Creación de módulos para Drupal 8

Aunque es posible construir sitios Drupal 8 relativamente complejos sin tener que mirar nunca los componentes internos de un módulo, puede haber casos en los que necesitarás comprender el funcionamiento interno de algún módulo para aprovechar al máximo el módulo. En este capítulo haremos un recorrido de alto nivel de lo que constituye un módulo en Drupal 8, caminando a través de la creación de un sencillo módulo Drupal 8.

1. Tu primer módulo Drupal 8

¡No te preocupes, lo mantendremos sencillo! Nuestro módulo de ejemplo hace sólo una cosa, pero lo hace muy bien: mostrar el texto “Hello Drupal 8 World!” en una página. El resultado de nuestros esfuerzos en esta sección será una página similar a la figura 12-1.

Figura 12-1.

Paso 1: Crear el directorio del módulo

El primer paso es crear un directorio donde residan los archivos que constituyen tu módulo. Todos los módulos aportados (no-núcleo) residen en el directorio de módulos ubicado en el directorio raíz de tu sitio Drupal. Si has instalado cualquier módulo más allá de lo que viene con Drupal 8, verás esos módulos en este directorio.

Utilizando el administrador de archivos del sistema operativo o desde una ventana de terminal y un símbolo del sistema, navega al directorio de módulos de tu sitio y crea un nuevo directorio llamado custom. Las mejores prácticas de Drupal indican que los módulos custom, los que no se descargan de Drupal.org, deben almacenarse en un subdirectorio llamado custom. Navega hasta el directorio custom y dentro de la carpeta crea un nuevo directorio llamado hello.

Paso 2: Crear el archivo de información del módulo

El siguiente paso es crear un archivo hello.info.yml. Este archivo informa a Drupal sobre tu módulo y proporciona la información que aparece en la página Extend en la sección Administración de tu sitio.

Utilizando tu editor de texto favorito, crea el archivo hello.info.yml con el siguiente contenido:

name: Hello type: module description: ‘Mi primer módulo Drupal 8.’ package: Awesome modules version: 1.0 core: ‘8.x’

La primera línea especifica el nombre del módulo tal como aparece en la página del módulo. La segunda línea especifica que estamos creando un módulo (Themes, por ejemplo, utilizaría un valor de tema para el tipo). La tercera línea captura la descripción del módulo, que también aparece en la página Extend. El campo package proporciona un mecanismo para agrupar los módulos. Por ejemplo, si visitas la página Extend de tu sitio, verás una serie de módulos enumerados en un cuadro con un título núcleo. Utilizaremos algo único para nuestro módulo y lo colocaremos en un package llamado módulos Awesome. Si estás escribiendo un módulo que, por ejemplo, crea nuevas capacidades de servicios web, debes utilizar el nombre de paquete de los otros módulos que crean servicios web para asegurarte de que el administrador del sitio puede encontrar fácilmente tu módulo. La versión crea un número de versión para el módulo y el core especifica la versión de Drupal para la que se escribió este módulo. En nuestro caso escribimos este módulo para Drupal 8.

Paso 3: Crear el archivo de módulo

El archivo de módulo para nuestro módulo Hello hace una cosa: devuelve el texto que se mostrará en la página que nuestro módulo proporciona. Los archivos de módulo pueden hacer muchas cosas, pero para nuestro ejemplo nos centraremos en lo básico.

Utilizando tu editor de texto favorito, crea un nuevo archivo denominado hello.module con el siguiente texto:

<?php use Drupal\Core\Routing\RouteMatchInterface; function hello_hello_world() { return t(‘Hello Drupal 8 World!’); }

El archivo comienza con la etiqueta PHP de apertura, <?php, ya que todos los módulos están escritos en lenguaje PHP. Los elementos específicos de nuestro archivo de módulo son

