Last updated October 22, 2018

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.

Link types illustrated

In this tutorial we'll get an overview of:

  • Menu links
  • Action links
  • Local tasks
  • Contextual links

Goal

  • Learn the differences between the various types of links available to module developers
  • Understand when to use each type of link

Prerequisites

Menu links

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 tutoria, Add a Menu Link.

Action links

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

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 on a node

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.

Recap

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_links render 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.

Additional resources