====== Menus ======

Menus are an important part of a template. They provide access to the wiki's functionality aka. actions. E.g., they may provide a button or link to edit the current page, access recent changes or offer to export a PDF.

[[:DokuWiki]] groups these actions into different menus which can be inserted into a template at different positions.

There is also an [[https://www.patreon.com/posts/menus-14160215|introductory blog post]] available.

===== Available Menus =====

^ view    ^ Source ^ Description ^
| ''site'' | [[gh>inc/Menu/SiteMenu.php|SiteMenu]] | defines all wiki wide actions, e.g. actions not related to one page. Examples: Recent Changes, Sitemap) |
| ''user'' | [[gh>inc/Menu/UserMenu.php|UserMenu]] | defines the actions related to the current user. Examples: Login, Admin |
| ''page'' | [[gh>inc/Menu/PageMenu.php|PageMenu]] | defines the action related to the current page. Examples: Edit, Show old Revisions |
| ''detail'' | [[gh>inc/Menu/DetailMenu.php|DetailMenu]] | similar to the Page Menu but related to an image when shown in the Detail view |
| | [[gh>inc/Menu/MobileMenu.php|MobileMenu]] | combines all items from Site, User and Page menu when they are allowed to be shown in mobile context. Useful to create a single [[wp>Hamburger_button|hamburger menu]]. |

Plugins can extend and modify the above menus using the [[devel:event:MENU_ITEMS_ASSEMBLY]] event.

===== Menu Items =====

Menus consist of Menu items - objects inheriting from [[gh>inc/Menu/Item/AbstractItem.php|AbstractItem.php]]. A menu item configures a few properties which the template may use to display this item. This includes, the action to trigger, a label, an SVG icon and few more. Please refer to the [[gh>inc/Menu/Item/AbstractItem.php|source]] on what properties are available.

Plugins can create their own Items and add them to the available menus using the [[devel:event:MENU_ITEMS_ASSEMBLY]] event.

=== Icon ===

The icon returned by the ''getSVG()'' method and set in the ''$svg'' property needs to adhere to the following restrictions:

  * It has to be in SVG format
  * The file has to be smaller than 2KB
  * It should only contain a single path object

The fill color of the path will be set by the template's CSS when used.

To match the style of other icons, it is recommended to either pick an icon from the huge, free selection at https://materialdesignicons.com/ or adhere to the [[https://material.io/guidelines/style/icons.html|Material Design Guidelines]] when designing your own icon.

===== Adding Menus to Templates =====

The menus mentioned above by instantiating them and either use one of the convenience methods or simply call ''getItems()'' and iterate over the item objects.

Example: to integrate the UserMenu as list of links use this:

<code php>
echo (new \dokuwiki\Menu\UserMenu())->getListItems();
</code>

A mobile dropdown menu can be added like this:

<code php>
echo (new \dokuwiki\Menu\MobileMenu())->getDropdown();
</code>

Please refer to the [[gh>inc/Menu/AbstractMenu.php|source]] for what else is available.

If you need specific HTML for menu items, you need to loop over the menu items and create the HTML
yourself. For example, this loop would create the icons in the [[:template:writr|writr template]], which is a bit more complex:

<code php>
$items = (new \dokuwiki\Menu\PageMenu())->getItems();
foreach($items as $item) {
  echo '<li>'
      .'<a href="'.$item->getLink().'" title="'.$item->getTitle().'">'
      .'<span class="icon">'.inlineSVG($item->getSvg()).'</span>'
      . '<span class="a11y">'.$item->getLabel().'</span>'
      . '</a></li>';
}
</code>

===== Legacy Support =====

With the introduction of the menu system, the following functions were deprecated. Template and plugin authors should make sure to replace them soon:

  * ''tpl_button()''
  * ''tpl_actionlink()''
  * ''tpl_get_action()''
  * ''tpl_actiondropdown()''
  * ''tpl_toolsevent()''