menus.rst 5.6 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200
  1. Menus
  2. #####
  3. Elgg contains helper code to build menus throughout the site.
  4. Every single menu requires a name, as does every single menu item. These are
  5. required in order to allow easy overriding and manipulation, as well as to
  6. provide hooks for theming.
  7. .. contents:: Contents
  8. :local:
  9. :depth: 1
  10. Basic usage
  11. ===========
  12. Basic functionalities can be achieved through these two functions:
  13. - `elgg_register_menu_item()`__ to add an item to a menu
  14. - `elgg_unregister_menu_item()`__ to remove an item from a menu
  15. You normally want to call them from your plugin's init function.
  16. __ http://reference.elgg.org/engine_2lib_2navigation_8php.html#a344445364078d03607904c44bad36c1c
  17. __ http://reference.elgg.org/engine_2lib_2navigation_8php.html#ae26ee09e330a130984c9a6f9e19f6546
  18. Examples
  19. --------
  20. .. code-block:: php
  21. // Add a new menu item to the site main menu
  22. elgg_register_menu_item('site', array(
  23. 'name' => 'itemname',
  24. 'text' => 'This is text of the item',
  25. 'href' => '/item/url',
  26. ));
  27. .. code:: php
  28. // Remove the "Elgg" logo from the topbar menu
  29. elgg_unregister_menu_item('topbar', 'elgg_logo');
  30. Advanced usage
  31. ==============
  32. You can get more control over menus by using :doc:`plugin hooks </design/events>`
  33. and the public methods provided by the ElggMenuItem__ class.
  34. There are two hooks that can be used to modify a menu:
  35. - ``'register', 'menu:<menu name>'`` to add or modify items (especially in dynamic menus)
  36. - ``'prepare', 'menu:<menu name>'`` to modify the structure of the menu before it is displayed
  37. When you register a plugin hook handler, replace the ``<menu name>`` part with the
  38. internal name of the menu.
  39. The third parameter passed into a menu handler contains all the menu items that
  40. have been registered so far by Elgg core and other enabled plugins. In the
  41. handler we can loop through the menu items and use the class methods to
  42. interact with the properties of the menu item.
  43. __ http://reference.elgg.org/classElggMenuItem.html
  44. Examples
  45. --------
  46. **Example 1:** Change the URL for menu item called "albums" in the ``owner_block`` menu:
  47. .. code-block:: php
  48. /**
  49. * Initialize the plugin
  50. */
  51. function my_plugin_init() {
  52. // Register a plugin hook handler for the owner_block menu
  53. elgg_register_plugin_hook_handler('register', 'menu:owner_block', 'my_owner_block_menu_handler');
  54. }
  55. /**
  56. * Change the URL of the "Albums" menu item in the owner_block menu
  57. */
  58. function my_owner_block_menu_handler($hook, $type, $menu, $params) {
  59. $owner = $params['entity'];
  60. // Owner can be either user or a group, so we
  61. // need to take both URLs into consideration:
  62. switch ($owner->getType()) {
  63. case 'user':
  64. $url = "album/owner/{$owner->guid}";
  65. break;
  66. case 'group':
  67. $url = "album/group/{$owner->guid}:
  68. break;
  69. }
  70. foreach ($menu as $key => $item) {
  71. if ($item->getName() == 'albums') {
  72. // Set the new URL
  73. $item->setURL($url);
  74. break;
  75. }
  76. }
  77. return $menu;
  78. }
  79. **Example 2:** Modify the ``entity`` menu for the ``ElggBlog`` objects
  80. - Remove the thumb icon
  81. - Change the "Edit" text into a custom icon
  82. .. code-block:: php
  83. /**
  84. * Initialize the plugin
  85. */
  86. function my_plugin_init() {
  87. // Register a plugin hook handler for the entity menu
  88. elgg_register_plugin_hook_handler('register', 'menu:entity', 'my_entity_menu_handler');
  89. }
  90. /**
  91. * Customize the entity menu for ElggBlog objects
  92. */
  93. function my_entity_menu_handler($hook, $type, $menu, $params) {
  94. // The entity can be found from the $params parameter
  95. $entity = $params['entity'];
  96. // We want to modify only the ElggBlog objects, so we
  97. // return immediately if the entity is something else
  98. if (!$entity instanceof ElggBlog) {
  99. return $menu;
  100. }
  101. foreach ($menu as $key => $item) {
  102. switch ($item->getName()) {
  103. case 'likes':
  104. // Remove the "likes" menu item
  105. unset($menu[$key]);
  106. break;
  107. case 'edit':
  108. // Change the "Edit" text into a custom icon
  109. $item->setText(elgg_view_icon('pencil'));
  110. break;
  111. }
  112. }
  113. return $menu;
  114. }
  115. Creating a new menu
  116. ===================
  117. Elgg provides multiple different menus by default. Sometimes you may however
  118. need some menu items that don't fit in any of the existing menus.
  119. If this is the case, you can create your very own menu with the
  120. `elgg_view_menu()`__ function. You must call the function from the view,
  121. where you want to menu to be displayed.
  122. __ http://reference.elgg.org/views_8php.html#ac2d475d3efbbec30603537013ac34e22
  123. **Example:** Display a menu called "my_menu" that displays it's menu items
  124. in alphapetical order:
  125. .. code-block:: php
  126. echo elgg_view_menu('my_menu', array('sort_by' => 'title'));
  127. You can now add new items to the menu like this:
  128. .. code-block:: php
  129. elgg_register_menu_item('my_menu', array(
  130. 'name' => 'my_page',
  131. 'href' => 'path/to/my_page',
  132. 'text' => elgg_echo('my_plugin:my_page'),
  133. ));
  134. Furthermore it is now possible to modify the menu using the hooks
  135. ``'register', 'menu:my_menu'`` and ``'prepare', 'menu:my_menu'``.
  136. Theming
  137. =======
  138. The menu name, section names, and item names are all embedded into the HTML as
  139. CSS classes (normalized to contain only hyphens, rather that underscores or
  140. colons). This increases the size of the markup slightly but provides themers
  141. with a high degree of control and flexibility when styling the site.
  142. **Example:** The following would be the output of the ``foo`` menu with sections
  143. ``alt`` and ``default`` containing items ``baz`` and ``bar`` respectively.
  144. .. code-block:: html
  145. <ul class="elgg-menu elgg-menu-foo elgg-menu-foo-alt">
  146. <li class="elgg-menu-item elgg-menu-item-baz"></li>
  147. </ul>
  148. <ul class="elgg-menu elgg-menu-foo elgg-menu-foo-default">
  149. <li class="elgg-menu-item elgg-menu-item-bar"></li>
  150. </ul>