annotate core/lib/Drupal/Core/Menu/menu.api.php @ 19:fa3358dc1485 tip

Add ndrum files
author Chris Cannam
date Wed, 28 Aug 2019 13:14:47 +0100
parents af1871eacc83
children
rev   line source
Chris@0 1 <?php
Chris@0 2
Chris@0 3 /**
Chris@0 4 * @file
Chris@0 5 * Hooks and documentation related to the menu system and links.
Chris@0 6 */
Chris@0 7
Chris@0 8 /**
Chris@0 9 * @defgroup menu Menu system
Chris@0 10 * @{
Chris@0 11 * Define the navigation menus, local actions and tasks, and contextual links.
Chris@0 12 *
Chris@0 13 * @section sec_overview Overview and terminology
Chris@0 14 * The menu system uses routes; see the
Chris@0 15 * @link routing Routing API topic @endlink for more information. It is used
Chris@0 16 * for navigation menus, local tasks, local actions, and contextual links:
Chris@0 17 * - Navigation menus are hierarchies of menu links; links point to routes or
Chris@0 18 * URLs.
Chris@0 19 * - Menu links and their hierarchies can be defined by Drupal subsystems
Chris@0 20 * and modules, or created in the user interface using the Menu UI module.
Chris@0 21 * - Local tasks are groups of related routes. Local tasks are usually rendered
Chris@0 22 * as a group of tabs.
Chris@0 23 * - Local actions are used for operations such as adding a new item on a page
Chris@0 24 * that lists items of some type. Local actions are usually rendered as
Chris@0 25 * buttons.
Chris@0 26 * - Contextual links are actions that are related to sections of rendered
Chris@0 27 * output, and are usually rendered as a pop-up list of links. The
Chris@0 28 * Contextual Links module handles the gathering and rendering of contextual
Chris@0 29 * links.
Chris@0 30 *
Chris@0 31 * The following sections of this topic provide an overview of the menu API.
Chris@0 32 * For more detailed information, see
Chris@0 33 * https://www.drupal.org/developing/api/8/menu
Chris@0 34 *
Chris@0 35 * @section sec_links Defining menu links for the administrative menu
Chris@0 36 * Routes for administrative tasks can be added to the main Drupal
Chris@0 37 * administrative menu hierarchy. To do this, add lines like the following to a
Chris@0 38 * module_name.links.menu.yml file (in the top-level directory for your module):
Chris@0 39 * @code
Chris@0 40 * dblog.overview:
Chris@0 41 * title: 'Recent log messages'
Chris@0 42 * parent: system.admin_reports
Chris@0 43 * description: 'View events that have recently been logged.'
Chris@0 44 * route_name: dblog.overview
Chris@18 45 * options:
Chris@18 46 * query:
Chris@18 47 * uid: 1
Chris@0 48 * weight: -1
Chris@0 49 * @endcode
Chris@0 50 * Some notes:
Chris@0 51 * - The first line is the machine name for your menu link, which usually
Chris@0 52 * matches the machine name of the route (given in the 'route_name' line).
Chris@0 53 * - parent: The machine name of the menu link that is the parent in the
Chris@0 54 * administrative hierarchy. See system.links.menu.yml to find the main
Chris@0 55 * skeleton of the hierarchy.
Chris@18 56 * - options: Define additional route options such as query parameters. See
Chris@18 57 * https://www.drupal.org/docs/8/api/menu-api/providing-module-defined-menu-links
Chris@18 58 * for more information.
Chris@0 59 * - weight: Lower (negative) numbers come before higher (positive) numbers,
Chris@0 60 * for menu items with the same parent.
Chris@0 61 *
Chris@0 62 * Discovered menu links from other modules can be altered using
Chris@0 63 * hook_menu_links_discovered_alter().
Chris@0 64 *
Chris@0 65 * @todo Derivatives will probably be defined for these; when they are, add
Chris@0 66 * documentation here.
Chris@0 67 *
Chris@0 68 * @section sec_tasks Defining groups of local tasks (tabs)
Chris@0 69 * Local tasks appear as tabs on a page when there are at least two defined for
Chris@0 70 * a route, including the base route as the main tab, and additional routes as
Chris@0 71 * other tabs. Static local tasks can be defined by adding lines like the
Chris@0 72 * following to a module_name.links.task.yml file (in the top-level directory
Chris@0 73 * for your module):
Chris@0 74 * @code
Chris@0 75 * book.admin:
Chris@0 76 * route_name: book.admin
Chris@0 77 * title: 'List'
Chris@0 78 * base_route: book.admin
Chris@0 79 * book.settings:
Chris@0 80 * route_name: book.settings
Chris@0 81 * title: 'Settings'
Chris@0 82 * base_route: book.admin
Chris@0 83 * weight: 100
Chris@0 84 * @endcode
Chris@0 85 * Some notes:
Chris@0 86 * - The first line is the machine name for your local task, which usually
Chris@0 87 * matches the machine name of the route (given in the 'route_name' line).
Chris@0 88 * - base_route: The machine name of the main task (tab) for the set of local
Chris@0 89 * tasks.
Chris@0 90 * - weight: Lower (negative) numbers come before higher (positive) numbers,
Chris@0 91 * for tasks on the same base route. If there is a tab whose route
Chris@0 92 * matches the base route, that will be the default/first tab shown.
Chris@0 93 *
Chris@0 94 * Local tasks from other modules can be altered using
Chris@0 95 * hook_menu_local_tasks_alter().
Chris@0 96 *
Chris@0 97 * @todo Derivatives are in flux for these; when they are more stable, add
Chris@0 98 * documentation here.
Chris@0 99 *
Chris@0 100 * @section sec_actions Defining local actions for routes
Chris@0 101 * Local actions can be defined for operations related to a given route. For
Chris@0 102 * instance, adding content is a common operation for the content management
Chris@0 103 * page, so it should be a local action. Static local actions can be
Chris@0 104 * defined by adding lines like the following to a
Chris@0 105 * module_name.links.action.yml file (in the top-level directory for your
Chris@0 106 * module):
Chris@0 107 * @code
Chris@0 108 * node.add_page:
Chris@0 109 * route_name: node.add_page
Chris@0 110 * title: 'Add content'
Chris@0 111 * appears_on:
Chris@0 112 * - system.admin_content
Chris@0 113 * @endcode
Chris@0 114 * Some notes:
Chris@0 115 * - The first line is the machine name for your local action, which usually
Chris@0 116 * matches the machine name of the route (given in the 'route_name' line).
Chris@0 117 * - appears_on: Machine names of one or more routes that this local task
Chris@0 118 * should appear on.
Chris@0 119 *
Chris@0 120 * Local actions from other modules can be altered using
Chris@0 121 * hook_menu_local_actions_alter().
Chris@0 122 *
Chris@0 123 * @todo Derivatives are in flux for these; when they are more stable, add
Chris@0 124 * documentation here.
Chris@0 125 *
Chris@0 126 * @section sec_contextual Defining contextual links
Chris@0 127 * Contextual links are displayed by the Contextual Links module for user
Chris@0 128 * interface elements whose render arrays have a '#contextual_links' element
Chris@0 129 * defined. For example, a block render array might look like this, in part:
Chris@0 130 * @code
Chris@0 131 * array(
Chris@0 132 * '#contextual_links' => array(
Chris@0 133 * 'block' => array(
Chris@0 134 * 'route_parameters' => array('block' => $entity->id()),
Chris@0 135 * ),
Chris@0 136 * ),
Chris@0 137 * @endcode
Chris@0 138 * In this array, the outer key 'block' defines a "group" for contextual
Chris@0 139 * links, and the inner array provides values for the route's placeholder
Chris@0 140 * parameters (see @ref sec_placeholders above).
Chris@0 141 *
Chris@0 142 * To declare that a defined route should be a contextual link for a
Chris@0 143 * contextual links group, put lines like the following in a
Chris@0 144 * module_name.links.contextual.yml file (in the top-level directory for your
Chris@0 145 * module):
Chris@0 146 * @code
Chris@0 147 * block_configure:
Chris@0 148 * title: 'Configure block'
Chris@0 149 * route_name: 'entity.block.edit_form'
Chris@0 150 * group: 'block'
Chris@0 151 * @endcode
Chris@0 152 * Some notes:
Chris@0 153 * - The first line is the machine name for your contextual link, which usually
Chris@0 154 * matches the machine name of the route (given in the 'route_name' line).
Chris@0 155 * - group: This needs to match the link group defined in the render array.
Chris@0 156 *
Chris@0 157 * Contextual links from other modules can be altered using
Chris@0 158 * hook_contextual_links_alter().
Chris@0 159 *
Chris@0 160 * @todo Derivatives are in flux for these; when they are more stable, add
Chris@0 161 * documentation here.
Chris@0 162 *
Chris@0 163 * @section sec_rendering Rendering menus
Chris@0 164 * Once you have created menus (that contain menu links), you want to render
Chris@0 165 * them. Drupal provides a block (Drupal\system\Plugin\Block\SystemMenuBlock) to
Chris@0 166 * do so.
Chris@0 167 *
Chris@0 168 * However, perhaps you have more advanced needs and you're not satisfied with
Chris@0 169 * what the menu blocks offer you. If that's the case, you'll want to:
Chris@0 170 * - Instantiate \Drupal\Core\Menu\MenuTreeParameters, and set its values to
Chris@0 171 * match your needs. Alternatively, you can use
Chris@0 172 * MenuLinkTree::getCurrentRouteMenuTreeParameters() to get a typical
Chris@0 173 * default set of parameters, and then customize them to suit your needs.
Chris@0 174 * - Call \Drupal\Core\MenuLinkTree::load() with your menu link tree parameters,
Chris@0 175 * this will return a menu link tree.
Chris@0 176 * - Pass the menu tree to \Drupal\Core\Menu\MenuLinkTree::transform() to apply
Chris@0 177 * menu link tree manipulators that transform the tree. You will almost always
Chris@0 178 * want to apply access checking. The manipulators that you will typically
Chris@0 179 * need can be found in \Drupal\Core\Menu\DefaultMenuLinkTreeManipulators.
Chris@0 180 * - Potentially write a custom menu tree manipulator, see
Chris@0 181 * \Drupal\Core\Menu\DefaultMenuLinkTreeManipulators for examples. This is
Chris@0 182 * only necessary if you want to do things like adding extra metadata to
Chris@0 183 * rendered links to display icons next to them.
Chris@0 184 * - Pass the menu tree to \Drupal\Core\Menu\MenuLinkTree::build(), this will
Chris@0 185 * build a renderable array.
Chris@0 186 *
Chris@0 187 * Combined, that would look like this:
Chris@0 188 * @code
Chris@0 189 * $menu_tree = \Drupal::menuTree();
Chris@0 190 * $menu_name = 'my_menu';
Chris@0 191 *
Chris@0 192 * // Build the typical default set of menu tree parameters.
Chris@0 193 * $parameters = $menu_tree->getCurrentRouteMenuTreeParameters($menu_name);
Chris@0 194 *
Chris@0 195 * // Load the tree based on this set of parameters.
Chris@0 196 * $tree = $menu_tree->load($menu_name, $parameters);
Chris@0 197 *
Chris@0 198 * // Transform the tree using the manipulators you want.
Chris@0 199 * $manipulators = array(
Chris@0 200 * // Only show links that are accessible for the current user.
Chris@0 201 * array('callable' => 'menu.default_tree_manipulators:checkAccess'),
Chris@0 202 * // Use the default sorting of menu links.
Chris@0 203 * array('callable' => 'menu.default_tree_manipulators:generateIndexAndSort'),
Chris@0 204 * );
Chris@0 205 * $tree = $menu_tree->transform($tree, $manipulators);
Chris@0 206 *
Chris@0 207 * // Finally, build a renderable array from the transformed tree.
Chris@0 208 * $menu = $menu_tree->build($tree);
Chris@0 209 *
Chris@16 210 * $menu_html = \Drupal::service('renderer')->render($menu);
Chris@0 211 * @endcode
Chris@0 212 *
Chris@0 213 * @}
Chris@0 214 */
Chris@0 215
Chris@0 216 /**
Chris@0 217 * @addtogroup hooks
Chris@0 218 * @{
Chris@0 219 */
Chris@0 220
Chris@0 221 /**
Chris@0 222 * Alters all the menu links discovered by the menu link plugin manager.
Chris@0 223 *
Chris@0 224 * @param array $links
Chris@0 225 * The link definitions to be altered.
Chris@0 226 *
Chris@0 227 * @return array
Chris@0 228 * An array of discovered menu links. Each link has a key that is the machine
Chris@0 229 * name, which must be unique. By default, use the route name as the
Chris@0 230 * machine name. In cases where multiple links use the same route name, such
Chris@0 231 * as two links to the same page in different menus, or two links using the
Chris@0 232 * same route name but different route parameters, the suggested machine name
Chris@0 233 * patten is the route name followed by a dot and a unique suffix. For
Chris@0 234 * example, an additional logout link might have a machine name of
Chris@0 235 * user.logout.navigation, and default links provided to edit the article and
Chris@0 236 * page content types could use machine names
Chris@0 237 * entity.node_type.edit_form.article and entity.node_type.edit_form.page.
Chris@0 238 * Since the machine name may be arbitrary, you should never write code that
Chris@0 239 * assumes it is identical to the route name.
Chris@0 240 *
Chris@0 241 * The value corresponding to each machine name key is an associative array
Chris@0 242 * that may contain the following key-value pairs:
Chris@0 243 * - title: (required) The title of the menu link. If this should be
Chris@0 244 * translated, create a \Drupal\Core\StringTranslation\TranslatableMarkup
Chris@0 245 * object.
Chris@0 246 * - description: The description of the link. If this should be
Chris@0 247 * translated, create a \Drupal\Core\StringTranslation\TranslatableMarkup
Chris@0 248 * object.
Chris@0 249 * - route_name: (optional) The route name to be used to build the path.
Chris@0 250 * Either the route_name or url element must be provided.
Chris@0 251 * - route_parameters: (optional) The route parameters to build the path.
Chris@0 252 * - url: (optional) If you have an external link use this element instead of
Chris@0 253 * providing route_name.
Chris@0 254 * - parent: (optional) The machine name of the link that is this link's menu
Chris@0 255 * parent.
Chris@0 256 * - weight: (optional) An integer that determines the relative position of
Chris@0 257 * items in the menu; higher-weighted items sink. Defaults to 0. Menu items
Chris@0 258 * with the same weight are ordered alphabetically.
Chris@0 259 * - menu_name: (optional) The machine name of a menu to put the link in, if
Chris@0 260 * not the default Tools menu.
Chris@0 261 * - expanded: (optional) If set to TRUE, and if a menu link is provided for
Chris@0 262 * this menu item (as a result of other properties), then the menu link is
Chris@0 263 * always expanded, equivalent to its 'always expanded' checkbox being set
Chris@0 264 * in the UI.
Chris@0 265 * - options: (optional) An array of options to be passed to
Chris@0 266 * \Drupal\Core\Utility\LinkGeneratorInterface::generate() when generating
Chris@0 267 * a link from this menu item.
Chris@0 268 *
Chris@0 269 * @ingroup menu
Chris@0 270 */
Chris@0 271 function hook_menu_links_discovered_alter(&$links) {
Chris@0 272 // Change the weight and title of the user.logout link.
Chris@0 273 $links['user.logout']['weight'] = -10;
Chris@0 274 $links['user.logout']['title'] = new \Drupal\Core\StringTranslation\TranslatableMarkup('Logout');
Chris@0 275 // Conditionally add an additional link with a title that's not translated.
Chris@0 276 if (\Drupal::moduleHandler()->moduleExists('search')) {
Chris@0 277 $links['menu.api.search'] = [
Chris@0 278 'title' => \Drupal::config('system.site')->get('name'),
Chris@0 279 'route_name' => 'menu.api.search',
Chris@0 280 'description' => new \Drupal\Core\StringTranslation\TranslatableMarkup('View popular search phrases for this site.'),
Chris@0 281 'parent' => 'system.admin_reports',
Chris@0 282 ];
Chris@0 283 }
Chris@0 284 }
Chris@0 285
Chris@0 286 /**
Chris@0 287 * Alter local tasks displayed on the page before they are rendered.
Chris@0 288 *
Chris@0 289 * This hook is invoked by \Drupal\Core\Menu\LocalTaskManager::getLocalTasks().
Chris@0 290 * The system-determined tabs and actions are passed in by reference. Additional
Chris@0 291 * tabs may be added.
Chris@0 292 *
Chris@0 293 * The local tasks are under the 'tabs' element and keyed by plugin ID.
Chris@0 294 *
Chris@0 295 * Each local task is an associative array containing:
Chris@0 296 * - #theme: The theme function to use to render.
Chris@0 297 * - #link: An associative array containing:
Chris@0 298 * - title: The localized title of the link.
Chris@0 299 * - url: a Url object.
Chris@0 300 * - localized_options: An array of options to pass to
Chris@0 301 * \Drupal\Core\Utility\LinkGeneratorInterface::generate().
Chris@0 302 * - #weight: The link's weight compared to other links.
Chris@0 303 * - #active: Whether the link should be marked as 'active'.
Chris@0 304 *
Chris@0 305 * @param array $data
Chris@0 306 * An associative array containing list of (up to 2) tab levels that contain a
Chris@0 307 * list of tabs keyed by their href, each one being an associative array
Chris@0 308 * as described above.
Chris@0 309 * @param string $route_name
Chris@0 310 * The route name of the page.
Chris@16 311 * @param \Drupal\Core\Cache\RefinableCacheableDependencyInterface $cacheability
Chris@16 312 * The cacheability metadata for the current route's local tasks.
Chris@0 313 *
Chris@0 314 * @ingroup menu
Chris@0 315 */
Chris@16 316 function hook_menu_local_tasks_alter(&$data, $route_name, \Drupal\Core\Cache\RefinableCacheableDependencyInterface &$cacheability) {
Chris@0 317
Chris@0 318 // Add a tab linking to node/add to all pages.
Chris@0 319 $data['tabs'][0]['node.add_page'] = [
Chris@0 320 '#theme' => 'menu_local_task',
Chris@0 321 '#link' => [
Chris@0 322 'title' => t('Example tab'),
Chris@0 323 'url' => Url::fromRoute('node.add_page'),
Chris@0 324 'localized_options' => [
Chris@0 325 'attributes' => [
Chris@0 326 'title' => t('Add content'),
Chris@0 327 ],
Chris@0 328 ],
Chris@0 329 ],
Chris@0 330 ];
Chris@16 331 // The tab we're adding is dependent on a user's access to add content.
Chris@16 332 $cacheability->addCacheTags(['user.permissions']);
Chris@0 333 }
Chris@0 334
Chris@0 335 /**
Chris@0 336 * Alter local actions plugins.
Chris@0 337 *
Chris@0 338 * @param array $local_actions
Chris@0 339 * The array of local action plugin definitions, keyed by plugin ID.
Chris@0 340 *
Chris@0 341 * @see \Drupal\Core\Menu\LocalActionInterface
Chris@0 342 * @see \Drupal\Core\Menu\LocalActionManager
Chris@0 343 *
Chris@0 344 * @ingroup menu
Chris@0 345 */
Chris@0 346 function hook_menu_local_actions_alter(&$local_actions) {
Chris@0 347 }
Chris@0 348
Chris@0 349 /**
Chris@0 350 * Alter local tasks plugins.
Chris@0 351 *
Chris@0 352 * @param array $local_tasks
Chris@0 353 * The array of local tasks plugin definitions, keyed by plugin ID.
Chris@0 354 *
Chris@0 355 * @see \Drupal\Core\Menu\LocalTaskInterface
Chris@0 356 * @see \Drupal\Core\Menu\LocalTaskManager
Chris@0 357 *
Chris@0 358 * @ingroup menu
Chris@0 359 */
Chris@0 360 function hook_local_tasks_alter(&$local_tasks) {
Chris@0 361 // Remove a specified local task plugin.
Chris@0 362 unset($local_tasks['example_plugin_id']);
Chris@0 363 }
Chris@0 364
Chris@0 365 /**
Chris@0 366 * Alter contextual links before they are rendered.
Chris@0 367 *
Chris@0 368 * This hook is invoked by
Chris@0 369 * \Drupal\Core\Menu\ContextualLinkManager::getContextualLinkPluginsByGroup().
Chris@0 370 * The system-determined contextual links are passed in by reference. Additional
Chris@0 371 * links may be added and existing links can be altered.
Chris@0 372 *
Chris@0 373 * Each contextual link contains the following entries:
Chris@0 374 * - title: The localized title of the link.
Chris@0 375 * - route_name: The route name of the link.
Chris@0 376 * - route_parameters: The route parameters of the link.
Chris@0 377 * - localized_options: An array of URL options.
Chris@0 378 * - (optional) weight: The weight of the link, which is used to sort the links.
Chris@0 379 *
Chris@0 380 *
Chris@0 381 * @param array $links
Chris@0 382 * An associative array containing contextual links for the given $group,
Chris@0 383 * as described above. The array keys are used to build CSS class names for
Chris@0 384 * contextual links and must therefore be unique for each set of contextual
Chris@0 385 * links.
Chris@0 386 * @param string $group
Chris@0 387 * The group of contextual links being rendered.
Chris@0 388 * @param array $route_parameters
Chris@0 389 * The route parameters passed to each route_name of the contextual links.
Chris@0 390 * For example:
Chris@0 391 * @code
Chris@0 392 * array('node' => $node->id())
Chris@0 393 * @endcode
Chris@0 394 *
Chris@0 395 * @see \Drupal\Core\Menu\ContextualLinkManager
Chris@0 396 *
Chris@0 397 * @ingroup menu
Chris@0 398 */
Chris@0 399 function hook_contextual_links_alter(array &$links, $group, array $route_parameters) {
Chris@0 400 if ($group == 'menu') {
Chris@0 401 // Dynamically use the menu name for the title of the menu_edit contextual
Chris@0 402 // link.
Chris@0 403 $menu = \Drupal::entityManager()->getStorage('menu')->load($route_parameters['menu']);
Chris@0 404 $links['menu_edit']['title'] = t('Edit menu: @label', ['@label' => $menu->label()]);
Chris@0 405 }
Chris@0 406 }
Chris@0 407
Chris@0 408 /**
Chris@0 409 * Alter the plugin definition of contextual links.
Chris@0 410 *
Chris@0 411 * @param array $contextual_links
Chris@0 412 * An array of contextual_links plugin definitions, keyed by contextual link
Chris@0 413 * ID. Each entry contains the following keys:
Chris@0 414 * - title: The displayed title of the link
Chris@0 415 * - route_name: The route_name of the contextual link to be displayed
Chris@0 416 * - group: The group under which the contextual links should be added to.
Chris@0 417 * Possible values are e.g. 'node' or 'menu'.
Chris@0 418 *
Chris@0 419 * @see \Drupal\Core\Menu\ContextualLinkManager
Chris@0 420 *
Chris@0 421 * @ingroup menu
Chris@0 422 */
Chris@0 423 function hook_contextual_links_plugins_alter(array &$contextual_links) {
Chris@0 424 $contextual_links['menu_edit']['title'] = 'Edit the menu';
Chris@0 425 }
Chris@0 426
Chris@0 427 /**
Chris@0 428 * Perform alterations to the breadcrumb built by the BreadcrumbManager.
Chris@0 429 *
Chris@0 430 * @param \Drupal\Core\Breadcrumb\Breadcrumb $breadcrumb
Chris@0 431 * A breadcrumb object returned by BreadcrumbBuilderInterface::build().
Chris@0 432 * @param \Drupal\Core\Routing\RouteMatchInterface $route_match
Chris@0 433 * The current route match.
Chris@0 434 * @param array $context
Chris@0 435 * May include the following key:
Chris@0 436 * - builder: the instance of
Chris@0 437 * \Drupal\Core\Breadcrumb\BreadcrumbBuilderInterface that constructed this
Chris@0 438 * breadcrumb, or NULL if no builder acted based on the current attributes.
Chris@0 439 *
Chris@0 440 * @ingroup menu
Chris@0 441 */
Chris@0 442 function hook_system_breadcrumb_alter(\Drupal\Core\Breadcrumb\Breadcrumb &$breadcrumb, \Drupal\Core\Routing\RouteMatchInterface $route_match, array $context) {
Chris@0 443 // Add an item to the end of the breadcrumb.
Chris@0 444 $breadcrumb->addLink(\Drupal\Core\Link::createFromRoute(t('Text'), 'example_route_name'));
Chris@0 445 }
Chris@0 446
Chris@0 447 /**
Chris@0 448 * Alter the parameters for links.
Chris@0 449 *
Chris@0 450 * @param array $variables
Chris@0 451 * An associative array of variables defining a link. The link may be either a
Chris@0 452 * "route link" using \Drupal\Core\Utility\LinkGenerator::link(), which is
Chris@0 453 * exposed as the 'link_generator' service or a link generated by
Chris@0 454 * \Drupal\Core\Utility\LinkGeneratorInterface::generate(). If the link is a
Chris@0 455 * "route link", 'route_name' will be set; otherwise, 'path' will be set.
Chris@0 456 * The following keys can be altered:
Chris@0 457 * - text: The link text for the anchor tag. If the hook implementation
Chris@0 458 * changes this text it needs to preserve the safeness of the original text.
Chris@17 459 * Using t() or \Drupal\Component\Render\FormattableMarkup with
Chris@0 460 * @placeholder is recommended as this will escape the original text if
Chris@0 461 * necessary. If the resulting text is not marked safe it will be escaped.
Chris@0 462 * - url_is_active: Whether or not the link points to the currently active
Chris@0 463 * URL.
Chris@0 464 * - url: The \Drupal\Core\Url object.
Chris@0 465 * - options: An associative array of additional options that will be passed
Chris@0 466 * to either \Drupal\Core\Utility\UnroutedUrlAssembler::assemble() or
Chris@0 467 * \Drupal\Core\Routing\UrlGenerator::generateFromRoute() to generate the
Chris@0 468 * href attribute for this link, and also used when generating the link.
Chris@0 469 * Defaults to an empty array. It may contain the following elements:
Chris@0 470 * - 'query': An array of query key/value-pairs (without any URL-encoding) to
Chris@0 471 * append to the URL.
Chris@0 472 * - absolute: Whether to force the output to be an absolute link (beginning
Chris@0 473 * with http:). Useful for links that will be displayed outside the site,
Chris@0 474 * such as in an RSS feed. Defaults to FALSE.
Chris@0 475 * - language: An optional language object. May affect the rendering of
Chris@0 476 * the anchor tag, such as by adding a language prefix to the path.
Chris@0 477 * - attributes: An associative array of HTML attributes to apply to the
Chris@0 478 * anchor tag. If element 'class' is included, it must be an array; 'title'
Chris@0 479 * must be a string; other elements are more flexible, as they just need
Chris@0 480 * to work as an argument for the constructor of the class
Chris@0 481 * Drupal\Core\Template\Attribute($options['attributes']).
Chris@0 482 *
Chris@0 483 * @see \Drupal\Core\Utility\UnroutedUrlAssembler::assemble()
Chris@0 484 * @see \Drupal\Core\Routing\UrlGenerator::generateFromRoute()
Chris@0 485 */
Chris@0 486 function hook_link_alter(&$variables) {
Chris@0 487 // Add a warning to the end of route links to the admin section.
Chris@0 488 if (isset($variables['route_name']) && strpos($variables['route_name'], 'admin') !== FALSE) {
Chris@0 489 $variables['text'] = t('@text (Warning!)', ['@text' => $variables['text']]);
Chris@0 490 }
Chris@0 491 }
Chris@0 492
Chris@0 493 /**
Chris@0 494 * @} End of "addtogroup hooks".
Chris@0 495 */