In Drupal module development, local tasks (often referred to as tabs) provide a way to create a tabbed navigation interface. This feature allows users to easily switch between different views or actions related to a specific context or resource. In this lesson, we will explore the setup and use of local tasks using the .links.task.yml file to enhance user navigation in your custom modules.
Understanding Local Tasks in Drupal
Local tasks in Drupal enable the presentation of a series of related or contextual actions in a tabbed interface. This is commonly used across Drupal admin and user interfaces to switch between related views or actions, such as edit and view tabs for content entities. By organizing functionalities into tabs, you can present users with a clean and intuitive navigation structure.
Setting Up Local Tasks
To provide users with such tabbed interfaces within your custom module, you'll use the .links.task.yml file. Let's explore the process in detail:
Step 1: Create the .links.task.yml File
In your module's directory, create a .links.task.yml file if it doesn't already exist. This file will define the local tasks you want to implement:
touch my_rest_module.links.task.yml
Step 2: Define Local Tasks in YAML
Open the my_rest_module.links.task.yml file and add the configuration for your local tasks:
my_rest_module.overview:
route_name: my_rest_module.overview
title: 'Overview'
base_route: my_rest_module.main
weight: 0
my_rest_module.settings:
route_name: my_rest_module.settings_form
title: 'Settings'
base_route: my_rest_module.main
weight: 10
In this YAML file, two local tasks are defined:
- my_rest_module.overview: Creates an "Overview" tab, linking to the route defined as
my_rest_module.overview. - my_rest_module.settings: Creates a "Settings" tab, pointing to the settings form, linking to the route
my_rest_module.settings_form.
Field Descriptions
- route_name: The route name to which the tab links.
- title: The text label for the tab.
- base_route: The base route this set of tasks is tied to, creating a logical grouping under this initial route context.
- weight: Determines the order of the tabs, with lower numbers appearing first.
Associating Routes with Local Tasks
Ensure that each route_name used in the local tasks corresponds with a defined route in your module’s .routing.yml. Below is an example of defining these routes in my_rest_module.routing.yml:
my_rest_module.main:
path: '/admin/my-rest-module'
defaults:
_title: 'My REST Module'
requirements:
_permission: 'administer my rest module'
my_rest_module.overview:
path: '/admin/my-rest-module/overview'
defaults:
_controller: '\Drupal\my_rest_module\Controller\OverviewController::content'
_title: 'Overview'
requirements:
_permission: 'administer my rest module'
my_rest_module.settings_form:
path: '/admin/my-rest-module/settings'
defaults:
_form: '\Drupal\my_rest_module\Form\SettingsForm'
_title: 'Settings'
requirements:
_permission: 'administer my rest module'
The base route my_rest_module.main anchors the local tasks, serving as their common context.
Testing Your Local Task Implementation
After configuring your .links.task.yml and corresponding routes, clear your cache to apply changes:
drush cr
Visit the base route path in the Drupal admin interface and verify if the defined tabs appear in the desired order. Check that clicks on each tab navigate correctly to the associated route path.
Conclusion
By using local tasks, you can significantly enhance the organization and accessibility of features within your Drupal modules. Local tasks, presented as tabs, offer intuitive navigation for users, streamlining the process of managing complex interactions in a coherent manner.
What’s Next?
After mastering the setup of local tasks, making the user interface more actionable is the next step. In our upcoming lesson, we'll dive into Adding Action Links in .links.action.yml, exploring how to implement direct-action links that integrate seamlessly into your Drupal modules’ navigation.