Menu items toevoegen in een Drupal 8 module

Algemeen

Om een route, door je module gedefinieerd in het .routing.yml-bestand, in één van de bestaande menu's te laten verschijnen, voegen we een .links.menu.yml configuratiebestand aan de module toe. De inhoud ziet er ongeveer als volgt uit en moet tenminste de volgende regels bevatten (voorbeeld uit dblog.links.menu.yml):

dblog.overview:
  title: 'Recent log messages'
  description: 'View events that have recently been logged.'
  route_name: dblog.overview
  parent: system.admin_reports
  menu_name: admin

Deze regels hebben de volgende betekenis:

dblog.overview:

Dit is de machine-name van de menu-link. Hoewel elke naam voldoet, schrijven Drupal 8's best practices voor dat de machine-name bestaat uit <modulenaam>.<routenaam>.

title: 'Recent log messages'
description: 'View events that have recently been logged.'

Deze 2 entries spreken voor zich en zijn bovendien bekend voor wie gewend is om Drupal 7 modules te schrijven. De betekenis van deze 2 regels is gelijk aan die in de vroegere hook_menu(), namelijk linktekst en het link title attribuut.

route_name: dblog.overview

Met deze regel vertel je Drupal over welke entry uit je routing bestand dit menu-item gaat. De route_name is de machine-name van de bedoelde routing entry. Vanwege Drupal's naming conventions voor .yml-bestanden zal deze doorgaans gelijk zijn aan de machine-name van menu-link zelf.

menu_name vs parent

parent: system.admin_reports
menu_name: admin

menu_name en parent zijn verwante entries, in die zin dat ze beiden aan Drupal iets vertellen over waar de menulink tenslotte zal verschijnen. parent vertelt wat het bovenliggende onderdeel van het menu-item moet worden, terwijl menu_name vertelt in welk menu de link moet verschijnen.

menu_name gebruikt de machine-name van één van de bestaande menu's, parent echter gebruikt de machine-name van een bestaand menu-item.

menu_name en parent tegelijk gebruiken lijkt praktisch zinloos en dat is het ook: menu_name zal genegeerd worden als parent aanwezig is. Sowieso zal parent doorgaans worden gebruikt in het beheermenu, terwijl menu_name vaker zal worden toegepast in end-user menu's, omdat in laatste geval zelden te voorspellen is welke parents een site bevat, laat staan dat we tijdens het schrijven van een module een voorkeur kunnen definieren. In beheermenu's daarentegen, met z'n (gedeeltelijk) vaste onderdelen, is het vaak prettig om te kunnen vastleggen onder welk menu-onderdeel de link zal verschijnen.

De waarde voor parent vaststellen

Er bestaat geen vaste receptuur om er achter te komen welke waarde voor parent moet worden gebruikt. Voor de vaste menu-onderdelen (content, development, appearance) in het beheermenu weet je echter dat deze alle door de system module worden gedefinieerd. De bijbehorende machine-names zijn dan ook te vinden in system.links.menu.yml. Om bijvoorbeeld een link onder de Configuration-sectie in het beheermenu te plaatsen, gebruik je voor parent de waarde system.admin_config en om de link onder de Appearance-sectie te plaatsen gebruik je de waarde system.themes_page.

Zolang je weet door welke module het bovenliggende onderdeel wordt gegenereerd, kun je simpel in de rootmap van de module het .links.menu.yml bestand inkijken. Als je alleen het pad kent van het bovenliggende onderdeel, zul je moeten gaan zoeken in de diverse .routing.yml bestanden op zoek naar de routing machine-name. Wanneer je die hebt gevonden kun je in de .links.menu.yml bestanden opzoeken welke menu-item machine-name erbij hoort en deze gebruiken in je parent entry.

In deel 2:
Links alteren, tabs en contextual links in Drupal 8