- Patch #382834 by jhodgdon, sun: documentation improvements for hook_menu() API

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',