kirby-collections-and-navigation

name	kirby-collections-and-navigation
description	Builds Kirby listings, pagination, search, filtering/sorting/grouping, and navigation menus. Use when implementing collection logic in templates/controllers/snippets.

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).