aboutsummaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorcash <cash@36083f99-b078-4883-b0ff-0f9b5a30f544>2011-03-26 22:06:28 +0000
committercash <cash@36083f99-b078-4883-b0ff-0f9b5a30f544>2011-03-26 22:06:28 +0000
commitc80487eb37d735f83e25c5cb86e504e2e4b66b76 (patch)
tree2c3b73708aab43b0e66f308adab080cf79d5dcd4
parentc91d28a163e75bdea02a9ddbc19649b06654da0d (diff)
downloadelgg-c80487eb37d735f83e25c5cb86e504e2e4b66b76.tar.gz
elgg-c80487eb37d735f83e25c5cb86e504e2e4b66b76.tar.bz2
Fixes #3026 documentation for menu system
git-svn-id: http://code.elgg.org/elgg/trunk@8857 36083f99-b078-4883-b0ff-0f9b5a30f544
-rw-r--r--engine/classes/ElggMenuBuilder.php4
-rw-r--r--engine/lib/navigation.php46
-rw-r--r--engine/lib/views.php19
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.