function hello_hello_world() {

Esto define una función PHP que se puede llamar desde otros módulos. En este caso es una función simple llamada hello_hello_world(). El primer saludo es el nombre del módulo, en nuestro caso Hello. Como estándar de codificación Drupal, todas las funciones deben comenzar con el nombre del módulo, seguido de un nombre de función descriptivo.

Una vez más, nuestra función hace una cosa: devolver una cadena de texto al código que llamó a esta función. Hemos envuelto el texto que estamos retornando en una función de Drupal llamada t(). Esta función traduce cualquier texto entre paréntesis, si tienes activadas las funciones multilingües (ver capítulo sobre multilenguaje). Es otro estándar de codificación Drupal para ajustar todos los valores de texto usando la función t().

Aunque nuestro módulo es simple, demuestra la funcionalidad básica de lo que hacen los módulos. El archivo de módulo es el caballo de batalla de cualquier módulo, y puede ser tan simple como nuestro módulo de ejemplo o tan complejo como sea necesario para cumplir con los requisitos funcionales y técnicos de tu módulo.

Paso 4: Crear el archivo de enrutamiento del módulo

La base de Drupal 8 es Symfony, un framework PHP que simplifica la creación de complejas aplicaciones basadas en PHP, como Drupal. El framework Symfony proporciona los mecanismos para crear una aplicación basada en Model-View-Controller (MVC), donde Model representa los datos subyacentes con los que la aplicación opera, View define la interfaz de usuario para la aplicación y Controller es el caballo de batalla de las aplicaciones, incluyendo las solicitudes de enrutamiento de los usuarios y devolver la información a la vista para mostrar al usuario. El siguiente paso en el proceso es crear el archivo de enrutamiento de nuestro módulo, que define cómo un visitante tendrá acceso a la funcionalidad de nuestro módulo y qué devuelve los valores que se mostrarán.

En el mismo directorio, usando tu editor de texto favorito, crea el archivo de enrutamiento del módulo. En nuestro caso, el archivo de enrutamiento se llamará help.routing.yml. El contenido del archivo debe ser:

hello.content: path: ‘/hello’ defaults: _controller: ‘\Drupal\hello\Controller\HelloController::sayhello’ requirements: _permission: ‘TRUE’

La primera línea de código representa el nombre de nuestro módulo (hello). La siguiente línea representa la ruta que un usuario final usaría para acceder a la funcionalidad proporcionada por el módulo, que es /hello. La sección defaults proporciona el origen del contenido que se devolverá al usuario final, que es la función sayhello dentro del HelloController (más sobre esto en un momento). La sección de requisitos define qué permisos debe tener un visitante para acceder a nuestro módulo; en este caso sólo usamos la palabra TRUE, ya que cualquiera puede acceder a esta página. Consulta el módulo Examples para obtener más información sobre cómo los módulos pueden restringir el acceso (www.drupal.org/project/examples).

Paso 5: Crear el controlador del módulo

Drupal 8 sigue el enfoque de orientación a objetos de Symfony y PHP 5. Uno de los conceptos clave que Drupal 8 ha adoptado es un estándar llamado PSR-4, que define cómo se carga el código en la memoria. Uno de los problemas con las versiones anteriores de Drupal es que una gran cantidad de código se cargaba en la memoria cuando no era necesario estar allí.

PSR-4 resuelve ese problema, y uno de los habilitadores es algo llamado namespaces. En nuestro archivo de enrutamiento, el valor asociado con _content comienza con \Drupal\hello\Controller, que es un espacio de nombres. PSR-4 define que un espacio de nombres se asigna directamente a la estructura de archivos de la aplicación. Symfony requiere que todos nuestros directorios de espacio de nombres residan dentro de un directorio llamado src, que reside en el directorio raíz de nuestro módulo.

Así que ocupémonos y creemos los directorios donde residirá el siguiente componente de nuestro módulo, el controlador. En el directorio raíz de nuestro módulo hello, crea un nuevo directorio llamado src, y dentro del directorio src, crea un nuevo directorio llamado Controller. Dentro del directorio Controller, ahora estamos listos para crear el controlador para nuestra aplicación, el “traffic cop” de nuestra aplicación. En tu editor de texto favorito, crea un archivo llamado HelloController.php. El contenido de nuestro controlador debe ser:

<?php namespace Drupal\hello\Controller; use Drupal\Core\Controller\ControllerBase; class HelloController extends ControllerBase { public function sayhello() { return array( ‘#markup’ => hello_hello_world(), ); } }

El comienzo de nuestro archivo de controlador comienza con la etiqueta de apertura PHP, ya que el controlador se escribe en PHP. La segunda línea define el espacio de nombres que estamos utilizando para nuestro controlador:

namespace Drupal\hello\Controller;

La tercera línea define que vamos a heredar la clase ControllerBase del núcleo de Drupal sin tener que escribirlo todo desde cero:

use Drupal\Core\Controller\ControllerBase;

Recordemos del Paso 4 que en el archivo de enrutamiento de nuestro módulo llamamos una función que devuelve el contenido para mostrarlo usando ‘\Drupal\hello\Controller\HelloController::sayhello’. La clase HelloController es la primera parte del HelloController::sayhello:

class HelloController extends ControllerBase {

La siguiente línea es la última mitad de la llamada de nuestro enrutador (HelloController::sayhello). La línea de código define la función que devolverá la información a la página que se muestra cuando el visitante accede a la URL de /hello en nuestro sitio.

public function sayhello() {

El código restante simplemente llama a la función que creamos en nuestro archivo de módulo hello_hello_world(). Esta función devuelve el texto “Hello Drupal 8 World!” en una matriz renderizable que Drupal sabe mostrar en una página y la devuelve a nuestro enrutador de módulos.

return array( ‘#markup’ => hello_hello_world(), );

Guarda este archivo y estamos listos para activar nuestro nuevo módulo. Visita la página Extend en la sección de administración del sitio y desplázate hacia abajo hasta que veas la sección Awesome modules (ver figura 12-2).

Figura 12-2.

Marca la casilla junto al nombre del módulo y haz clic en el botón “Guardar configuración para habilitar el módulo.

Con el módulo habilitado, ya estás listo para probar tu primer módulo Drupal 8! Para ejecutar el módulo, navega a la página de inicio y agrega /hello al final de la URL (definimos esa ruta en el archivo de enrutamiento de nuestro módulo).

Deberías ver la salida mostrada anteriormente en la figura 12-1.

2. Otros archivos del módulo

Nuestro módulo Hello es un módulo muy sencillo, con el propósito de ayudarte a superar la curva de aprendizaje inicial de cómo se estructura un módulo en Drupal.

Ahora que conoces los fundamentos básicos, puedes consultar otros módulos aportados, o incluso el núcleo de Drupal, para ver cómo se crean módulos más complejos y estudiar los archivos asociados con esa mayor complejidad. Puedes aprender sobre la escritura de módulos más complejos en www.drupal.org/developing/modules/8. Te recomiendo que descargues el módulo Examples desde www.drupal.org/project/examples. Dentro de ese módulo encontrarás varios ejemplos que demuestran cómo se construyen los módulos Drupal 8, un gran punto de partida para crear módulos Drupal 8.