From c80487eb37d735f83e25c5cb86e504e2e4b66b76 Mon Sep 17 00:00:00 2001 From: cash Date: Sat, 26 Mar 2011 22:06:28 +0000 Subject: Fixes #3026 documentation for menu system git-svn-id: http://code.elgg.org/elgg/trunk@8857 36083f99-b078-4883-b0ff-0f9b5a30f544 --- engine/classes/ElggMenuBuilder.php | 4 ++-- engine/lib/navigation.php | 46 ++++++++++++++++++++++++++++++++++++++ engine/lib/views.php | 19 ++++++++++++++-- 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:'. 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:'. 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:' 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:' 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. -- cgit v1.2.3