diff options
author | Dries Buytaert <dries@buytaert.net> | 2009-10-02 00:44:22 +0000 |
---|---|---|
committer | Dries Buytaert <dries@buytaert.net> | 2009-10-02 00:44:22 +0000 |
commit | 04b6c362849b61200c8f220141d8836a42acbb21 (patch) | |
tree | 460bee559ec9f52b3759097ea9f56f118c797b3c /modules/menu | |
parent | e673ae5b9b83efbf84452a0c34499e0fa9523e07 (diff) | |
download | brdo-04b6c362849b61200c8f220141d8836a42acbb21.tar.gz brdo-04b6c362849b61200c8f220141d8836a42acbb21.tar.bz2 |
- Patch #382834 by jhodgdon, sun: documentation improvements for hook_menu() API
Diffstat (limited to 'modules/menu')
-rw-r--r-- | modules/menu/menu.api.php | 164 |
1 files changed, 136 insertions, 28 deletions
diff --git a/modules/menu/menu.api.php b/modules/menu/menu.api.php index d64f9b34c..3b1c7bdf6 100644 --- a/modules/menu/menu.api.php +++ b/modules/menu/menu.api.php @@ -14,78 +14,186 @@ /** * Define menu items and page callbacks. * - * This hook enables modules to register paths, which determines whose - * requests are to be handled. Depending on the type of registration - * requested by each path, a link is placed in the the navigation block and/or - * an item appears in the menu administration page (q=admin/menu). + * This hook enables modules to register paths in order to define how URL + * requests are handled. Paths may be registered for URL handling only, but can + * also register a link to be placed in a menu (usually the Navigation menu). A + * path and its associated information is commonly called a "menu router item". * - * This hook is called rarely - for example when modules are enabled. + * hook_menu() implementations return an associative array whose keys define + * paths and whose values are an associative array defining properties for each + * path. The definition for each path may refer to a callback function that is + * invoked when the registered path is requested. In case there is no other + * registered path that fits the requested path better, any further path + * components are optionally passed to the callback function by default. + * For example, when registering the path 'abc/def': + * @code + * function mymodule_menu() { + * $items['abc/def'] = array( + * 'page callback' => 'mymodule_abc_view', + * ); + * } + * + * function mymodule_abc_view($ghi = 0, $jkl = '') { + * // ... + * } + * @endcode + * When the path 'abc/def' was requested, then no further arguments would be + * passed to the callback function, so $ghi and $jkl would take the default + * values as defined in the function signature. + * In case 'abc/def/123/foo' was requested, then $ghi would be '123' and $jkl + * would be 'foo'. + * + * In addition to optional path arguments, the definition for each path may + * specify a list of arguments for each callback function as an array. These + * argument lists may contain fixed/hard-coded argument values, but may also + * contain integers that correspond to path components. When integers are used + * and the callback function is called, the corresponding path components will + * be substituted. For example: + * @code + * function mymodule_menu() { + * $items['abc/def'] = array( + * 'page callback' => 'mymodule_abc_view', + * 'page arguments' => array(1, 'foo'), + * ); + * } + * @endcode + * When the path 'abc/def' was requested, the callback function would get 'def' + * as first argument and (always) 'foo' as second argument. + * The integer 1 in an argument list would be replaced with 'def' and integer 0 + * would be replaced with 'abc', i.e. path components are counted from zero. + * This allows to re-use a callback function for several different paths. + * + * Arguments may also be used to replace wildcards within paths. For example, + * when registering the path 'my-module/%/edit': + * @code + * $items['my-module/%/edit'] = array( + * 'page callback' => 'mymodule_abc_edit', + * 'page arguments' => array(1), + * ); + * @endcode + * When the path 'my-module/foo/edit' is requested, then integer 1 will be + * replaced with 'foo' and passed to the callback function. + * + * Registered paths may also contain special "auto-loader" wildcard components + * in the form of '%mymodule_abc', where the '%' part means that this path + * component is a wildcard, and the 'mymodule_abc' part defines the prefix for a + * menu argument loader function, which here would be mymodule_abc_load(). + * For example, when registering the path 'my-module/%mymodule_abc/edit': + * @code + * $items['my-module/%mymodule_abc/edit'] = array( + * 'page callback' => 'mymodule_abc_edit', + * 'page arguments' => array(1), + * ); + * @endcode + * When the path 'my-module/123/edit' is requested, then the argument loader + * function mymodule_abc_load() will be invoked with the argument '123', and it + * is supposed to take that value to load and return data for "abc" having the + * internal id 123: + * @code + * function mymodule_abc_load($abc_id) { + * return db_query("SELECT * FROM {mymodule_abc} WHERE abc_id = :abc_id", array(':abc_id' => $abc_id))->fetchObject(); + * } + * @endcode + * The returned data of the argument loader will be passed in place of the + * original path component to all callback functions referring to that (integer) + * component in their argument list. + * Menu argument loader functions may also be passed additional arguments; see + * "load arguments" below. + * + * If a registered path defines an argument list, then those defined arguments + * will always be passed first to the callback function. In case there are any + * further components contained in the requested path, then those will always + * come last. + * + * Special care should be taken for the page callback drupal_get_form(), because + * the callback function will always receive $form and &$form_state as the very + * first function arguments: + * @code + * function mymodule_abc_form($form, &$form_state) { + * // ... + * return $form; + * } + * @endcode + * See @link form_api Form API documentation @endlink for details. + * + * This hook is rarely called (for example, when modules are enabled), and + * its results are cached in the database. * * @return * An array of menu items. Each menu item has a key corresponding to the - * Drupal path being registered. The item is an associative array that may - * contain the following key-value pairs: + * Drupal path being registered. The corresponding array value is an + * associative array that may contain the following key-value pairs: * - "title": Required. The untranslated title of the menu item. - * - "title callback": Function to generate the title, defaults to t(). + * - "title callback": Function to generate the title; defaults to t(). * If you require only the raw string to be output, set this to FALSE. - * - "title arguments": Arguments to send to t() or your custom callback. + * - "title arguments": Arguments to send to t() or your custom callback, + * with path component substitution as described above. * - "description": The untranslated description of the menu item. * - "page callback": The function to call to display a web page when the user * visits the path. If omitted, the parent menu item's callback will be used * instead. * - "page arguments": An array of arguments to pass to the page callback - * function. Integer values pass the corresponding URL component (see arg()). - * - "access callback": A function returning a boolean value that determines + * function, with path component substitution as described above. + * - "access callback": A function returning a boolean value that determines * whether the user has access rights to this menu item. Defaults to * user_access() unless a value is inherited from a parent menu item. * - "access arguments": An array of arguments to pass to the access callback - * function. Integer values pass the corresponding URL component. + * function, with path component substitution as described above. * - "theme callback": Optional. A function returning the machine-readable * name of the theme that will be used to render the page. If the function * returns nothing, the main site theme will be used. If no function is * provided, the main site theme will also be used, unless a value is * inherited from a parent menu item. * - "theme arguments": An array of arguments to pass to the theme callback - * function. Integer values pass the corresponding URL component. + * function, with path component substitution as described above. * - "file": A file that will be included before the callbacks are accessed; * this allows callback functions to be in separate files. The file should * be relative to the implementing module's directory unless otherwise - * specified by the "file path" option. + * specified by the "file path" option. Note: This does not apply to the + * 'access callback'. * - "file path": The path to the folder containing the file specified in * "file". This defaults to the path to the module implementing the hook. * - "load arguments": An array of arguments to be passed to each of the - * object loaders in the path. For example, for the router item at - * node/%node/revisions/%/view, the array(1, 3) will call node_load() with - * the arguments corresponding to the second and fourth URL argument; - * as with other arguments, integers are automatically cast to URL - * arguments. There are also two "magic" values: "%index" will correspond - * to the URL index where the object's load function is specified; "%map" - * will correspond to the full menu map, passed in by reference to the - * load function. - * - "weight": An integer that determines relative position of items in the - * menu; higher-weighted items sink. Defaults to 0. When in doubt, leave + * wildcard object loaders in the path. For example, for the path + * node/%node/revisions/%/view, a "load arguments" value of array(1, 3) will + * call node_load() with the second and fourth path components passed in (as + * described above, integers are automatically replaced with path + * components). There are also two "magic" values: "%index" will correspond + * to the index of the wildcard path component, and "%map" will correspond + * to the full menu map, passed in by reference. + * - "weight": An integer that determines the relative position of items in + * the menu; higher-weighted items sink. Defaults to 0. When in doubt, leave * this alone; the default alphabetical order is usually best. * - "menu_name": Optional. Set this to a custom menu if you don't want your * item to be placed in Navigation. + * - "tab_parent": For local task menu items, the path of the task's parent + * item; defaults to the same path without the last component (e.g., the + * default parent for 'admin/people/create' is 'admin/people'). + * - "tab_root": For local task menu items, the path of the closest non-tab + * item; same default as "tab_parent". + * - "block callback": Name of a function used to render the block on the + * system administration page for this item (called with no arguments). + * If not provided, system_admin_menu_block() is used to generate it. + * - "position": Position of the block ('left' or 'right') on the system + * administration page for this item. * - "type": A bitmask of flags describing properties of the menu item. * Many shortcut bitmasks are provided as constants in menu.inc: * - MENU_NORMAL_ITEM: Normal menu items show up in the menu tree and can be * moved/hidden by the administrator. * - MENU_CALLBACK: Callbacks simply register a path so that the correct - * function is fired when the URL is accessed. + * function is fired when the path is accessed. * - MENU_SUGGESTED_ITEM: Modules may "suggest" menu items that the * administrator may enable. * - MENU_LOCAL_TASK: Local tasks are rendered as tabs by default. * - MENU_DEFAULT_LOCAL_TASK: Every set of local tasks should provide one * "default" task, that links to the same path as its parent when clicked. - * If the "type" key is omitted, MENU_NORMAL_ITEM is assumed. + * If the "type" element is omitted, MENU_NORMAL_ITEM is assumed. + * * For a detailed usage example, see page_example.module. * For comprehensive documentation on the menu system, see * http://drupal.org/node/102338. */ function hook_menu() { - $items = array(); - $items['blog'] = array( 'title' => 'blogs', 'page callback' => 'blog_page', |