Menus!
 
DokuWiki's action plugins allow a wide range of new features to be integrated into DokuWiki. But one question users and developers often struggle with is: "How do I add my plugin's functionality to the user interface so it shows up on every page?".

The introduction of the sidebar combined with a simple syntax to trigger a certain functionality already solved this partially. The Feedback plugin offers such a syntax for example.

But what if you want to integrate your plugin into one of the existing menus?

In 2013 the TEMPLATE_PAGETOOLS_DISPLAY event was introduced. It allowed plugins to integrate themselves into the floating page tools menu of the DokuWiki default template. Other templates started to introduce the same event soon.

However that event was problematic from the start. It relied on the plugin author to provide button HTML that would fit into the HTML of the menu (as defined by the template). In addition the plugin had to provide appropriate CSS to style the button. It didn't help that the CSS for this floating menu was quite complicated.

In the end this event did not really solve the underlying problem. There was no way for plugin authors to integrate into templates without having to know the template's specifics.


Today, I merged a complete overhaul of how menus work. A description of the details can be found in the official documentation

Basically two new types of classes have been introduced: Menus and Items. An item class describes a certain type of interaction GUI element aka. a button or link.

For example, there is an Item called Recent - it describes all the info needed to construct a link to the recent changes. It says that the action to call is named 'recent', that pressing ALT-SHIFT-R should trigger the button, that there is an SVG called calendar-clock.svg that would be a fitting icon and so on. There is however absolutely no HTML or CSS in that class. It just describes what is available to build what ever kind of button or link you want for linking to the Recent Changes page.

And then there are Menus. We have multiple of those for the various types of actions we have. Theres a menu for all user related actions, one for wiki wide actions and there one for the page related actions.

The latter, called PageMenu would be the floating menu you know and love in the DokuWiki template. But again there is nothing in there that defines how this menu should look. There is nothing about it being a floating element.

A Menu just gives access to all Items that should be shown in this menu. But this is where we finally solve the initial problem. Each menu now emits the new MENU_ITEMS_ASSEMBLY event. You probably guessed it, this event lets plugin authors add their own custom Items to any of the predefined menus.

Template authors simply instantiate the Menus in their template and can then render and style them however they see fit. Any plugin provided Items will be automatically included and look exactly as the template designer intended.

To make this really useful though, templates need to integrate this new menu system. So if you're using a different template than the default one, open an issue in their bug tracker and ask them to integrate this.


Tier Benefits
Pledge $0 or more per month
patrons
Everyone
Recent Posts