Cuando estamos implementando un módulo personalizado de Drupal tenemos que lidiar con algunos ficheros en formato YAML. Estos tienen ciertos cometidos bastantes confusos para los newbies, así que voy a poner un poco de orden y aclaración. Los ficheros son:

• mimodulo.routing.yml
  • Define las URL y controladores que van a gestionar una página*.
• mimodulo.links.menu.yml
  • Inserta en las barra de menús accesos a funciones de nuestro módulo, páginas externas, …
• mimodulo.links.task.yml
  • Inserta en las pestañas (tabs) accesos a funciones de nuestro módulo.
• mimodulo.links.action.yml
  • Inserta botones con acceso a las funciones de nuestro módulo.
• mibloque.links.contextual.yml
  • Crea menú contextuales en los bloques.

Arriba hemos visto cómo deben llamarse los ficheros. Ojo, la parte, en cursiva, donde dice mimódulo debe sustituirse por el nombre del módulo que estás implementando. Todos los ficheros deben ubicarse en la raíz del módulo. Por poner un ejemplo:

/modules/custom/mimodulo/mimodulo.routing.yml

PD: Módulo lleva tilde, pero por motivos informáticos obvios se omite.

Routing

El nombre del fichero es mimodulo.routing.yml

Aquí se registran las ubicaciones de todos los controladores vinculados a cada una de las acciones del módulo. Es esencial para el resto de ficheros que veremos, a continuación, ya que todos ellos hacen referencia a las rutas aquí establecidas*. Veamos un contenido tipo:

mimodulo.list:
  path: 'listado'
  defaults:
    _controller: '\Drupal\mimodulo\Controller\ListadoController::display'
    _title: 'Listado de contenido'
  requirements:
    _access: 'TRUE'

mimodulo.contenido.add:
  path: 'add'
  defaults:
    _form: '\Drupal\mimodulo\Form\AddForm'
    _title: 'Añadir contenido'
  requirements:
    _permission: 'access content'

mimodulo.settings:
  path: 'configuracion'
  defaults:
    _controller: '\Drupal\mimodulo\Controller\ConfiguracionController::display'
    _title: 'Configuración del módulo'
  requirements:
    _permission: 'access content'

Donde:

1. Es el identificador utilizado para cada ruta. Este es el que se usará en el resto de ficheros en las entradas tipo route_name. Aquí existen tres entradas: mimodulo.list, mimodulo.contenido.add y mimodulo.settings. El nombre no tiene porqué ser así, pero por buena práctica se estructura de esa manera.
2. Path define la ruta que se vinculará a la URL. Para la primera entrada será algo así: http://miweb/listado
3. Default varía en base a qué se está dirigiendo: una entidad, un formulario, un controlador, etc. En este ejemplo hemos puesto un controlador y un formulario. Luego comentaré porqué no he puesto una entidad.
4. _controller, apunta al método del controlador que va a gestionar esta acción; _form, apunta al formulario. Si apuntáramos a una entidad, pondríamos _entity.
5. _tile es para el texto que aparecerá en la cabecera de la cabecera de la página y de la ventana del navegador
6. requirements, establece los permisos que se deberán tener para poder acceder.

Todo esto es un tema muy extenso. Ya veré si hago un artículo más detallado de todo esto, pero añado un link con la documentación oficial donde lo explica.

En el resto de ejemplos pondré capturas del resultado final, pero aquí no se puede porque esto no tiene una respuesta directa sobre la interfaz de usuario (UI).

*Este fichero ha generado un poco de dudas en mí, ya que en Drupal 9 se puede hacer esto con anotaciones, o eso pensaba yo con los «links» de las anotaciones. La duda que me surgió fue, ¿uso uno u otro? La respuesta es, después de leer bastante al respecto, ambas. Las dos opciones son complementarias y/o necesarias, pero no exclusivas.

Mi recomendación es utilizar todo lo referente a las entidades en las anotaciones de la propia entidad. Aunque si necesitas crear una entrada de menú, pestaña, botón o menú contextual tendrás que tirar del fichero en YAML (mimodulo.routing.yml).

Si no me crees, aquí tienes un extracto de la documentación oficial:

Creating these links does not automatically create the routes for those URIs. To make these links accessible, your module will need to implement its own routing.yml file, or use a «route_provider» handler in the entity annotation.

https://www.drupal.org/docs/drupal-apis/entity-api/introduction-to-entity-api-in-drupal-8

Links.Menu

El nombre del fichero es mimodulo.links.menu.yml

En Drupal 7 esto tenía que ser implementado en el hook_menu, pero desde la versión 8 esto ya no es así y se ha separado. Ahora se implementa todo en este fichero. El contenido tipo es este:

mimodulo.settings:
  title: 'Configuración MiMódulo'
  description: 'Configuración de mi módulo personalizado'
  route_name: mimodulo.settings
  parent: system.admin_structure

Dónde:

1. Es la clave o identificador utilizado para referenciar el elemento. Para una buena práctica se aconseja que sea similar al route_name.
2. Título que aparecerá en el menú
3. Descripción que aparecerá en la parte inferior. Debajo del título del menú.
4. Identificador de la ruta. Esta se define en el fichero mimodulo.routing.yml
5. Contexto que alberga el menú donde se va a insertar el nuestro. En este ejemplo: /admin/structure

La apariencia final vendrá a ser como la siguiente:

Más información aquí.

Links.Task

El nombre del fichero es mimodulo.links.task.yml

En esta ocasión lo que definimos aquí son las pestañas. Nos podría interesar añadirlas en la sección de contenido del lado de administración o en la ficha de edición del propio nodo. Haremos lo primero, ya que es lo menos frecuente que se ven en los ejemplos que suelen verse en Internet. Este sería el código:

mimodulo.list:
  title: 'Mi Contenido'
  route_name: mimodulo.list
  base_route: system.admin_content
  weight: 15

Dónde:

1. Es la referencia o clave al elemento. Por buena práctica se recomienda que sea similar a route_name
2. Título que aparecerá en la pestaña
3. Identificador de la ruta. Esta se define en el fichero mimodulo.routing.yml
4. base_route es el contenedor donde ubicará la pestaña. En este ejemplo es /admin/content
5. Weight es el peso, que como sabrás a estas alturas, define la posición de un elemento en una lista. Mientras mayor sea su valor, más alejado estará del inicio (0). En este caso he puesto 15, pero podría ser, 4.

Este es el resultado final del código anterior:

Más información aquí.

Links.Action

El nombre del fichero es mimodulo.links.action.yml

En este fichero se definen botones vinculados a acciones de nuestro módulo. Nos podría interesar añadirlas en la sección de contenido del lado de administración o en la ficha de edición del propio nodo. Haremos lo primero, ya que es lo menos frecuente que se ven en los ejemplos que suelen verse en Internet. Este sería el código:

mimodulo.contenido.add:
  title: 'Añadir nuevo contenido'
  route_name: mimodulo.contenido.add
  appears_on:
    - entity.menu.collection

Donde:

1. Es la referencia o clave al elemento. Por buena práctica se recomienda que sea similar a route_name
2. Título que tendrá el botón
3. Identificador de la ruta. Esta se define en el fichero mimodulo.routing.yml
4. Indica en qué contextos aparecerá el botón. En este ejemplo se ha puesto en el de la getión de los menús.

Este es el resultado final del código anterior:

Más información aquí.

Links.Contextual

El nombre del fichero es mibloque.links.contextual.yml

Esta parte no la he podido investigar mucho, pero lo poco que he recabado es lo siguiente. Sirve para crear menús contextuales en los bloques. Por eso he enfatizado que solo se aplica a los módulos de tipo bloque. Este es un código de ejemplo:

block_configure:
  title: 'Configure block'
  route_name: 'block.admin_edit'
  group: 'block'

Donde:

1. Es la referencia o clave al elemento. Por buena práctica se recomienda que sea similar a route_name
2. Título que aparecerá en el item del menú.
3. Identificador de la ruta. Esta se define en el fichero mimodulo.routing.yml
4. Clave para agrupar los elementos del menú. Similar a la funcionalidad de base_route de las pestañas (tasks).

Este es el resultado final:

Más información aquí.