Commit 21fc02cf authored by webchick's avatar webchick

Issue #2290129 by jhodgdon, Gábor Hojtsy, Crell, joachim: Menu/routing topic needs an overhaul.

parent 83229e05
......@@ -14,89 +14,245 @@
* @{
* Define the navigation menus, and route page requests to code based on URLs.
*
* 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 UI 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:
* @section sec_overview Overview and terminology
* The Drupal routing system defines how Drupal responds to URL requests that
* the web server passes on to Drupal. The routing system is based on the
* @link http://symfony.com Symfony framework. @endlink The central idea is
* that Drupal subsystems and modules can register routes (basically, URL
* paths and context); they can also register to respond dynamically to
* routes, for more flexibility. When Drupal receives a URL request, it will
* attempt to match the request to a registered route, and query dynamic
* responders. If a match is made, Drupal will then instantiate the required
* classes, gather the data, format it, and send it back to the web browser.
* Otherwise, Drupal will return a 404 or 403 response.
*
* The menu system uses routes; it is used for navigation menus, local tasks,
* local actions, and contextual links:
* - Navigation menus are hierarchies of menu links; links point to routes or
* URLs.
* - Menu links and their hierarchies can be defined by Drupal subsystems
* and modules, or created in the user interface using the Menu UI module.
* - Local tasks are groups of related routes. Local tasks are usually rendered
* as a group of tabs.
* - Local actions are used for operations such as adding a new item on a page
* that lists items of some type. Local actions are usually rendered as
* buttons.
* - Contextual links are actions that are related to sections of rendered
* output, and are usually rendered as a pop-up list of links. The
* Contextual Links module handles the gathering and rendering of contextual
* links.
*
* The following sections of this topic provide an overview of the routing and
* menu APIs. For more detailed information, see
* https://www.drupal.org/developing/api/8/routing and
* https://www.drupal.org/developing/api/8/menu
*
* @section sec_register Registering simple routes
* To register a route, add lines similar to this to a module_name.routing.yml
* file in your top-level module directory:
* @code
* dblog.overview:
* path: '/admin/reports/dblog'
* defaults:
* _content: '\Drupal\dblog\Controller\DbLogController::overview'
* _title: 'Recent log messages'
* requirements:
* _permission: 'access site reports'
* @endcode
* Some notes:
* - The first line is the machine name of the route. Typically, it is prefixed
* by the machine name of the module that defines the route, or the name of
* a subsystem.
* - The 'path' line gives the URL path of the route (relative to the site's
* base URL).
* - The 'defaults' section tells how to build the main content of the route,
* and can also give other information, such as the page title and additional
* arguments for the route controller method. There are several possibilities
* for how to build the main content, including:
* - _content: A callable, usually a method on a page controller class
* (see @ref sec_controller below for details).
* - _controller: A callable, usually a method on a page controller class
* (see @ref sec_controller below for details).
* - _form: A form controller class. See the
* @link form_api Form API topic @endlink for more information about
* form controllers.
* - _entity_form: A form for editing an entity. See the
* @link entity_api Entity API topic @endlink for more information.
* - The 'requirements' section is used in Drupal to give access permission
* instructions (it has other uses in the Symfony framework). Most
* routes have a simple permission-based access scheme, as shown in this
* example. See the @link user_api Permission system topic @endlink for
* more information about permissions.
*
* See https://www.drupal.org/node/2092643 for more details about *.routing.yml
* files, and https://www.drupal.org/node/2122201 for information on how to
* set up dynamic routes.
*
* @section sec_placeholders Defining routes with placeholders
* Some routes have placeholders in them, and these can also be defined in a
* module_name.routing.yml file, as in this example from the Block module:
* @code
* block.admin_display:
* path: '/admin/structure/block'
* block.admin_edit:
* path: '/admin/structure/block/manage/{block}'
* defaults:
* _content: '\Drupal\block\Controller\BlockListController::listing'
* _entity_form: 'block.default'
* _title: 'Configure block'
* requirements:
* _permission: 'administer blocks'
* _entity_access: 'block.update'
* @endcode
* In the path, '{block}' is a placeholder - it will be replaced by the
* ID of the block that is being configured by the entity system. See the
* @link entity_api Entity API topic @endlink for more information.
*
* @section sec_controller Route controllers for simple routes
* For simple routes, after you have defined the route in a *.routing.yml file
* (see @ref sec_register above), the next step is to define a page controller
* class and method. Page controller classes do not necessarily need to
* implement any particular interface or extend any particular base class. The
* only requirement is that the method specified in your *.routing.yml file
* return one of the following, depending on whether you specified _content or
* _controller in the routing file defaults section:
* - A render array (see the
* @link theme_render Theme and render topic @endlink for more information),
* if _content is used in the routing file.
* - A \Drupal\Core\Page\HtmlFragmentInterface object (fragment or page), if
* _content is used in the routing file.
* - A \Symfony\Component\HttpFoundation\Response object, if _controller is
* used in the routing file.
* As a note, if your module registers multiple simple routes, it is usual
* (and usually easiest) to put all of their methods on one controller class.
*
* Most controllers will need to display some information stored in the Drupal
* database, which will involve using one or more Drupal services (see the
* @link container Services and container topic @endlink). In order to properly
* inject services, a controller should implement
* \Drupal\Core\DependencyInjection\ContainerInjectionInterface; simple
* controllers can do this by extending the
* \Drupal\Core\Controller\ControllerBase class. See
* \Drupal\dblog\Controller\DbLogController for a straightforward example of
* a controller class.
*
* @section sec_links Defining menu links for the administrative menu
* Routes for administrative tasks can be added to the main Drupal
* administrative menu hierarchy. To do this, add lines like the following to a
* module_name.menu_links.yml file (in the top-level directory for your module):
* @code
* dblog.overview:
* title: 'Recent log messages'
* parent: system.admin_reports
* description: 'View events that have recently been logged.'
* route_name: dblog.overview
* weight: -1
* @endcode
* Some notes:
* - The first line is the machine name for your menu link, which usually
* matches the machine name of the route (given in the 'route_name' line).
* - parent: The machine name of the menu link that is the parent in the
* administrative hierarchy. See system.menu_links.yml to find the main
* skeleton of the hierarchy.
* - weight: Lower (negative) numbers come before higher (positive) numbers,
* for menu items with the same parent.
*
* Menu items from other modules can be altered using
* hook_menu_link_defaults_alter().
*
* @todo Derivatives will probably be defined for these; when they are, add
* documentation here.
*
* @section sec_tasks Defining groups of local tasks (tabs)
* Local tasks appear as tabs on a page when there are at least two defined for
* a route, including the base route as the main tab, and additional routes as
* other tabs. Static local tasks can be defined by adding lines like the
* following to a module_name.local_tasks.yml file (in the top-level directory
* for your module):
* @code
* book.admin:
* route_name: book.admin
* title: 'List'
* base_route: book.admin
* book.settings:
* route_name: book.settings
* title: 'Settings'
* base_route: book.admin
* weight: 100
* @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 module.menu_links.yml to
* define links for your module's paths in the main Navigation menu or other
* menus.
*
* @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
* paths (which should be unique). The menu system aggregates these items
* and determines the menu hierarchy from the paths. For example, if the
* paths defined were a, a/b, e, a/b/c/d, f/g, and a/b/h, the menu system
* would form the structure:
* - a
* - a/b
* - a/b/c/d
* - a/b/h
* - e
* - f/g
* Note that the number of elements in the path does not necessarily
* determine the depth of the menu item in the tree.
*
* When responding to a page request, the menu system looks to see if the
* path requested by the browser is registered as a menu item with a
* callback. If not, the system searches up the menu tree for the most
* complete match with a callback it can find. If the path a/b/i is
* requested in the tree above, the callback for a/b would be used.
*
* The found callback function is called with any arguments specified
* in the "page arguments" attribute of its menu item. The
* attribute must be an array. After these arguments, any remaining
* components of the path are appended as further arguments. In this
* way, the callback for a/b above could respond to a request for
* a/b/i differently than a request for a/b/j.
*
* For an illustration of this process, see page_example.module.
*
* Access to the callback functions is also protected by the menu system.
* The "access callback" with an optional "access arguments" of each menu
* item is called before the page callback proceeds. If this returns TRUE,
* then access is granted; if FALSE, then access is denied. Default local task
* menu items (see next paragraph) may omit this attribute to use the value
* provided by the parent item.
*
* In the default Drupal interface, you will notice many links rendered as
* tabs. These are known in the menu system as "local tasks", and they are
* rendered as tabs by default, though other presentations are possible.
* Local tasks function just as other menu items in most respects. It is
* convention that the names of these tasks should be short verbs if
* possible. In addition, a "default" local task should be provided for
* each set. When visiting a local task's parent menu item, the default
* local task will be rendered as if it is selected; this provides for a
* normal tab user experience. This default task is special in that it
* links not to its provided path, but to its parent item's path instead.
* The default task's path is only used to place it appropriately in the
* menu hierarchy.
*
* Everything described so far is stored in the menu_router table. The
* menu_links table holds the visible menu links. By default these are
* derived from the same hook_menu definitions, however you are free to
* add more with menu_link_save().
* Some notes:
* - The first line is the machine name for your local task, which usually
* matches the machine name of the route (given in the 'route_name' line).
* - base_route: The machine name of the main task (tab) for the set of local
* tasks.
* - weight: Lower (negative) numbers come before higher (positive) numbers,
* for tasks on the same base route. If there is a tab whose route
* matches the base route, that will be the default/first tab shown.
*
* Local tasks from other modules can be altered using
* hook_menu_local_tasks_alter().
*
* @todo Derivatives are in flux for these; when they are more stable, add
* documentation here.
*
* @section sec_actions Defining local actions for routes
* Local actions can be defined for operations related to a given route. For
* instance, adding content is a common operation for the content management
* page, so it should be a local action. Static local actions can be
* defined by adding lines like the following to a
* module_name.local_actions.yml file (in the top-level directory for your
* module):
* @code
* node.add_page:
* route_name: node.add_page
* title: 'Add content'
* appears_on:
* - system.admin_content
* @endcode
* Some notes:
* - The first line is the machine name for your local action, which usually
* matches the machine name of the route (given in the 'route_name' line).
* - appears_on: Machine names of one or more routes that this local task
* should appear on.
*
* Local actions from other modules can be altered using
* hook_menu_local_actions_alter().
*
* @todo Derivatives are in flux for these; when they are more stable, add
* documentation here.
*
* @section sec_contextual Defining contextual links
* Contextual links are displayed by the Contextual Links module for user
* interface elements whose render arrays have a '#contextual_links' element
* defined. For example, a block render array might look like this, in part:
* @code
* array(
* '#contextual_links' => array(
* 'block' => array(
* 'route_parameters' => array('block' => $entity->id()),
* ),
* ),
* @endcode
* In this array, the outer key 'block' defines a "group" for contextual
* links, and the inner array provides values for the route's placeholder
* parameters (see @ref sec_placeholders above).
*
* To declare that a defined route should be a contextual link for a
* contextual links group, put lines like the following in a
* module_name.contextual_links.yml file (in the top-level directory for your
* module):
* @code
* block_configure:
* title: 'Configure block'
* route_name: 'block.admin_edit'
* group: 'block'
* @endcode
* Some notes:
* - The first line is the machine name for your contextual link, which usually
* matches the machine name of the route (given in the 'route_name' line).
* - group: This needs to match the link group defined in the render array.
*
* Contextual links from other modules can be altered using
* hook_contextual_links_alter().
*
* @todo Derivatives are in flux for these; when they are more stable, add
* documentation here.
*/
/**
......
......@@ -30,6 +30,8 @@
* service.
*
* @see \Drupal\Core\DependencyInjection\ContainerInjectionInterface
*
* @ingroup menu
*/
abstract class ControllerBase implements ContainerInjectionInterface {
use StringTranslationTrait;
......
......@@ -19,6 +19,8 @@
* ControllerBase as that allows direct access to the container. That renders
* the controller very difficult to unit test so should only be used for
* controllers that are trivial in complexity.
*
* @ingroup menu
*/
interface ContainerInjectionInterface {
......
......@@ -14,6 +14,8 @@
* HTML that would not be part of the HTML string itself. That includes, for
* example, required CSS files, Javascript files, link tags, meta tags, and the
* title of a page or page section.
*
* @ingroup menu
*/
interface HtmlFragmentInterface {
......
......@@ -313,13 +313,13 @@
* entity interface you have defined as its parameter, and returns routing
* information for the entity page; see node_uri() for an example. You will
* also need to add a corresponding route to your module's routing.yml file;
* see the node.view route in node.routing.yml for an example, and see the
* @link menu Menu and routing @endlink topic for more information about
* routing.
* see the node.view route in node.routing.yml for an example, and see
* @ref sec_routes below for some notes.
* - Define routing and links for the various URLs associated with the entity.
* These go into the 'links' annotation, with the link type as the key, and
* the route machine name (defined in your module's routing.yml file) as the
* value. Typical link types are:
* value; see @ref sec_routes below for some routing notes. Typical link
* types are:
* - canonical: Default link, either to view (if entities are viewed on their
* own pages) or edit the entity.
* - delete-form: Confirmation form to delete the entity.
......@@ -339,6 +339,37 @@
* (configuration). These annotations are documented on
* \Drupal\Core\Entity\EntityType.
*
* @section sec_routes Entity routes
* Entity routes, like other routes, are defined in *.routing.yml files; see
* the @link menu Menu and routing @endlink topic for more information. Here
* is a typical entry, for the block configure form:
* @code
* block.admin_edit:
* path: '/admin/structure/block/manage/{block}'
* defaults:
* _entity_form: 'block.default'
* _title: 'Configure block'
* requirements:
* _entity_access: 'block.update'
* @endcode
* Some notes:
* - path: The {block} in the path is a placeholder, which (for an entity) must
* always take the form of {machine_name_of_entity_type}. In the URL, the
* placeholder value will be the ID of an entity item. When the route is used,
* the entity system will load the corresponding entity item and pass it in as
* an object to the controller for the route.
* - defaults: For entity form routes, use _entity_form rather than the generic
* _content or _form. The value is composed of the entity type machine name
* and a form controller type from the entity annotation (see @ref define
* above more more on controllers and annotation). So, in this example,
* block.default refers to the 'default' form controller on the block entity
* type, whose annotation contains:
* @code
* controllers = {
* "form" = {
* "default" = "Drupal\block\BlockForm",
* @endcode
*
* @section load_query Loading and querying entities
* To load entities, use the entity storage manager, which is an object
* implementing \Drupal\Core\Entity\EntityStorageInterface that you can
......
......@@ -437,6 +437,8 @@ function hook_page_build(&$page) {
* in the UI.
* - options: (optional) An array of options to be passed to l() when
* generating a link from this menu item.
*
* @ingroup menu
*/
function hook_menu_link_defaults_alter(&$links) {
// Change the weight and title of the user.logout link.
......@@ -511,6 +513,8 @@ function hook_menu_local_tasks(&$data, $route_name) {
* The route name of the page.
*
* @see hook_menu_local_tasks()
*
* @ingroup menu
*/
function hook_menu_local_tasks_alter(&$data, $route_name) {
}
......@@ -523,6 +527,8 @@ function hook_menu_local_tasks_alter(&$data, $route_name) {
*
* @see \Drupal\Core\Menu\LocalActionInterface
* @see \Drupal\Core\Menu\LocalActionManager
*
* @ingroup menu
*/
function hook_menu_local_actions_alter(&$local_actions) {
}
......@@ -572,6 +578,8 @@ function hook_local_tasks_alter(&$local_tasks) {
* @endcode
*
* @see \Drupal\Core\Menu\ContextualLinkManager
*
* @ingroup menu
*/
function hook_contextual_links_alter(array &$links, $group, array $route_parameters) {
if ($group == 'menu') {
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment