Menus are an integral part of any website. Elgg defines two classes that help in building and rendering menus. The first class provided is ElggMenuItem. The second class provided is ElggMenuBuilder, which provide methods that help in rendering menus using the ElggMenuItem objects.
Adding Items to menu
Adding items to a menu requires:
- Create a plugin hook handler in your start.php
elgg_register_plugin_hook_handler('register', 'menu:<menu-name>', '<plugin callback>');
It is important to note that the plugin hook is ‘register’ so we are adding to something, while the entity is of type menu with a specific name. For example, in the default Elgg template the profile avatar contains a context menu. To add to the avatar menu a plugin developer will add a page handler for the hook ‘register’ and the menu type ‘user-hover’. So in this case the hook handler will be defined as:
elgg_register_plugin_hook_handler('register', 'menu:user_hover', '<callback function>');
- The next step is to implement the callback function using the function signature
function <callback function>($hook, $type, $menu_items, $params)
The most important parameter is the third parameter, $menu_items. In most cases the parameter will contain an array of menu items that have already been created by other plugins. If the plugin being created needs only to add new menu items, the menu items need to be appended to the variable $menu_items.
Context Menu for same menu
Using Elgg contexts it is possible to customize menus for a specific section of the site. Contexts are defined by calling the method
elgg_push_context('<context name>');
This method will add a new context on the context queue used for rendering pages. While within the context, the menu can be customized as desired for the plugin. When developing the function callback a plugin developer needs to check that the menu being created is within the custom context by calling the function elgg_get_context().
Example:
function my_new_menu_items($hook, $type, $menu_items, $params) {
$context = elgg_get_context();
if ($context == 'my context') {
$url = "admin";
$item = new ElggMenuItem(‘my menu item’, ‘Go to admin’, $url);
$item ->setSection('action');
$menu_items[] = $item;
}}
When creating contexts it is important to remove the context if no longer required. This is an important step to ensure that other plugins will not encounter issues due to the new context. As the contexts are stored into a queue, the function to remove a context is
elgg_pop_context();
Change rendering of a menu
Menus are normally rendered using a default rendering mechanism. Elgg allows plugin developers to hook into the rendering of menus to define their own requirements.
Plugin developers that need to change the rendering mechanism need to define a plugin hook for the ‘prepare’ stage of the menu rendering. Similar to the ‘register’ hook, the function call to hook into the preparation of menu rendering is
elgg_register_plugin_hook_handler('prepare', 'menu:<menu-name>', '<plugin callback>');
Conclusion
In Elgg it is possible to take full control of menus by hooking into the menu by registering a plugin for the creation of menus and preparation of menus for rendering.