Drupal 8  8.0.2
Menu system

Functions

 template_preprocess_menu_local_task (&$variables)
 
 template_preprocess_menu_local_action (&$variables)
 
 menu_list_system_menus ()
 
 menu_local_tabs ()
 
 menu_cache_clear_all ()
 
 hook_menu_links_discovered_alter (&$links)
 
 hook_menu_local_tasks_alter (&$data, $route_name)
 
 hook_menu_local_actions_alter (&$local_actions)
 
 hook_local_tasks_alter (&$local_tasks)
 
 hook_contextual_links_alter (array &$links, $group, array $route_parameters)
 
 hook_contextual_links_plugins_alter (array &$contextual_links)
 
 hook_system_breadcrumb_alter (\Drupal\Core\Breadcrumb\Breadcrumb &$breadcrumb,\Drupal\Core\Routing\RouteMatchInterface $route_match, array $context)
 

Detailed Description

Define the navigation menus, local actions and tasks, and contextual links.

Overview and terminology

The menu system uses routes; see the Routing API topic for more information. It is used for navigation menus, local tasks, local actions, and contextual links:

The following sections of this topic provide an overview of the menu API. For more detailed information, see https://www.drupal.org/developing/api/8/menu

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.links.menu.yml file (in the top-level directory for your module):

dblog.overview:
title: 'Recent log messages'
parent: system.admin_reports
description: 'View events that have recently been logged.'
route_name: dblog.overview
weight: -1

Some notes:

Discovered menu links from other modules can be altered using hook_menu_links_discovered_alter().

Todo:
Derivatives will probably be defined for these; when they are, add documentation here.

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.links.task.yml file (in the top-level directory for your module):

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

Some notes:

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.

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.links.action.yml file (in the top-level directory for your module):

node.add_page:
route_name: node.add_page
title: 'Add content'
appears_on:
- system.admin_content

Some notes:

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.

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:

