![Drupal Route Controller](/sites/default/files/styles/blog_teaser/public/2024-05/drupal%20route%20controller_0.png?itok=7NluAFnb)
Requisitos:
Este tutorial está dirigido a aquellos que desean aprender sobre el desarrollo de módulos de Drupal desde cero. Se recomienda que, antes de leer este tutorial, tengas ciertos conocimientos sobre instalación, configuraciones y construcción de sitios con el CMS de Drupal.
Hay mucho que puedes encontrar en línea sobre configuraciones de CMS de Drupal. En esta guía, nos enfocaremos en la creación de módulos e implementación de nuevas funcionalidades en Drupal a través de la programación dentro de los módulos.
También es importante tener un entendimiento básico de programación y del lenguaje de programación PHP. Se recomienda conocer la sintaxis de PHP, los tipos de datos en PHP, el manejo de arrays y conceptos de programación orientada a objetos como clases, métodos, propiedades e herencia.
Antes de comenzar, asegúrate de tener un sitio de Drupal funcionando y configurado en tu máquina local o en un servidor. Necesitarás tener acceso para agregar y modificar archivos en esa instalación.
El código en este tutorial ha sido probado en la última versión disponible en ese momento, Drupal v10.1.
!Bienvenido!
En este emocionante tutorial, nos sumergiremos en el fascinante (y lleno de posibilidades) mundo del desarrollo de módulos de Drupal. Aprenderemos de manera fácil y práctica, utilizando un ejemplo clásico y divertido: la creación de un módulo para generar texto Lorem Ipsum.
Iremos paso a paso en la construcción de este módulo, comenzando desde lo básico, asegurándonos de tener todos los componentes necesarios para lograr una versión funcional. En el camino, veremos resultados tangibles que te ayudarán a entender cómo funcionan los módulos en Drupal de manera sencilla.
Así que prepárate para explorar y aprender de una manera práctica y divertida. ¡Sumerjámonos directamente en ello!
Modulo Lorem Ipsum
En términos simples, el módulo Lorem Ipsum combina palabras y frases al azar para crear texto de relleno para diversas necesidades. El texto aleatorio puede ser utilizado para completar contenido en un sitio web de prueba o con fines de diseño, etc.
Los usuarios pueden seleccionar cuántos párrafos y cuántas oraciones por párrafo desean, y generar automáticamente texto de relleno con estas características.
En este tutorial, crearemos el código responsable de la funcionalidad principal para generar texto Lorem Ipsum y mostrar los resultados en una página de Drupal.
Esto implica tres cosas:
- Crear un módulo personalizado llamado "loremipsum."
- Crear una ruta para mostrar los resultados. Por ejemplo: https://www.our_site.com/loremipsum/generate/5/10
La ruta recibirá parámetros en la URL como entrada para indicar cuántos párrafos y el máximo de oraciones por párrafo que queremos en el texto resultante. - Crear un controlador y ejecutar la visualización de resultados en la ruta.
Ahora veamos qué son estas cosas.
Puedes encontrar todo el código de este tutorial en GitHub en la siguiente dirección: https://github.com/x7ian/loremipsum_novice2expertutorial
Crear un module
Para crear un módulo, necesitas dos cosas:
- Una carpeta de módulo en el directorio web/modules/custom/<nombre del módulo> y
- un archivo <nombre del módulo>.info.yaml dentro de esa carpeta.
Reemplaza '<nombre del módulo>' con el nombre de tu módulo.
En este caso, creamos una carpeta <proyecto>/web/modules/custom/loremipsum y un archivo loremipsum.info.yml dentro de esta carpeta.
Los archivos .YML son archivos que contienen lenguaje YAML, un lenguaje de serialización de datos. Los archivos YML se utilizan en los módulos de Drupal para especificar información de configuración del módulo, y como verás pronto si continúas con esta serie de guías, también se utilizan ampliamente para declarar componentes de Drupal. Un ejemplo de un archivo de configuración es el archivo principal del módulo, el .info.yml.
loremipsum.info.yml contents:
name: Lorem ipsumtype: module
description: 'Generador Lorem ipsum para Drupal'
package: Custom
core_version_requirement: ^8 || ^9 || ^10
Estamos declarando un módulo llamado Lorem Ipsum.
- Le asignamos una descripción de lo que hace,
- le indicamos que pertenece al paquete Personalizado, aunque podríamos haber utilizado otro o creado un paquete diferente. Esto sirve para agrupar módulos.
- Finalmente, declaramos compatibilidad con las versiones 8, 9 y 10 de Drupal.
La estructura hasta ahora es la siguiente:
Ahora podemos ir al menu de administracion de drupal en nuestro sitio, en Administration > Modules (/admin/modules).
Asegúrate de activar el módulo Custon Lorem Ipsum y presiona Instalar.
El módulo se activará, pero este módulo aún no hace nada.
Creando una Ruta
Una ruta es una dirección o URL reservada en nuestro sitio, utilizada para mostrar o ejecutar algo que necesitamos. En otras palabras, es como agregar una nueva página o una nueva dirección a Drupal para que cuando alguien acceda a esa dirección, Drupal ejecute un código y muestre algo que hemos programado.
Para definir rutas, utilizamos el archivo .routing.yml, por lo que agregaremos el siguiente contenido al archivo loremipsum.routing.yml:
loremipsum.generate:
path: '/loremipsum/generate/{paragraphs}/{phrases}'
defaults:
_controller: '\Drupal\loremipsum\Controller\LoremIpsumController::generate'
requirements:
_permission: 'generate lorem ipsum'
In this file, we define a route which we call 'loremipsum.generate', to which we are assigning the following parameters:
- 'path': The route receives two parameters defined within brackets {paragraphs}/{phrases}. These are values that will be replaced in the route by the values of these parameters. In this case, {paragraphs} refers to the number of paragraphs we want to generate, and {phrases} to the maximum number of phrases per paragraph.
- 'defaults: _controller': We specify that when someone accesses the specified route, the code inside the generate() function within the '\Drupal\loremipsum\Controller\LoremIpsumController' class should be executed. This function is called the controller.
- 'requirements: _permission': Here, access permissions to the route are specified to restrict access to user roles.
For now, we'll leave a fairly generic permission, - 'access content', which practically allows access to all users. It's always recommended to set restrictions as a security measure. Later on, in future guides, we'll delve deeper into this topic.
Agregar un controlador
Solo necesitamos crear el controlador, la función que devuelve los resultados que se mostrarán en la ruta.
Como ya lo hemos definido en el archivo routing.yml, el controlador estará ubicado en la clase \Drupal\loremipsum\Controller\LoremIpsumController. Lo que parece ser una ruta con barras invertidas (\) es una notación especial en PHP. Drupal utiliza el estándar PSR-4 (Recomendación Estándar de PHP) para localizar los archivos de clase en la carpeta src. Según PSR-4, esta clase debería encontrarse en el archivo físico src/Controller/LoremIpsumController.php, y el controlador será específicamente la función generate() de la clase LoremIpsumController.
Para obtener más información sobre los Espacios de Nombres y el estándar PSR-4, puedes leer un artículo aquí.
El archivo del controlador tendrá el siguiente contenido:
/src/Controller/LoremIpsumController.php
<?php
namespace Drupal\loremipsum\Controller;
use Drupal\Component\Utility\Html;
/**
* Controller routines for Lorem ipsum pages.
*/
class LoremIpsumController {
/**
* Constructs Lorem ipsum text with arguments.
* This callback is mapped to the path
* 'loremipsum/generate/{paragraphs}/{phrases}'.
*
* @param string $paragraphs
* Numero de parrafos a generar.
* @param string $phrases
* Maximo numero de frases que se pueden generar en un parrafo.
*/
public function generate($paragraphs, $phrases) {
// Usar este texto como origen de las frases.
$page_title = 'Lorem ipsum';
$source_text = "Lorem ipsum dolor sit amet, consectetur adipisci elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. \nUt enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. \nDuis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. \nExcepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.";
$repertory = explode(PHP_EOL, $source_text);
$text = '';
// Generar $paragraphs parrafos con hasta $phrases frases cada uno..
for ($i = 1; $i <= $paragraphs; $i++) {
$this_paragraph = '';
// El número de frases sera un número random entre 1 y $phrases..
$random_phrases = mt_rand(1, $phrases);
$last_number = 0;
$next_number = 0;
for ($j = 1; $j <= $random_phrases; $j++) {
// Evitaremos las frases repetidas dos veces seguidas.
do {
$next_number = floor(mt_rand(0, count($repertory) - 1));
} while ($next_number === $last_number && count($repertory) > 1);
// $this_paragraph acumula un parrafo con las frases generadas.
$this_paragraph .= $repertory[$next_number] . ' ';
$last_number = $next_number;
}
// $text acumula todos los parrafos generados.
// Cada parrafo dentro de una etiqueda ‘<p>’
$text .= '<p>' . Html::escape($this_paragraph) . '</p>';
}
// Finalmente el resultado es enviado en un un elemento ‘markup’ de array renderizable.
$element = [
'#type' => 'markup',
'#markup' => '<h3>' . Html::escape($page_title) . '</h3>' . $text,
];
return $element;
}
}
Aquí se crea la clase LoremIpsumController. Dentro de la clase, hay un método generate(), que es la función que definimos como el controlador para la ruta loremipsum.generate, _controller: '\Drupal\loremipsum\Controller\LoremIpsumController::generate'.
En los comentarios del código anterior, hay una explicación de lo que hace el código personalizado para generar el texto Lorem Ipsum.
También ten en cuenta que:
- La función generate($paragraphs, $phrases) recibe dos parámetros. Estos corresponden a los dos parámetros de ruta definidos anteriormente, {paragraphs}/{phrases}.
Los valores encontrados en esas posiciones en la ruta se recibirán automáticamente en las variables $paragraphs, $phrases. - La función generate() devuelve el contenido que queremos mostrar en la página de la ruta. Este contenido debe estar en forma de un Render Array.
Los render arrays son arrays asociativos en PHP que contienen una estructura definida por las reglas de una API de Render Arrays.
Más adelante en esta serie de guías, hablaremos más sobre los render arrays.
En nuestro código, el texto Lorem Ipsum generado se almacena en la variable $text. Este valor luego se inserta en un elemento de marcado en un array renderizable, que es devuelto por la función.
Resumen Gráfico
Visualizando gráficamente lo que entra en el módulo Lorem Ipsum, imaginemos lo siguiente.
Vemos que el módulo personalizado está representado por el recuadro rosa. Dentro de nuestro módulo, hemos creado dos cosas: una ruta llamada "loremipsum.generate" que recibirá solicitudes del navegador de un visitante y ejecutará el código definido en un controlador, LoremIpsumController.
El controlador produce un arreglo de renderizado que contiene el texto Lorem Ipsum generado. Esto es procesado por Drupal para generar la respuesta y enviarla al navegador que realizó la solicitud.
Esta es la estructura de lo que se incorpora hasta ahora en el módulo loremipsum.
Módulo loremipsum v0.1
Una vez que se agrega el controlador, necesitamos Limpiar la caché para que Drupal reconozca la nueva ruta y registre su controlador.
Ahora vayamos al navegador, vayamos a
http://<our site>/loremipsum/generate/5/10
Deberíamos ver texto Lorem Ipsum con 5 párrafos, cada uno conteniendo de 1 a 10 frases aleatorias.
Puedes verlo en acción justo aquí: https://blog.cgalicia.space/loremipsum/generate/5/10
¡Felicidades! Has creado un módulo que añade funcionalidad a Drupal y espero que hayas aprendido algunas cosas sobre cómo empezar a crear con módulos de Drupal.
En las próximas guías, continuaremos añadiendo nuevas características y mejorando nuestro módulo mientras aprendemos nuevos conceptos de programación de módulos en Drupal.
Enlaces:
Puedes encontrar todo el código de este tutorial en GitHub en la siguiente dirección: https://github.com/x7ian/loremipsum_novice2expertutorial
PSR-4 y espacios de nombres en Drupal:
https://www.drupal.org/docs/develop/standards/php/psr-4-namespaces-and-…
Guía oficial de Render Arrays de Drupal.org:
https://www.drupal.org/docs/drupal-apis/render-api/render-arrays
Ejemplo de Rutas y Controladores en Drupal.org:
https://www.drupal.org/docs/drupal-apis/routing-system/introductory-dru…