diff --git a/core/includes/menu.inc b/core/includes/menu.inc index 6abab20..47e1103 100644 --- a/core/includes/menu.inc +++ b/core/includes/menu.inc @@ -19,17 +19,38 @@ use Symfony\Component\Routing\Route; /** - * @defgroup menu Menu system + * @defgroup menu Menu and routing system * @{ * Define the navigation menus, and route page requests to code based on URLs. * - * The Drupal menu system drives both the navigation system from a user - * perspective and the callback system that Drupal uses to respond to URLs - * passed from the browser. For this reason, a good understanding of the - * menu system is fundamental to the creation of complex modules. As a note, - * this is related to, but separate from menu.module, which allows menus - * (which in this context are hierarchical lists of links) to be customized from - * the Drupal administrative interface. + * The Drupal routing system defines how Drupal responds to URLs passed to the + * browser. The menu system, which depends on the routing system, is used for + * navigation. The Menu module allows menus to be created in the user interface + * as hierarchical lists of links. + * + * @section registering_paths Registering router paths + * To register a path, you need to add lines similar to this in a + * module.routing.yml file: + * @code + * block.admin_display: + * path: '/admin/structure/block' + * defaults: + * _content: '\Drupal\block\Controller\BlockListController::listing' + * requirements: + * _permission: 'administer blocks' + * @endcode + * @todo Add more information here, especially about controllers and what all + * the stuff in the routing.yml file means. + * + * @section Defining menu links + * Once you have a route defined, you can use hook_menu() to define links + * for your module's paths in the main Navigation menu or other menus. See + * the hook_menu() documentation for more details. + * + * @todo The rest of this topic has not been reviewed or updated for Drupal 8.x + * and is not correct! + * @todo It is quite likely that hook_menu() will be replaced with a different + * hook, configuration system, or plugin system before the 8.0 release. * * Drupal's menu system follows a simple hierarchy defined by paths. * Implementations of hook_menu() define menu items and assign them to diff --git a/core/modules/system/system.api.php b/core/modules/system/system.api.php index abda14e..0d9b5be 100644 --- a/core/modules/system/system.api.php +++ b/core/modules/system/system.api.php @@ -49,13 +49,13 @@ function hook_hook_info() { /** * Define administrative paths. * - * Modules may specify whether or not the paths they define in hook_menu() are + * Modules may specify whether or not the routing paths they define are * to be considered administrative. Other modules may use this information to * display those pages differently (e.g. in a modal overlay, or in a different * theme). * * To change the administrative status of menu items defined in another module's - * hook_menu(), modules should implement hook_admin_paths_alter(). + * routing paths, modules should implement hook_admin_paths_alter(). * * @return * An associative array. For each item, the key is the path in question, in @@ -63,7 +63,6 @@ function hook_hook_info() { * be TRUE (for paths considered administrative) or FALSE (for non- * administrative paths). * - * @see hook_menu() * @see drupal_match_path() * @see hook_admin_paths_alter() */ @@ -491,51 +490,23 @@ function hook_menu_get_item_alter(&$router_item, $path, $original_map) { } /** - * Define menu items and page callbacks. - * - * This hook enables modules to register paths in order to define how URL - * requests are handled. Paths may be registered for URL handling only, or they - * can register a link to be placed in a menu (usually the Tools menu). A - * path and its associated information is commonly called a "menu router item". - * This hook is rarely called (for example, when modules are enabled), and - * its results are cached in the database. - * - * hook_menu() implementations return an associative array whose keys define - * paths and whose values are an associative array of properties for each - * path. (The complete list of properties is in the return value section below.) + * Define links for menus. * - * @section sec_render_tabs Rendering Menu Items As Tabs - * You can also make groups of menu items to be rendered (by default) as tabs - * on a page. To do that, first create one menu item of type MENU_NORMAL_ITEM, - * with your chosen path, such as 'foo'. Then duplicate that menu item, using a - * subdirectory path, such as 'foo/tab1', and changing the type to - * MENU_DEFAULT_LOCAL_TASK to make it the default tab for the group. Then add - * the additional tab items, with paths such as "foo/tab2" etc., with type - * MENU_LOCAL_TASK. Example: + * @section sec_menu_link Creating Menu Items + * Menu item example of type MENU_NORMAL_ITEM: * @code * // Make "Foo settings" appear on the admin Config page * $items['admin/config/system/foo'] = array( * 'title' => 'Foo settings', * 'type' => MENU_NORMAL_ITEM, - * // Page callback, etc. need to be added here. - * ); - * // Make "Tab 1" the main tab on the "Foo settings" page - * $items['admin/config/system/foo/tab1'] = array( - * 'title' => 'Tab 1', - * 'type' => MENU_DEFAULT_LOCAL_TASK, - * // Access callback, page callback, and theme callback will be inherited - * // from 'admin/config/system/foo', if not specified here to override. - * ); - * // Make an additional tab called "Tab 2" on "Foo settings" - * $items['admin/config/system/foo/tab2'] = array( - * 'title' => 'Tab 2', - * 'type' => MENU_LOCAL_TASK, - * // Page callback and theme callback will be inherited from - * // 'admin/config/system/foo', if not specified here to override. - * // Need to add access callback or access arguments. + * 'route_name' => 'foo.settings' * ); * @endcode * + * @todo The section that used to be here about path argument substitution has + * been removed, but is still referred to in the return section. It needs to + * be added back in, or a corrected version of it. + * * @return * An array of menu items. Each menu item has a key corresponding to the * Drupal path being registered. The corresponding array value is an @@ -550,67 +521,6 @@ function hook_menu_get_item_alter(&$router_item, $path, $original_map) { * t(). If you require only the raw string to be output, set this to FALSE. * - description arguments: Arguments to send to t() or your custom callback, * with path component substitution as described above. - * - "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, with path component substitution as described above. - * - "access callback": A function returning TRUE if the user has access - * rights to this menu item, and FALSE if not. It can also be a boolean - * constant instead of a function, and you can also use numeric values - * (will be cast to boolean). Defaults to user_access() unless a value is - * inherited from the parent menu item; only MENU_DEFAULT_LOCAL_TASK items - * can inherit access callbacks. To use the user_access() default callback, - * you must specify the permission to check as 'access arguments' (see - * below). - * - "access arguments": An array of arguments to pass to the access callback - * function, with path component substitution as described above. If the - * access callback is inherited (see above), the access arguments will be - * inherited with it, unless overridden in the child menu item. - * - "theme callback": (optional) A function returning the machine-readable - * name of the theme that will be used to render the page. If not provided, - * the value will be inherited from a parent menu item. If there is no - * theme callback, or if the function does not return the name of a current - * active theme on the site, the theme for this page will be determined by - * either hook_custom_theme() or the default theme instead. As a general - * rule, the use of theme callback functions should be limited to pages - * whose functionality is very closely tied to a particular theme, since - * they can only be overridden by modules which specifically target those - * pages in hook_menu_alter(). Modules implementing more generic theme - * switching functionality (for example, a module which allows the theme to - * be set dynamically based on the current user's role) should use - * hook_custom_theme() instead. - * - "theme arguments": An array of arguments to pass to the theme callback - * function, with path component substitution as described above. - * - "file": A file that will be included before the page callback is called; - * this allows page 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. Does not apply to other - * callbacks (only page callback). - * - "file path": The path to the directory 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 - * wildcard object loaders in the path, after the path argument itself. - * For example, if a module registers path node/%node/revisions/%/view - * with load arguments set to array(3), the '%node' in the path indicates - * that the loader function node_load() will be called with the second - * path component as the first argument. The 3 in the load arguments - * indicates that the fourth path component will also be passed to - * node_load() (numbering of path components starts at zero). So, if path - * node/12/revisions/29/view is requested, node_load(12, 29) will be called. - * There are also two "magic" values that can be used in load arguments. - * "%index" indicates the index of the wildcard path component. "%map" - * indicates the path components as an array. For example, if a module - * registers for several paths of the form 'user/%user_category/edit/*', all - * of them can use the same load function user_category_load(), by setting - * the load arguments to array('%map', '%index'). For instance, if the user - * is editing category 'foo' by requesting path 'user/32/edit/foo', the load - * function user_category_load() will be called with 32 as its first - * argument, the array ('user', 32, 'edit', 'foo') as the map argument, - * and 1 as the index argument (because %user_category is the second path - * component and numbering starts at zero). user_category_load() can then - * use these values to extract the information that 'foo' is the category - * being requested. * - "weight": An integer that determines the relative position of items in * the menu; higher-weighted items sink. Defaults to 0. Menu items with the * same weight are ordered alphabetically. @@ -620,63 +530,32 @@ function hook_menu_get_item_alter(&$router_item, $path, $original_map) { * this menu item (as a result of other properties), then the menu link is * always expanded, equivalent to its 'always expanded' checkbox being set * in the UI. - * - "context": (optional) Defines the context a tab may appear in. By - * default, all tabs are only displayed as local tasks when being rendered - * in a page context. All tabs that should be accessible as contextual links - * in page region containers outside of the parent menu item's primary page - * context should be registered using one of the following contexts: - * - MENU_CONTEXT_PAGE: (default) The tab is displayed as local task for the - * page context only. - * - MENU_CONTEXT_INLINE: The tab is displayed as contextual link outside of - * the primary page context only. - * Contexts can be combined. For example, to display a tab both on a page - * and inline, a menu router item may specify: - * @code - * 'context' => MENU_CONTEXT_PAGE | MENU_CONTEXT_INLINE, - * @endcode - * - "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". * - "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 - * information is generated when the path is accessed. * - MENU_SUGGESTED_ITEM: Modules may "suggest" menu items that the * administrator may enable. - * - MENU_LOCAL_ACTION: Local actions are menu items that describe actions - * on the parent item such as adding a new user or block, and are - * rendered in the action-links list in your theme. - * - MENU_LOCAL_TASK: Local tasks are menu items that describe different - * displays of data, and are generally rendered as tabs. - * - MENU_DEFAULT_LOCAL_TASK: Every set of local tasks should provide one - * "default" task, which should display the same page as the parent item. * If the "type" element is omitted, MENU_NORMAL_ITEM is assumed. * - "options": An array of options to be passed to l() when generating a link - * from this menu item. Note that the "options" parameter has no effect on - * MENU_LOCAL_TASK, MENU_DEFAULT_LOCAL_TASK, and MENU_LOCAL_ACTION items. + * from this menu item. * * For a detailed usage example, see page_example.module. * For comprehensive documentation on the menu system, see * http://drupal.org/node/102338. + * + * @see menu */ function hook_menu() { $items['example'] = array( 'title' => 'Example Page', - 'page callback' => 'example_page', - 'access arguments' => array('access content'), - 'type' => MENU_SUGGESTED_ITEM, + 'route_name' => 'example.page', ); $items['example/feed'] = array( 'title' => 'Example RSS feed', - 'page callback' => 'example_feed', - 'access arguments' => array('access content'), - 'type' => MENU_CALLBACK, + 'route_name' => 'example.feed', ); return $items;