Providing module-defined local actions
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
You can:
- Log in, click Edit, and edit this page
- Log in, click Discuss, update the Page status value, and suggest an improvement
- Log in and create a Documentation issue with your suggestion