Fixes #3026 documentation for menu system

git-svn-id: http://code.elgg.org/elgg/trunk@8857 36083f99-b078-4883-b0ff-0f9b5a30f544

3 files changed, 65 insertions, 4 deletions

diff --git a/engine/classes/ElggMenuBuilder.php b/engine/classes/ElggMenuBuilder.php
index 90ce4eb68..cadfee7f5 100644
--- a/engine/classes/ElggMenuBuilder.php
+++ b/engine/classes/ElggMenuBuilder.php
@@ -189,8 +189,8 @@ class ElggMenuBuilder {
 			case 'priority':
 				$sort_callback = array('ElggMenuBuilder', 'compareByWeight');
 				break;
-			case 'order':
-				// use registration order
+			case 'register':
+				// use registration order - usort breaks this
 				return;
 				break;
 			default:
diff --git a/engine/lib/navigation.php b/engine/lib/navigation.php
index 16cdf9d4c..91d0704eb 100644
--- a/engine/lib/navigation.php
+++ b/engine/lib/navigation.php
@@ -3,6 +3,45 @@
  * Elgg navigation library
  * Functions for managing menus and other navigational elements
  *
+ * Breadcrumbs
+ * Elgg uses a breadcrumb stack. The page handlers (controllers in MVC terms)
+ * push the breadcrumb links onto the stack. @see elgg_push_breadcrumb()
+ *
+ *
+ * Pagination
+ * Automatically handled by Elgg when using elgg_list_entities* functions.
+ * @see elgg_list_entities()
+ *
+ *
+ * Tabs
+ * @see navigation/tabs view
+ *
+ *
+ * Menus
+ * Elgg uses a single interface to manage its menus. Menu items are added with
+ * {@link elgg_register_menu_item()}. This is generally used for menus that
+ * appear only once per page. For context-sensitive menus (such as the hover
+ * menu for user's avatar), a plugin hook is emitted when the menu is being
+ * created. The hook is 'register', 'menu:<menu_name>'. For more details on this,
+ * @see elgg_view_menu().
+ *
+ * Menus supported by the Elgg core
+ * Standard menus:
+ *     site   Site navihgation shown on every page.
+ *     page   Page menu usually shown in a sidebar. Uses Elgg's context.
+ *     topbar Topbar menu shown on every page. The default has two sections.
+ *     footer Like the topbar but in the footer.
+ *     extras Links about content on the page. The RSS link is added to this.
+ *
+ * Context-sensitive (also called just-in-time menus):
+ *     user_hover  Avatar hover menu. The user entity is passed as a parameter.
+ *     entity      The set of links shown in the summary of an entity.
+ *     river       Links shown on river items.
+ *     owner_block Links shown for a user or group in their owner block.
+ *     filter      The tab filter for content (all, mine, friends)
+ *     title       The buttons shown next to a content title.
+ *     long-text   The links shown above the input/longtext view.
+ *
  * @package Elgg.Core
  * @subpackage Navigation
  */
@@ -10,6 +49,13 @@
 /**
  * Register an item for an Elgg menu
  *
+ * @warning Generally you should not use this in response to the plugin hook:
+ * 'register', 'menu:<menu_name>'. If you do, you may end up with many incorrect
+ * links on a context-sensitive menu.
+ *
+ * @see elgg_view_menu() for the plugin hooks available for modifying a menu as
+ * it is being rendered.
+ *
  * @param string $menu_name The name of the menu: site, page, userhover,
  *                          userprofile, groupprofile, or any custom menu
  * @param mixed  $menu_item A ElggMenuItem object or an array of options in format:
diff --git a/engine/lib/views.php b/engine/lib/views.php
index d3d790f8b..442f777f6 100644
--- a/engine/lib/views.php
+++ b/engine/lib/views.php
@@ -678,13 +678,28 @@ function elgg_view_layout($layout_name, $vars = array()) {
 /**
  * Render a menu
  *
+ * @see elgg_register_menu_item() for documentation on adding menu items and
+ * navigation.php for information on the different menus available.
+ *
+ * This function triggers a 'register', 'menu:<menu name>' plugin hook that enables
+ * plugins to add menu items just before a menu is rendered. This is used by
+ * context-sensitive menus (menus that are specific to a particular entity such
+ * as the user hover menu). Using elgg_register_menu_item() in response to the hook
+ * can cause incorrect links to show up. See the blog plugin's blog_owner_block_menu()
+ * for an example of using this plugin hook.
+ *
+ * An additional hook is the 'prepare', 'menu:<menu name>' which enables plugins
+ * to modify the structure of the menu (sort it, remove items, set variables on
+ * the menu items).
+ *
+ * elgg_view_menu() uses views in navigation/menu
+ *
  * @param string $menu_name The name of the menu
  * @param array  $vars      An associative array of display options for the menu.
  *                          Options include:
  *                              sort_by => string or php callback
- *                                  string options: 'name', 'title' (default), 'order' (registration order)
+ *                                  string options: 'name', 'priority', 'title' (default), 'register' (registration order)
  *                                  php callback: a compare function for usort
- *                                  priority: the order the items were registered
  *                              handler: string the page handler to build action URLs
  *                              entity: ElggEntity to use to build action URLs
  *                              class: string the class for the entire menu.