diff --git a/core/includes/menu.inc b/core/includes/menu.inc index 6abab20..a36ab6d 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 + * and breadcrumbs 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..61f1b7f 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,21 +490,10 @@ 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, breadcrumbs, and local tasks. * * @section sec_render_tabs Rendering Menu Items As Tabs - * You can also make groups of menu items to be rendered (by default) as tabs + * You can 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 @@ -517,25 +505,27 @@ function hook_menu_get_item_alter(&$router_item, $path, $original_map) { * $items['admin/config/system/foo'] = array( * 'title' => 'Foo settings', * 'type' => MENU_NORMAL_ITEM, - * // Page callback, etc. need to be added here. + * 'route_name' => 'foosettings' * ); * // 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. + * // Route name would 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' => 'foo2', * ); * @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 +540,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. @@ -645,8 +574,6 @@ function hook_menu_get_item_alter(&$router_item, $path, $original_map) { * 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 @@ -664,19 +591,17 @@ function hook_menu_get_item_alter(&$router_item, $path, $original_map) { * 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;