kirby-collections-and-navigation

bnomei's avatarfrom bnomei

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

⭐17stars🔀0forks📁View on GitHub🕐Updated Jan 10, 2026⬇️2downloads

When & Why to Use This Skill

This Claude skill automates the development of Kirby CMS collections and navigation systems. It streamlines the creation of dynamic listings, complex pagination, robust search functionality, and intuitive navigation menus by implementing best-practice controller and template logic, ensuring high-performance and maintainable code for Kirby-based websites.

Use Cases

  • Building a paginated blog or news index with custom sorting by date and category.
  • Implementing a site-wide search page that correctly handles query parameters and empty states.
  • Creating dynamic, multi-level navigation menus that automatically highlight the active page state.
  • Developing complex filtering systems for product catalogs or portfolios using tags and custom metadata.
  • Refactoring heavy template logic into Kirby controllers to improve code maintainability and performance.
namekirby-collections-and-navigation
descriptionBuilds 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).