Drupal provides module developers several different methods for creating the different types of links we see on a typical page. In this tutorial we'll see how these different types of links relate to each other, and when you might want to make use of them.
In this tutorial we'll get an overview of:
- Menu links
- Action links
- Local tasks
- Contextual links
- Learn the differences between the various types of links available to module developers
- Understand when to use each type of link
If a module wants to add a link to a menu in Drupal, it can do so by providing a menu link. From a high level these links are provided by custom modules by including a YAML file. Browsing Drupal core you will see that several modules include menu links. You can identify them by looking for files that end with the extension .links.menu.yml. For example, the Node module defines two menu links in the file core/modules/node/node.links.menu.yml
entity.node_type.collection: title: 'Content types' parent: system.admin_structure description: 'Create and manage fields, forms, and display settings for your content.' route_name: entity.node_type.collection node.add_page: title: 'Add content' route_name: node.add_page
We will take a more in-depth look at the various options for menu links this in the tutorial, Add a Menu Link.
While logged in as a site administrator, if you come across a link to add another item, chances are you're looking at an action link. Action links allow module developers to provide particular actions for working with their data structures. An example of this can be seen on the content type administration screen (/admin/structure/types) with the "Add content type" button. Actions are specified in yet another YAML file with a particular naming convention .links.action.yml. Again using the Node module as an example, here is the contents of the /core/modules/node/node.links.action.yml file:
node.type_add: route_name: node.type_add title: 'Add content type' appears_on: - entity.node_type.collection node.add_page: route_name: node.add_page title: 'Add content' appears_on: - system.admin_content
The options available for configuring action links are covered in more detail in the tutorial, Add an Action Link.
Local task links
Local tasks are by default rendered as tabs available to authenticated users. If you've ever visited a node page and clicked on the edit link you've clicked a local task link to reach the edit form. These links are also defined within a particularly named YAML file with the extension .links.task.yml. The node module provides several local tasks. We can see that by looking at core/modules/node/node.links.task.yml.
entity.node.canonical: route_name: entity.node.canonical base_route: entity.node.canonical title: 'View' entity.node.edit_form: route_name: entity.node.edit_form base_route: entity.node.canonical title: Edit entity.node.delete_form: route_name: entity.node.delete_form base_route: entity.node.canonical title: Delete weight: 10 entity.node.version_history: route_name: entity.node.version_history base_route: entity.node.canonical title: 'Revisions' weight: 20 entity.node_type.edit_form: title: 'Edit' route_name: entity.node_type.edit_form base_route: entity.node_type.edit_form entity.node_type.collection: title: List route_name: entity.node_type.collection base_route: entity.node_type.collection
All of the options relevant to local task links will be covered in the tutorial, Add a Local Task Link.
Contextual links provide shortcuts to common administrator tasks. For example, when viewing a node, common actions may include editing or deleting the content. Contextual links provided by the node module make that easier.
Contextual links, unlike the links we've looked at so far, are not only specified via a YAML file. Contextual links should identify the particular route (named URL path) that will be used as contextual links. These routes are listed in a YAML file with the .links.contextual.yml extension. In addition to the YAML file a contextual link needs to add a
#contextual_links element to the render array where the link needs to appear. Returning to the node module for an example we can find the /core/modules/node/node.links.contextual.yml file:
entity.node.edit_form: route_name: entity.node.edit_form group: node title: Edit entity.node.delete_form: route_name: entity.node.delete_form group: node title: Delete weight: 10
We'll cover all of the options for the contextual links YAML file, as well as how to add the
#contextual_links render array element in the tutorial, Add a Contextual Link.
In this tutorial, we looked at the four major types of links we can provide from a custom module. We looked at the hopefully familiar implementation of each of them from core's node module. Menu links provide module developers a way to add any particular link to Drupal's menu system. Action links allow developers to add buttons for particular behaviors like adding additional items. Local tasks can help group commonly needed tasks around working with a particular entity. Contextual links provide another avenue to provide these types of links with a less obtrusive UI pattern.
Further your understanding
- Navigate around your Drupal site and try to identify some Menu, Action, Local task and Contextual links. Can you find their implementation in your codebase?
- When would you choose to use a Local task link? When might a Contextual link be more appropriate?
- Can you find where the
#contextual_linksrender element is added within the node module? New to render elements? Start with a Render API Overview.
- Each of these types of links are different plugins. While you probably don't need to know the details of the plugin system to understand how to create links, our What Are Plugins tutorial provides a good starting point if you're curious.