Chris@0: array( Chris@0: * 'block' => array( Chris@0: * 'route_parameters' => array('block' => $entity->id()), Chris@0: * ), Chris@0: * ), Chris@0: * @endcode Chris@0: * In this array, the outer key 'block' defines a "group" for contextual Chris@0: * links, and the inner array provides values for the route's placeholder Chris@0: * parameters (see @ref sec_placeholders above). Chris@0: * Chris@0: * To declare that a defined route should be a contextual link for a Chris@0: * contextual links group, put lines like the following in a Chris@0: * module_name.links.contextual.yml file (in the top-level directory for your Chris@0: * module): Chris@0: * @code Chris@0: * block_configure: Chris@0: * title: 'Configure block' Chris@0: * route_name: 'entity.block.edit_form' Chris@0: * group: 'block' Chris@0: * @endcode Chris@0: * Some notes: Chris@0: * - The first line is the machine name for your contextual link, which usually Chris@0: * matches the machine name of the route (given in the 'route_name' line). Chris@0: * - group: This needs to match the link group defined in the render array. Chris@0: * Chris@0: * Contextual links from other modules can be altered using Chris@0: * hook_contextual_links_alter(). Chris@0: * Chris@0: * @todo Derivatives are in flux for these; when they are more stable, add Chris@0: * documentation here. Chris@0: * Chris@0: * @section sec_rendering Rendering menus Chris@0: * Once you have created menus (that contain menu links), you want to render Chris@0: * them. Drupal provides a block (Drupal\system\Plugin\Block\SystemMenuBlock) to Chris@0: * do so. Chris@0: * Chris@0: * However, perhaps you have more advanced needs and you're not satisfied with Chris@0: * what the menu blocks offer you. If that's the case, you'll want to: Chris@0: * - Instantiate \Drupal\Core\Menu\MenuTreeParameters, and set its values to Chris@0: * match your needs. Alternatively, you can use Chris@0: * MenuLinkTree::getCurrentRouteMenuTreeParameters() to get a typical Chris@0: * default set of parameters, and then customize them to suit your needs. Chris@0: * - Call \Drupal\Core\MenuLinkTree::load() with your menu link tree parameters, Chris@0: * this will return a menu link tree. Chris@0: * - Pass the menu tree to \Drupal\Core\Menu\MenuLinkTree::transform() to apply Chris@0: * menu link tree manipulators that transform the tree. You will almost always Chris@0: * want to apply access checking. The manipulators that you will typically Chris@0: * need can be found in \Drupal\Core\Menu\DefaultMenuLinkTreeManipulators. Chris@0: * - Potentially write a custom menu tree manipulator, see Chris@0: * \Drupal\Core\Menu\DefaultMenuLinkTreeManipulators for examples. This is Chris@0: * only necessary if you want to do things like adding extra metadata to Chris@0: * rendered links to display icons next to them. Chris@0: * - Pass the menu tree to \Drupal\Core\Menu\MenuLinkTree::build(), this will Chris@0: * build a renderable array. Chris@0: * Chris@0: * Combined, that would look like this: Chris@0: * @code Chris@0: * $menu_tree = \Drupal::menuTree(); Chris@0: * $menu_name = 'my_menu'; Chris@0: * Chris@0: * // Build the typical default set of menu tree parameters. Chris@0: * $parameters = $menu_tree->getCurrentRouteMenuTreeParameters($menu_name); Chris@0: * Chris@0: * // Load the tree based on this set of parameters. Chris@0: * $tree = $menu_tree->load($menu_name, $parameters); Chris@0: * Chris@0: * // Transform the tree using the manipulators you want. Chris@0: * $manipulators = array( Chris@0: * // Only show links that are accessible for the current user. Chris@0: * array('callable' => 'menu.default_tree_manipulators:checkAccess'), Chris@0: * // Use the default sorting of menu links. Chris@0: * array('callable' => 'menu.default_tree_manipulators:generateIndexAndSort'), Chris@0: * ); Chris@0: * $tree = $menu_tree->transform($tree, $manipulators); Chris@0: * Chris@0: * // Finally, build a renderable array from the transformed tree. Chris@0: * $menu = $menu_tree->build($tree); Chris@0: * Chris@16: * $menu_html = \Drupal::service('renderer')->render($menu); Chris@0: * @endcode Chris@0: * Chris@0: * @} Chris@0: */ Chris@0: Chris@0: /** Chris@0: * @addtogroup hooks Chris@0: * @{ Chris@0: */ Chris@0: Chris@0: /** Chris@0: * Alters all the menu links discovered by the menu link plugin manager. Chris@0: * Chris@0: * @param array $links Chris@0: * The link definitions to be altered. Chris@0: * Chris@0: * @return array Chris@0: * An array of discovered menu links. Each link has a key that is the machine Chris@0: * name, which must be unique. By default, use the route name as the Chris@0: * machine name. In cases where multiple links use the same route name, such Chris@0: * as two links to the same page in different menus, or two links using the Chris@0: * same route name but different route parameters, the suggested machine name Chris@0: * patten is the route name followed by a dot and a unique suffix. For Chris@0: * example, an additional logout link might have a machine name of Chris@0: * user.logout.navigation, and default links provided to edit the article and Chris@0: * page content types could use machine names Chris@0: * entity.node_type.edit_form.article and entity.node_type.edit_form.page. Chris@0: * Since the machine name may be arbitrary, you should never write code that Chris@0: * assumes it is identical to the route name. Chris@0: * Chris@0: * The value corresponding to each machine name key is an associative array Chris@0: * that may contain the following key-value pairs: Chris@0: * - title: (required) The title of the menu link. If this should be Chris@0: * translated, create a \Drupal\Core\StringTranslation\TranslatableMarkup Chris@0: * object. Chris@0: * - description: The description of the link. If this should be Chris@0: * translated, create a \Drupal\Core\StringTranslation\TranslatableMarkup Chris@0: * object. Chris@0: * - route_name: (optional) The route name to be used to build the path. Chris@0: * Either the route_name or url element must be provided. Chris@0: * - route_parameters: (optional) The route parameters to build the path. Chris@0: * - url: (optional) If you have an external link use this element instead of Chris@0: * providing route_name. Chris@0: * - parent: (optional) The machine name of the link that is this link's menu Chris@0: * parent. Chris@0: * - weight: (optional) An integer that determines the relative position of Chris@0: * items in the menu; higher-weighted items sink. Defaults to 0. Menu items Chris@0: * with the same weight are ordered alphabetically. Chris@0: * - menu_name: (optional) The machine name of a menu to put the link in, if Chris@0: * not the default Tools menu. Chris@0: * - expanded: (optional) If set to TRUE, and if a menu link is provided for Chris@0: * this menu item (as a result of other properties), then the menu link is Chris@0: * always expanded, equivalent to its 'always expanded' checkbox being set Chris@0: * in the UI. Chris@0: * - options: (optional) An array of options to be passed to Chris@0: * \Drupal\Core\Utility\LinkGeneratorInterface::generate() when generating Chris@0: * a link from this menu item. Chris@0: * Chris@0: * @ingroup menu Chris@0: */ Chris@0: function hook_menu_links_discovered_alter(&$links) { Chris@0: // Change the weight and title of the user.logout link. Chris@0: $links['user.logout']['weight'] = -10; Chris@0: $links['user.logout']['title'] = new \Drupal\Core\StringTranslation\TranslatableMarkup('Logout'); Chris@0: // Conditionally add an additional link with a title that's not translated. Chris@0: if (\Drupal::moduleHandler()->moduleExists('search')) { Chris@0: $links['menu.api.search'] = [ Chris@0: 'title' => \Drupal::config('system.site')->get('name'), Chris@0: 'route_name' => 'menu.api.search', Chris@0: 'description' => new \Drupal\Core\StringTranslation\TranslatableMarkup('View popular search phrases for this site.'), Chris@0: 'parent' => 'system.admin_reports', Chris@0: ]; Chris@0: } Chris@0: } Chris@0: Chris@0: /** Chris@0: * Alter local tasks displayed on the page before they are rendered. Chris@0: * Chris@0: * This hook is invoked by \Drupal\Core\Menu\LocalTaskManager::getLocalTasks(). Chris@0: * The system-determined tabs and actions are passed in by reference. Additional Chris@0: * tabs may be added. Chris@0: * Chris@0: * The local tasks are under the 'tabs' element and keyed by plugin ID. Chris@0: * Chris@0: * Each local task is an associative array containing: Chris@0: * - #theme: The theme function to use to render. Chris@0: * - #link: An associative array containing: Chris@0: * - title: The localized title of the link. Chris@0: * - url: a Url object. Chris@0: * - localized_options: An array of options to pass to Chris@0: * \Drupal\Core\Utility\LinkGeneratorInterface::generate(). Chris@0: * - #weight: The link's weight compared to other links. Chris@0: * - #active: Whether the link should be marked as 'active'. Chris@0: * Chris@0: * @param array $data Chris@0: * An associative array containing list of (up to 2) tab levels that contain a Chris@0: * list of tabs keyed by their href, each one being an associative array Chris@0: * as described above. Chris@0: * @param string $route_name Chris@0: * The route name of the page. Chris@16: * @param \Drupal\Core\Cache\RefinableCacheableDependencyInterface $cacheability Chris@16: * The cacheability metadata for the current route's local tasks. Chris@0: * Chris@0: * @ingroup menu Chris@0: */ Chris@16: function hook_menu_local_tasks_alter(&$data, $route_name, \Drupal\Core\Cache\RefinableCacheableDependencyInterface &$cacheability) { Chris@0: Chris@0: // Add a tab linking to node/add to all pages. Chris@0: $data['tabs'][0]['node.add_page'] = [ Chris@0: '#theme' => 'menu_local_task', Chris@0: '#link' => [ Chris@0: 'title' => t('Example tab'), Chris@0: 'url' => Url::fromRoute('node.add_page'), Chris@0: 'localized_options' => [ Chris@0: 'attributes' => [ Chris@0: 'title' => t('Add content'), Chris@0: ], Chris@0: ], Chris@0: ], Chris@0: ]; Chris@16: // The tab we're adding is dependent on a user's access to add content. Chris@16: $cacheability->addCacheTags(['user.permissions']); Chris@0: } Chris@0: Chris@0: /** Chris@0: * Alter local actions plugins. Chris@0: * Chris@0: * @param array $local_actions Chris@0: * The array of local action plugin definitions, keyed by plugin ID. Chris@0: * Chris@0: * @see \Drupal\Core\Menu\LocalActionInterface Chris@0: * @see \Drupal\Core\Menu\LocalActionManager Chris@0: * Chris@0: * @ingroup menu Chris@0: */ Chris@0: function hook_menu_local_actions_alter(&$local_actions) { Chris@0: } Chris@0: Chris@0: /** Chris@0: * Alter local tasks plugins. Chris@0: * Chris@0: * @param array $local_tasks Chris@0: * The array of local tasks plugin definitions, keyed by plugin ID. Chris@0: * Chris@0: * @see \Drupal\Core\Menu\LocalTaskInterface Chris@0: * @see \Drupal\Core\Menu\LocalTaskManager Chris@0: * Chris@0: * @ingroup menu Chris@0: */ Chris@0: function hook_local_tasks_alter(&$local_tasks) { Chris@0: // Remove a specified local task plugin. Chris@0: unset($local_tasks['example_plugin_id']); Chris@0: } Chris@0: Chris@0: /** Chris@0: * Alter contextual links before they are rendered. Chris@0: * Chris@0: * This hook is invoked by Chris@0: * \Drupal\Core\Menu\ContextualLinkManager::getContextualLinkPluginsByGroup(). Chris@0: * The system-determined contextual links are passed in by reference. Additional Chris@0: * links may be added and existing links can be altered. Chris@0: * Chris@0: * Each contextual link contains the following entries: Chris@0: * - title: The localized title of the link. Chris@0: * - route_name: The route name of the link. Chris@0: * - route_parameters: The route parameters of the link. Chris@0: * - localized_options: An array of URL options. Chris@0: * - (optional) weight: The weight of the link, which is used to sort the links. Chris@0: * Chris@0: * Chris@0: * @param array $links Chris@0: * An associative array containing contextual links for the given $group, Chris@0: * as described above. The array keys are used to build CSS class names for Chris@0: * contextual links and must therefore be unique for each set of contextual Chris@0: * links. Chris@0: * @param string $group Chris@0: * The group of contextual links being rendered. Chris@0: * @param array $route_parameters Chris@0: * The route parameters passed to each route_name of the contextual links. Chris@0: * For example: Chris@0: * @code Chris@0: * array('node' => $node->id()) Chris@0: * @endcode Chris@0: * Chris@0: * @see \Drupal\Core\Menu\ContextualLinkManager Chris@0: * Chris@0: * @ingroup menu Chris@0: */ Chris@0: function hook_contextual_links_alter(array &$links, $group, array $route_parameters) { Chris@0: if ($group == 'menu') { Chris@0: // Dynamically use the menu name for the title of the menu_edit contextual Chris@0: // link. Chris@0: $menu = \Drupal::entityManager()->getStorage('menu')->load($route_parameters['menu']); Chris@0: $links['menu_edit']['title'] = t('Edit menu: @label', ['@label' => $menu->label()]); Chris@0: } Chris@0: } Chris@0: Chris@0: /** Chris@0: * Alter the plugin definition of contextual links. Chris@0: * Chris@0: * @param array $contextual_links Chris@0: * An array of contextual_links plugin definitions, keyed by contextual link Chris@0: * ID. Each entry contains the following keys: Chris@0: * - title: The displayed title of the link Chris@0: * - route_name: The route_name of the contextual link to be displayed Chris@0: * - group: The group under which the contextual links should be added to. Chris@0: * Possible values are e.g. 'node' or 'menu'. Chris@0: * Chris@0: * @see \Drupal\Core\Menu\ContextualLinkManager Chris@0: * Chris@0: * @ingroup menu Chris@0: */ Chris@0: function hook_contextual_links_plugins_alter(array &$contextual_links) { Chris@0: $contextual_links['menu_edit']['title'] = 'Edit the menu'; Chris@0: } Chris@0: Chris@0: /** Chris@0: * Perform alterations to the breadcrumb built by the BreadcrumbManager. Chris@0: * Chris@0: * @param \Drupal\Core\Breadcrumb\Breadcrumb $breadcrumb Chris@0: * A breadcrumb object returned by BreadcrumbBuilderInterface::build(). Chris@0: * @param \Drupal\Core\Routing\RouteMatchInterface $route_match Chris@0: * The current route match. Chris@0: * @param array $context Chris@0: * May include the following key: Chris@0: * - builder: the instance of Chris@0: * \Drupal\Core\Breadcrumb\BreadcrumbBuilderInterface that constructed this Chris@0: * breadcrumb, or NULL if no builder acted based on the current attributes. Chris@0: * Chris@0: * @ingroup menu Chris@0: */ Chris@0: function hook_system_breadcrumb_alter(\Drupal\Core\Breadcrumb\Breadcrumb &$breadcrumb, \Drupal\Core\Routing\RouteMatchInterface $route_match, array $context) { Chris@0: // Add an item to the end of the breadcrumb. Chris@0: $breadcrumb->addLink(\Drupal\Core\Link::createFromRoute(t('Text'), 'example_route_name')); Chris@0: } Chris@0: Chris@0: /** Chris@0: * Alter the parameters for links. Chris@0: * Chris@0: * @param array $variables Chris@0: * An associative array of variables defining a link. The link may be either a Chris@0: * "route link" using \Drupal\Core\Utility\LinkGenerator::link(), which is Chris@0: * exposed as the 'link_generator' service or a link generated by Chris@0: * \Drupal\Core\Utility\LinkGeneratorInterface::generate(). If the link is a Chris@0: * "route link", 'route_name' will be set; otherwise, 'path' will be set. Chris@0: * The following keys can be altered: Chris@0: * - text: The link text for the anchor tag. If the hook implementation Chris@0: * changes this text it needs to preserve the safeness of the original text. Chris@17: * Using t() or \Drupal\Component\Render\FormattableMarkup with Chris@0: * @placeholder is recommended as this will escape the original text if Chris@0: * necessary. If the resulting text is not marked safe it will be escaped. Chris@0: * - url_is_active: Whether or not the link points to the currently active Chris@0: * URL. Chris@0: * - url: The \Drupal\Core\Url object. Chris@0: * - options: An associative array of additional options that will be passed Chris@0: * to either \Drupal\Core\Utility\UnroutedUrlAssembler::assemble() or Chris@0: * \Drupal\Core\Routing\UrlGenerator::generateFromRoute() to generate the Chris@0: * href attribute for this link, and also used when generating the link. Chris@0: * Defaults to an empty array. It may contain the following elements: Chris@0: * - 'query': An array of query key/value-pairs (without any URL-encoding) to Chris@0: * append to the URL. Chris@0: * - absolute: Whether to force the output to be an absolute link (beginning Chris@0: * with http:). Useful for links that will be displayed outside the site, Chris@0: * such as in an RSS feed. Defaults to FALSE. Chris@0: * - language: An optional language object. May affect the rendering of Chris@0: * the anchor tag, such as by adding a language prefix to the path. Chris@0: * - attributes: An associative array of HTML attributes to apply to the Chris@0: * anchor tag. If element 'class' is included, it must be an array; 'title' Chris@0: * must be a string; other elements are more flexible, as they just need Chris@0: * to work as an argument for the constructor of the class Chris@0: * Drupal\Core\Template\Attribute($options['attributes']). Chris@0: * Chris@0: * @see \Drupal\Core\Utility\UnroutedUrlAssembler::assemble() Chris@0: * @see \Drupal\Core\Routing\UrlGenerator::generateFromRoute() Chris@0: */ Chris@0: function hook_link_alter(&$variables) { Chris@0: // Add a warning to the end of route links to the admin section. Chris@0: if (isset($variables['route_name']) && strpos($variables['route_name'], 'admin') !== FALSE) { Chris@0: $variables['text'] = t('@text (Warning!)', ['@text' => $variables['text']]); Chris@0: } Chris@0: } Chris@0: Chris@0: /** Chris@0: * @} End of "addtogroup hooks". Chris@0: */