kirby-collections-and-navigation
Builds Kirby listings, pagination, search, filtering/sorting/grouping, and navigation menus. Use when implementing collection logic in templates/controllers/snippets.
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.
| 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-paginationkirby://kb/scenarios/08-search-pagekirby://kb/scenarios/09-filtering-with-tagskirby://kb/scenarios/11-navigation-menuskirby://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
itemscollection andpagination. - Render items via a snippet to avoid repeated template logic.
- Provide empty-state and active-navigation UI.
- Default sort: use
date descwhen the field exists; otherwise fall back totitle 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
- Clarify collection scope (site vs section), filters, sort order, and UI (pagination, tag filters, menu style).
- Call
kirby:kirby_initand readkirby://roots. - Inspect existing templates/controllers/snippets to reuse patterns:
kirby:kirby_templates_indexkirby:kirby_controllers_indexkirby:kirby_snippets_index
- Prefer controllers for collection logic; keep templates thin.
- Search the KB with
kirby:kirby_searchfor task playbooks (examples: "pagination", "search page", "filtering with tags", "navigation menus", "collections filtering"). - Implement or adjust collection queries; add snippets for repeated UI.
- Verify rendering and pagination URLs with
kirby:kirby_render_page(noCache=true).