array(
'#contextual_links' => array(
'block' => array(
'route_parameters' => array('block' => $entity->id()),
),
),

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 Defining routes with 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.links.contextual.yml file (in the top-level directory for your module):

block_configure:
title: 'Configure block'
route_name: 'entity.block.edit_form'
group: 'block'

Some notes:

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.

Rendering menus

Once you have created menus (that contain menu links), you want to render them. Drupal provides a block (Drupal) to do so.

However, perhaps you have more advanced needs and you're not satisfied with what the menu blocks offer you. If that's the case, you'll want to:

Combined, that would look like this:

$menu_tree = \Drupal::menuTree();
$menu_name = 'my_menu';
// Build the typical default set of menu tree parameters.
$parameters = $menu_tree->getCurrentRouteMenuTreeParameters($menu_name);
// Load the tree based on this set of parameters.
$tree = $menu_tree->load($menu_name, $parameters);
// Transform the tree using the manipulators you want.
$manipulators = array(
// Only show links that are accessible for the current user.
array('callable' => 'menu.default_tree_manipulators:checkAccess'),
// Use the default sorting of menu links.
array('callable' => 'menu.default_tree_manipulators:generateIndexAndSort'),
);
$tree = $menu_tree->transform($tree, $manipulators);
// Finally, build a renderable array from the transformed tree.
$menu = $menu_tree->build($tree);
$menu_html = drupal_render($menu);

Function Documentation

hook_contextual_links_alter ( array &  $links,
  $group,
array  $route_parameters 
)

Alter contextual links before they are rendered.

This hook is invoked by ::getContextualLinkPluginsByGroup(). The system-determined contextual links are passed in by reference. Additional links may be added and existing links can be altered.

Each contextual link contains the following entries:

  • title: The localized title of the link.
  • route_name: The route name of the link.
  • route_parameters: The route parameters of the link.
  • localized_options: An array of URL options.
  • (optional) weight: The weight of the link, which is used to sort the links.
Parameters
array$linksAn associative array containing contextual links for the given $group, as described above. The array keys are used to build CSS class names for contextual links and must therefore be unique for each set of contextual links.
string$groupThe group of contextual links being rendered.
array$route_parameters,.The route parameters passed to each route_name of the contextual links. For example:
array('node' => $node->id())
See Also

References Drupal\entityManager(), and t().

Here is the call graph for this function:

hook_contextual_links_plugins_alter ( array &  $contextual_links)

Alter the plugin definition of contextual links.

Parameters
array$contextual_linksAn array of contextual_links plugin definitions, keyed by contextual link ID. Each entry contains the following keys:
  • title: The displayed title of the link
  • route_name: The route_name of the contextual link to be displayed
  • group: The group under which the contextual links should be added to. Possible values are e.g. 'node' or 'menu'.
See Also
hook_local_tasks_alter ( $local_tasks)

Alter local tasks plugins.

Parameters
array$local_tasksThe array of local tasks plugin definitions, keyed by plugin ID.
See Also
hook_menu_links_discovered_alter ( $links)

Alters all the menu links discovered by the menu link plugin manager.

Parameters
array$linksThe link definitions to be altered.
Returns
array An array of discovered menu links. Each link has a key that is the machine name, which must be unique. By default, use the route name as the machine name. In cases where multiple links use the same route name, such as two links to the same page in different menus, or two links using the same route name but different route parameters, the suggested machine name patten is the route name followed by a dot and a unique suffix. For example, an additional logout link might have a machine name of user.logout.navigation, and default links provided to edit the article and page content types could use machine names entity.node_type.edit_form.article and entity.node_type.edit_form.page. Since the machine name may be arbitrary, you should never write code that assumes it is identical to the route name.

The value corresponding to each machine name key is an associative array that may contain the following key-value pairs:

  • title: (required) The title of the menu link. If this should be translated, create a object.
  • description: The description of the link. If this should be translated, create a object.
  • route_name: (optional) The route name to be used to build the path. Either the route_name or url element must be provided.
  • route_parameters: (optional) The route parameters to build the path.
  • url: (optional) If you have an external link use this element instead of providing route_name.
  • parent: (optional) The machine name of the link that is this link's menu parent.
  • weight: (optional) 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.
  • menu_name: (optional) The machine name of a menu to put the link in, if not the default Tools menu.
  • expanded: (optional) If set to TRUE, and if a menu link is provided for 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.
  • options: (optional) An array of options to be passed to ::generate() when generating a link from this menu item.

References Drupal\config(), and Drupal\moduleHandler().

Here is the call graph for this function:

hook_menu_local_actions_alter ( $local_actions)

Alter local actions plugins.

Parameters
array$local_actionsThe array of local action plugin definitions, keyed by plugin ID.
See Also
hook_menu_local_tasks_alter ( $data,
  $route_name 
)

Alter local tasks displayed on the page before they are rendered.

This hook is invoked by menu_local_tasks(). The system-determined tabs and actions are passed in by reference. Additional tabs may be added.

The local tasks are under the 'tabs' element and keyed by plugin ID.

Each local task is an associative array containing:

  • #theme: The theme function to use to render.
  • #link: An associative array containing:
    • title: The localized title of the link.
    • url: a Url object.
    • localized_options: An array of options to pass to ::generate().
  • #weight: The link's weight compared to other links.
  • #active: Whether the link should be marked as 'active'.
Parameters
array$dataAn associative array containing list of (up to 2) tab levels that contain a list of tabs keyed by their href, each one being an associative array as described above.
string$route_nameThe route name of the page.

References t().

Here is the call graph for this function:

hook_system_breadcrumb_alter ( \Drupal\Core\Breadcrumb\Breadcrumb $breadcrumb,
\Drupal\Core\Routing\RouteMatchInterface  $route_match,
array  $context 
)

Perform alterations to the breadcrumb built by the BreadcrumbManager.

Parameters
\Drupal\Core\Breadcrumb\Breadcrumb$breadcrumbA breadcrumb object returned by BreadcrumbBuilderInterface::build().
\Drupal\Core\Routing\RouteMatchInterface$route_matchThe current route match.
array$contextMay include the following key:
  • builder: the instance of that constructed this breadcrumb, or NULL if no builder acted based on the current attributes.

References t().

Here is the call graph for this function:

menu_cache_clear_all ( )

Clears all cached menu data.

This should be called any time broad changes might have been made to the router items or menu links.

References Drupal\cache().

Here is the call graph for this function:

menu_list_system_menus ( )

Returns an array containing the names of system-defined (default) menus.

Referenced by WizardPluginBase\buildForm().

Here is the caller graph for this function:

menu_local_tabs ( )

Returns a renderable element for the primary and secondary tabs.

template_preprocess_menu_local_action ( $variables)

Prepares variables for single local action link templates.

Default template: menu-local-action.html.twig.

Parameters
array$variablesAn associative array containing:
  • element: A render element containing:
    • #link: A menu link array with 'title', 'url', and (optionally) 'localized_options' keys.
template_preprocess_menu_local_task ( $variables)

Prepares variables for single local task link templates.

Default template: menu-local-task.html.twig.

Parameters
array$variablesAn associative array containing:
  • element: A render element containing:
    • #link: A menu link array with 'title', 'url', and (optionally) 'localized_options' keys.
    • #active: A boolean indicating whether the local task is active.

References t().

Here is the call graph for this function: