Kirby Collections and Navigation

KB entry points

• kirby://kb/scenarios/07-pagination

• kirby://kb/scenarios/08-search-page

• kirby://kb/scenarios/09-filtering-with-tags

• kirby://kb/scenarios/11-navigation-menus

• kirby://kb/scenarios/23-collections-filtering

Required inputs

• Collection source (page/section/template or ids).
• Filters, sort order, and pagination size.
• Target templates/snippets and UI expectations.

Default pattern

• Keep collection building in the controller; return a single

  items

  collection and

  pagination

  .
• Render items via a snippet to avoid repeated template logic.
• Provide empty-state and active-navigation UI.
• Default sort: use

  date desc

  when the field exists; otherwise fall back to

  title asc

  .

Example

Controller:

return function ($page) {
  $items = $page->children()->listed()->sortBy('date', 'desc')->paginate(10);
  return [
    'items' => $items,
    'pagination' => $items->pagination(),
  ];
};

Snippet:

<?php if ($items->isEmpty()): ?>
  <p>No items yet.</p>
<?php else: ?>
  <?php foreach ($items as $item): ?>
    <!-- render item -->
  <?php endforeach ?>
  <?php snippet('pagination', ['pagination' => $pagination]) ?>
<?php endif ?>

Output checklist

• Ensure pagination URLs preserve filters and tags.
• Render empty states without PHP notices.
• Confirm active navigation matches the current page.

Common pitfalls

• Dropping query params or tag filters on pagination links.
• Implementing heavy collection logic in templates instead of controllers.

Workflow

1. Clarify collection scope (site vs section), filters, sort order, and UI (pagination, tag filters, menu style).
2. Call

   kirby:kirby_init

   and read

   kirby://roots

   .
3. Inspect existing templates/controllers/snippets to reuse patterns:

   • kirby:kirby_templates_index

   • kirby:kirby_controllers_index

   • kirby:kirby_snippets_index

4. Prefer controllers for collection logic; keep templates thin.
5. Search the KB with

   kirby:kirby_search

   for task playbooks (examples: "pagination", "search page", "filtering with tags", "navigation menus", "collections filtering").
6. Implement or adjust collection queries; add snippets for repeated UI.
7. Verify rendering and pagination URLs with

   kirby:kirby_render_page(noCache=true)

   .