Index: modules/menu/menu.api.php =================================================================== RCS file: /cvs/drupal/drupal/modules/menu/menu.api.php,v retrieving revision 1.11 diff -u -p -r1.11 menu.api.php --- modules/menu/menu.api.php 30 Sep 2009 13:09:29 -0000 1.11 +++ modules/menu/menu.api.php 30 Sep 2009 21:31:44 -0000 @@ -14,78 +14,143 @@ /** * 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". + * + * hook_menu() implementations return an associative array that contains again + * an associative array for each path. The definition for each path may refer to + * callback functions and may specify a list of arguments for each callback + * function as an array. These argument arrays may 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, when registering the path 'abc/def': + * @code + * $items['abc/def'] = array( + * 'page callback' => 'mymodule_abc_view', + * 'page arguments' => array(1), + * ); + * @endcode + * The integer 1 in an argument list will be replaced with 'def', and integer 0 + * would be replaced with 'abc' when the callback function is called. This + * allows to re-use a callback function for several different paths. + * + * Arguments may also be used to replace wildcards in 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 would be mymodule_abc_load() then. 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 passed additional arguments; see + * "load arguments" below. * - * This hook is called rarely - for example when modules are enabled. + * 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',