Creación de módulos personalizados en drupal

En muchas ocasiones la mejor solución para ciertas necesidades es escribir un módulo personalizado; y más aún, cuando aquellas son demasiado específicas como para esperar que hayan sido tratadas o resueltas por módulos contribuídos.

Ahora bien, escribir módulos para Drupal es fácil, no se requiere de conocimientos profundos de programación; se requiere más bien: 1. saber pensar lógicamente, 2. saber traducir las necesidades en verbos y 3. Saber buscar y tener paciencia para encontrar los equivalentes en el lenguaje php y/o en el API de drupal para dichos verbos.

En estas notas intentaré ofrecer una guía simple para escribir módulos personalizados. Y, en sus ejemplos ofreceré soluciones para algunas de las inquietudes que he encontrado planteadas en el foro, y a las que no pude ofrecer ayuda significativa, bien por limitaciones de espacio, bien por pertinencia, o, también, porque en ese entonces no sabía suficiente para hacerlo.

Qué es un módulo

Un módulo es un conjunto de archivos de programa, imágenes, datos, hojas de estilo, etc., organizados en un directorio, cuyo propósito es realizar tareas ligadas con la solución de una necesidad o de un grupo de necesidades afines.

Estructura general de un módulo

Nombre de un módulo

Comenzaré por hacer una distinción formal que ahorrará dificultades: Todo módulo tiene dos nombres, que eventualmente pueden ser iguales, pero que deben ser considerados como diferentes: Un nombre amigable y un nombre técnico.

El nombre amigable
Es un nombre con sentido social y cuyo propósito es presentar al módulo ante la comunidad para que sea identificado y entendido por sus usuarios. Ej: "Mi primer módulo"
El nombre técnico
Esta dirigido a la máquina, es humanamente legible pero se orienta a ser entendido por "el motor de Drupal" y debe ser único en cada sitio en que sea instalado.
Debe ser escrito usando únicamente letras minúsculas (sin eñes ni tildes), números y guión bajo (raya al piso). Ej: "mi_primer_modulo"

Contenido de un módulo

Todo módulo debe tener como mínimo dos archivos (*.info y *.module) alojados en un mismo directorio y, los tres (directorio y archivos) deben tener en común el nombre técnico del módulo. ejemplo: Supongamos que acabamos de escribir e instalar un módulo. La estructura de archivos resultante se parecerá a la siguiente:

/directorio_del_sitio/sites/all/modules/
  • otro_modulo
  • . . .
  • mi_primer_modulo
    • mi_primer_modulo.info
    • mi_primer_modulo.module

El módulo, dependiendo de su complejidad podrá contener otros archivos y subdirectorios anidados, por ejemplo: archivo de instalación (.install que es opcional) hojas de estilo, temas por defecto, scripts etc., en este caso se tendrá algo como:

  • mi_primer_modulo
    • css
    • images
    • includes
    • js
    • mi_primer_modulo.info
    • mi_primer_modulo.install
    • mi_primer_modulo.module

Y, salvo los tres archivos señalados (info, module e install) el resto puede ser organizado al gusto del desarrollador del módulo; aunque conviene mantener presente que los nombres de archivo respeten la sintaxis de nombre técnico, puesto que un archivo es ofrecido al sistema para que sea abierto y "mostrado" por un controlador. Los nombres técnicos nunca deben contener caracteres especiales, pues pueden provocar fallos en algunos SO, entre los que el menor es no responder correctamente a los enlaces web. (Ilustro con un caso: hace algún tiempo un diseñador gráfico, de uno de mis equipos de trabajo, entregó un archivo cuyo nombre contenía una tilde. El archivo, por descuido, no fue renombrado y se subió con ese nombre a un servidor Linux. El directorio en que fue alojado quedó inservible por un buen tiempo y no pudo ser reparado con facilidad, fue imposible vía ftp y nos vimos obligados a pedir apoyo al servicio de alojamiento (hosting).)

El archivo de declaración de un módulo

El archivo "nombre_tecnico_del_modulo.info" es conocido como archivo de declaración del módulo. Y su propósito es "presentar" el módulo ante el motor de Drupal. Basta con que se escriba y ubique en la posición recomendada para que Drupal sepa de la existencia del módulo y pueda ofrecerlo en el menú de construcción del sitio para ser activado. En un sentido muy aproximado, copiar la carpeta (directorio) del módulo a uno de los directorios modules del sitio:

  • /directorio_del_sitio/modules/
  • /directorio_del_sitio/sites/all/modules/
  • /directorio_del_sitio/sites/default/modules/

equivale a instalar el módulo. No obstante, no equivale a activarlo. Drupal explora el árbol de directorios y registra automáticamente los módulos existentes en el mismo; y presume, que si están allí, es porque se quiso instalarlos: no se copia accidentalmente un directorio de módulo a un directorio modules de un sitio Drupal. Esta acotación es importante: Si no tiene intención de usar un módulo, no lo copie al directorio de módulos de su sitio. Si quiere probarlo, hágalo en un sitio de pruebas.

Contenido del archivo de declaración
El archivo de declaración .info, es un archivo de texto plano debe contener como mínimo los siguientes parámetros: nombre amigable, descripción y versión de drupal a la que está dirigido el módulo. No se necesita el nombre técnico pues este es ofrecido por el nombre del archivo. Se presentan así:

name
Nombre amigable. Se recomienda que sólo su primera letra sea mayúscula, y en caso de requerir tildes debe usar entities (entidades) html y ser escrito entre comillas. Si no usa entidades no requiere de las comillas.
description
Descripción breve del propósito del módulo (para qué sirve, qué hace.)
core
Familia de versiones de Drupal a la que está dirigido puede ser 6.x, 7.x, 8.x, etc. Establece restricciones de compatibilidad.
Ejemplos:
1. El archivo de declaración para "Mi primer ejercicio", mi_primer_ejercicio.info sería:
name= Mi primer ejerciciodescription= "Módulo de prueba escrito como ejercicio. No hace nada."core= 7.x
2. El archivo barrasdenavegacion.info usado para declarar un hipotético módulo "Barras de navegación" que es parte de un paquete llamado "Mis utilitarios" sería el siguiente.

name= "Barras de navegación"description= Juego de barras paginadoras para acceso progresivo a fuentes de datospackage= Mis utilitariosdependencies[]=origenes_de_datoscore= 6.x

En los dos ejemplos se pueden observar alguna diferencias sutiles: 1. el uso de comillas al parar los parámetros: Sólo se aplican cuando se usan entities (en ambos casos ó)
2. En el segundo caso se agregan dos parámetros opcionales: package y dependencies[] El primero indica que debe ser ofrecido como parte de un paquete (será presentado) en los menús de activación y control de módulos bajo el nombre del paquete. Y el segundo establece que depende de otro módulo, cuyo nombre técnico es "origenes_de_datos" y que no puede ser activado si dicho módulo no se encuentra instalado y activo.
Una observación importante: La descripción ocupa sólo una línea y puede ser larga. Aquí se rompió por cuestiones de formato del editor.

El archivo de programa principal de un módulo

El archivo "nombre_tecnico_del_modulo.module" es un archivo de programa escrito en lenguaje php típico, que ofrece las funciones y objetos necesarios para que el módulo sea operativo.
Tiene tres características fundamentales:

  1. Nunca usa la marca terminadora ?> típica de los archivos php. Pero si debe usar la inicial: <?php
  2. Implementa mediante puntos de enganche hook_ las funciones necesarias para que Drupal pueda activar y ejecutar sus servicios
  3. Puede incluir funciones y objetos adicionales para ser llamados y empleados mediante código php desde otros módulos o desde páginas, cuando el módulo php ha sido habilitado para ser usado como formato de entrada al escribir las páginas del sitio.

En la próxima sección de este manual se trataran en detalle los rudimentos para escribir un archivo de programa principal.

El archivo de instalación de un módulo

Al igual que el archivo de programa principal, se trata de un archivo de programa php sin cierre de etiqueta en la línea terminadora Su función es realizar tareas del tipo sólo una vez, necesarias para la correcta operación del módulo, presentar tareas de actualización, definir la estructura de base de datos requerida, crear e iniciar las tablas necesarias y eventualmente ofrecer mecanismos de desinstalación. En una sección posterior se tratará en detalle.

Próximo capítulo: Escritura del Archivo de programa principal de un módulo