Providing module-defined local actions

Last updated on
14 November 2023

This documentation needs work. See "Help improve this page" in the sidebar.

Local actions have also been moved out of the hook_menu() system in Drupal 8 and are very similar to local tasks. Use actions to define local operations such as adding new items to an administrative list (menus, contact categories, etc).

Local actions are defined in a YAML format, named after the module they are defined by. Such as menu_ui.links.action.yml for this example from menu_ui module:

menu_ui.link_add:
  route_name: menu_ui.link_add
  title: 'Add link'
  appears_on:
    - menu_ui.menu_edit

menu_ui.menu_add:
  route_name: menu_ui.menu_add
  title: 'Add menu'
  appears_on:
    - menu_ui.overview_page

These actions appear like the following:

As with local tasks, best practice is to name the local actions the same as the route for the action. Specify the route in a route_name key and provide a title that appears on the local action button. You can also specify a title_context to disambiguate text that may have multiple meanings.

Finally, the appears_on key is used to define a list of routes where this action will appear. You can specify multiple routes in a list.

Using route parameters and weight

If you'd like to use routes that require one or more parameters, you can use route_parameters to define values for those parameters. Also, you can use weight to change the order in which your local actions appear.

For example, to add a node of type page, use:

node.add_content_page:
  route_name: node.add
  route_parameters:
    node_type: page
  title: 'Add page'
  appears_on:
    - system.admin_content
  weight: -10

Dynamic local action generation

You can also implement dynamic local action generation along the same line as for local tasks. Provide a class in the deriver key of your example.links.action.yml file and implement that class based on \Drupal\Component\Plugin\Derivative\DeriverBase. Make sure to provide the keys in the same way in array format. See the example in the local tasks documentation.

Customizing local action behaviour

The default local action implementation is in LocalActionDefault. You can extend this class and modify the behaviour of a desired local action by providing the class on the local action. Such as to use a dynamic title for a local action:

<?php

namespace Drupal\example\Plugin\Menu\LocalAction;

use Drupal\Core\Menu\LocalActionDefault;
use Drupal\Core\StringTranslation\TranslatableMarkup;

/**
 * Defines a local action plugin with a dynamic title.
 */
class CustomLocalAction extends LocalActionDefault {

  /**
   * {@inheritdoc}
   */
  public function getTitle() {
    $title = new TranslatableMarkup("My @arg action", array(
      '@arg' => 'dynamic-title',
    ));
    return $title;
  }

}

And refer this class in your example.links.action.yml file:

example.content.action:
  route_name: example.content.action
  title: 'Example dynamic title action'
  weight: -20
  class: '\Drupal\example\Plugin\Menu\LocalAction\CustomLocalAction'
  appears_on:
    - example.content

Altering existing local actions

To alter existing local actions, use hook_menu_local_actions_alter.

Help improve this page

Page status: Needs work

You can: