Menu builders
In our menus recipe, we show how to build several types of menus with Kirby. However, those examples work with main pages and their children and have their limits when it comes to building more flexible menus where the depth of a page is not important or where you need multiple menus with selected pages.
In this recipe, we will look how we can build such custom menus where editors can pick the pages they want to include in a menu, or how we can even include external links.
In this recipe we assume that these menus are created in site.yml
, so that we use the $site
object when rendering them in the template. You can of course also use these menus in a page and adjust the template code accordingly.
Independent single level custom menu
The easiest way to create a custom menu from existing pages is the use of a pages field:
This setup can be used for a main menu, or for different single-level menus in the footer or in a sidebar.
In the template:
Multiple independent custom menus
The above works well if the required menus are known in advance, so that we can provide a field per menu.
In some cases, for example for a footer with multiple menus, we need some more flexibility. In such a case, where the number of menus can vary, a structure field is more useful.
In the template, we can use it like this to render each menu with its headline:
We loop through the structure items and create a new nav
tag for each menu. Inside the nav
tag, we render the title for each menu and the navigation items as a list.
Mixed menu I
What if we want mix external links with Kirby pages in our menu? We can also achieve this with a structure field.
Here, we show the pageLink
field to select a page if isExternal
is false, and the externalLink
field if isExternal
is set to true. For both types of links the editor can also set a custom title.
In the template:
In our template, we loop through all items and check if the provided link is a page or an URL. We render the title from the structure item if it is given, otherwise we fall back to the page title for a page link or to the shortened URL for external links.
Two-level custom menu
In our blueprint, we create a structure field with the following setup:
The structure field has a pages field for the first level of menu items, and a second conditional pages field for the submenu items that is only shown to editors if they set the hasSubmenu
toggle field to true
. The toggle field is not absolutely necessary but helps to keep the form concise.
The mainMenu
pages field is limited to max: 1
pages, whereas the subMenu
field can have multiple subpages.
We can now render this menu in the template like this:
First we check if our structure field contains items with $menu->isNotEmpty()
, because we don't want to render empty nav
tags.
We then loop through the structure items, and for each first level item we check if the stored value is actually a page.
For the second level menu items, we also check if the pages collection ($item->subMenu()->toPages()
) is empty, and only render the submenu if there are items.
If you need more menu levels, you can extend this example and nest another structure field inside the first level structure.
Mixed menu II
We can also combine this example with external links like in the example before.
Since our fields are repetive, we split them into two parts.
The first part is our nested menu structure field:
Inside this field, we reuse a group of fields we have defined in /site/blueprints/fields/menufields.yml
, because we need these 4 fields in both structure levels:
This example allows us to have conditional external links both on the first and on the second levels of the menu. Editors can also add an optional link title.
Let's see how we can handle this field definition in our template. To keep our code dry, we use a snippet inside the template:
Inside the snippet, we recursively call the snippet for the submenu items:
As always, this is just a basic collection of ideas that you can extend for your use cases. In the structure field examples, you could, for example, include additional fields for link attributes, like target: _blank
for those clients who absolutely want to open links in new tabs.
Instead of using conditional fields for page links vs. external links, you could also use the link field plugin.