Menu links, tabs and action buttons

A route creates a page, but nothing links to it — you have to know the address. To make the page appear in the site menu, in tabs or as a button, the module adds one more small YAML file. All three files live in the root of the module folder and are created by hand.

# web/modules/custom/blog/blog.links.menu.yml
blog.list:
  title: 'Blog'
  route_name: blog.list
  menu_name: main

After drush cr the main menu of the site gets a Blog item leading to /blog. The link names not an address but a route from blog.routing.yml.

Key	Meaning
`blog.list`	The link name. It is handy to repeat the route name
`title`	The text of the menu item
`route_name`	The route the link leads to
`menu_name`	The menu: `main` — main navigation, `footer` — footer, `admin` — the panel
`weight`	The order: the smaller the number, the higher the item
`parent`	The name of the parent link for a nested item

A nested item

# web/modules/custom/blog/blog.links.menu.yml
blog.about:
  title: 'About the blog'
  route_name: blog.about
  menu_name: main
  parent: blog.list
  weight: 10

The About the blog item becomes a child of Blog. Whether it is visible depends on the menu block settings in the theme: by default the main menu shows one level.

A link in the panel

Settings pages are placed in the panel menu by naming one of the Configuration sections as the parent:

# web/modules/custom/blog/blog.links.menu.yml
blog.settings:
  title: 'Blog settings'
  description: 'The number of articles per page and the title.'
  route_name: blog.settings
  parent: system.admin_config_content

The link appears on the Configuration page in the Content authoring group. The blog.settings route is created in the lesson about configuration forms — add this entry then.

Tabs

Tabs join several pages of one section. They are described in the file blog.links.task.yml:

# web/modules/custom/blog/blog.links.task.yml
blog.list_tab:
  title: 'Articles'
  route_name: blog.list
  base_route: blog.list
 
blog.about_tab:
  title: 'About the blog'
  route_name: blog.about
  base_route: blog.list

The pages /blog and /blog/about get two tabs. base_route is the route the tab group belongs to; the tab where it equals route_name is the default one.

An action button

An action button is a prominent link at the top of a page, usually "Add…". The file blog.links.action.yml:

# web/modules/custom/blog/blog.links.action.yml
blog.add_article:
  title: 'Add article'
  route_name: node.add
  route_parameters:
    node_type: article
  appears_on:
    - blog.list

The /blog page gets a button leading to the article creation form /node/add/article. appears_on lists the routes where the button is shown. Only those allowed to open the node.add route see it.

Common mistake

Menu links, tabs and buttons check access to the route: if the visitor lacks the permission, the item is simply not shown. So a "missing" link is most often a cache that was not rebuilt, a typo in route_name, or you looking at the site as an anonymous visitor for whom the route is closed. Run drush cr and check the route name.

Thanks for reading!

A menu link