DokuWiki

It's better when it's simple

User Tools

Site Tools


devel:menus

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 introductory blog post available.

Available Menus

view Source Description
site SiteMenu defines all wiki wide actions, e.g. actions not related to one page. Examples: Recent Changes, Sitemap)
user UserMenu defines the actions related to the current user. Examples: Login, Admin
page PageMenu defines the action related to the current page. Examples: Edit, Show old Revisions
detail DetailMenu similar to the Page Menu but related to an image when shown in the Detail view
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 hamburger menu.

Plugins can extend and modify the above menus using the MENU_ITEMS_ASSEMBLY event.

Menus consist of Menu items - objects inheriting from 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 source on what properties are available.

Plugins can create their own Items and add them to the available menus using the 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 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:

echo (new \dokuwiki\Menu\UserMenu())->getListItems();

A mobile dropdown menu can be added like this:

echo (new \dokuwiki\Menu\MobileMenu())->getDropdown();

Please refer to the 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 writr template, which is a bit more complex:

$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>';
}

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()
devel/menus.txt · Last modified: 2019-05-06 22:23 by daumling

Except where otherwise noted, content on this wiki is licensed under the following license: CC Attribution-Share Alike 4.0 International
CC Attribution-Share Alike 4.0 International Donate Powered by PHP Valid HTML5 Valid CSS Driven by DokuWiki