README

This Kirby CMS-Plugin lets you build and render structured menues with a variety of features.

Features

Custom deepness
Custom HTML-Tags for root- & child-nodes
Custom CSS-Classes for active- & descendant nodes
Custom HTML-Attributes/Values for each node
Custom user-roles for displaying each node
- Custom default roles for new nodes
Usable as a standalone field and a block
- Block is extendable with own tabs
All types of the "link"-field can be added as nodes
- Disclaimer: active- & descendant nodes can only be detected for internal Kirby-Pages

Current translations

English
German

Prerequisites

Kirby 4.3+

Installation

Download

Download and copy this repository to /site/plugins/kirby-menu.

Git submodule

git submodule add https://github.com/swiegmann/kirby-menu.git site/plugins/kirby-menu

Composer

composer require swiegmann/kirby-menu

Usage

Field

Add the field to a site- or page-blueprint:
```
fields:
  yourfieldname:
    extends: fields/menu
```
Note: This is a structure-field. You can overwrite some reasonable properties like label or required. See Structure Field Properties on the Kirby Site.
The backend shows a structure-field where you added it. Add an entry. [click (+) to add]. Every entry is a full menu. Every menu needs a unique internal key, e.g.: "meta", which is later needed to render the menu in your snippet. Add some nodes and save.
The generic Kirby-Method to render the menu in your snippet is:
```
echo $site->menu($field, 'yourmenukey');
```
... where $field is of type Kirby\Content\Field.

In my setup I have added the field menues to site.yml and created an entry with the internal key meta. This is how the part in my header-snippet looks like:
```
<?= $site->menu($site->content()->get('menues'), 'meta') ?>
```

Block

Add the block to a layout/block-blueprint, e.g:

fields:
  yourfieldname:
    type: blocks
    fieldsets:
      - menu

Add a new block of 'menu' in your layout/block-field. [click (+) to add] Continue adding some nodes and save.

HTML sample-result (exemplary)

<ul>
  <li>
    <a href="https://domain.com">Home</a>
  </li>
  <li class="active-desc">
    <a href="https://domain.com/news">News</a>
    <ul>
      <li class="active">
        <a href="https://domain.com/news/technology" aria-current="page">Technology</a>
      </li>
      <li id="meta-culture">
        <a href="https://domain.comn/news/culture">Culture</a>
      </li>
      <li id="meta-world" class="important" data-something>
        <a href="https://domain.com/news/world">World</a>
      </li>
    </ul>
  <li>
</ul>

Global Configuration

Configure global settings in your config.php file:

return [
  'swiegmann.menu' => [
    'activeDescPageCssClass' => 'active-desc',
    'activePageCssClass' => 'active',
    'deepness' => '3',
    'defaultRoleKeys' => [],
    'listEntryTag' => 'li',
    'listTag' => 'ul',
    'visitorRoleKey' => 'visitor'
  ]
];

Option	Default	Type	Description
`activeDescPageCssClass`	`active-desc`	String	CSS-Class for nodes of active child-nodes
`activePageCssClass`	`active`	String	CSS-Class for active nodes
`deepness`	`3`	Integer	maximum deepness
`defaultRoleKeys`	`[]`	Array	List of (user-) role-keys that get default view-privilegues, e.g. `['admin', editor', 'visitor']`. Empty = all roles
`listEntryTag`	`li`	String	HTML-Tag for a node
`listTag`	`ul`	String	HTML-Tag for (level-) roots
`visitorRoleKey`	`visitor`	String	Role-key of visitors. Can be either a Kirby role-key (if you created a visitor-role in your setup) or another string

Customize snippets

Copy the snippet-files from:

/site/plugins/kirby-menu/snippets

to:

/site/snippets

and apply your own logic.

Add own tabs to the block

Copy the blueprint-file from:

/site/plugins/kirby-menu/blueprints/blocks/menu.yml

to:

/site/blueprints/blocks

and add your own tabs to the blueprint.

swiegmann / kirby-menu

Maintainers

Details