Creando mudulos de Drupal

Este tutorial est orientado a programadores que conocen PHP, que han empezado a
utilizar Drupal 7 a nivel de instalacin e interfaz de administracin, y que desean
aprender a programar sus propios mdulos. He querido empezar por el clsico Hola
Mundo para hacer el ejemplo lo ms sencillo posible conceptualmente, pero al mismo
tiempo extenderlo con variantes que permitan hacerse una idea de cmo funciona
Drupal y las posibilidades que nos ofrece.
A travs de este tutorial podrs aprender a:

Crear tu primer mdulo

Crear una pgina para decir hola mundo

Theming: maquetar el resultado con HTML

Programar un bloque que diga Hola Mundo

Hacer el saludo configurable desde la interfaz de administracin

Saludar por su nombre al usuario que inicia sesin

Hacer configurable en la interfaz qu eventos mostrarn el saludo

Traducir cadenas de texto con Drupal: t(Hello World)

Creando tu primer mdulo

Por supuesto podramos crear el Hola Mundo en un bloque o una pgina directamente
desde la interfaz, o incluso introducir un <?php echo Hola Mundo; ?> en una plantilla
del tema, pero se trata de aprender a programar funcionalidades y en Drupal esto se hace
desarrollando mdulos.
Los mdulos se suelen ubicar dentro del directorio /sites/all/modules. All creamos una
carpeta para nuestro mdulo que podemos llamar saludar. Para terminar de crear
nuestro mdulo necesitamos crear dentro el archivo saludar.info y el archivo
saludar.module. El primero es un archivo de texto que contendr la informacin de
definicin del archivo, y en el segundo empezaremos a programar con PHP.
saludar/saludar.info
name = Saludar
description = "Mdulo que dice hola mundo"
package = Aprendiendo a programar con Drupal
core = 7.x

En saludar.info estamos diciendo que el mdulo se llama Saludar, describimos lo que

hace, lo clasificamos en la categora Aprendiendo a programar con Drupal y
especificamos que es compatible con Drupal 7.
Para comprobar que hemos creado el mdulo correctamente nos vamos a la opcin
Mdulos del men de administracin de nuestra web Drupal, en la ruta
/admin/modules. All encontraremos nuestra categora con nuestro primer mdulo, y una
casilla para activarlo.

Crear una pgina para decir hola mundo

Para crear una pgina, es decir, programar la respuesta para una determinada url,
utilizaremos la funcin hook_menu(). Cuando nuestra aplicacin reciba la peticin de la
pgina /saludar/hola-mundo, Drupal comprobar si alguno de los mdulos tiene
programado un nombremodulo_menu() para esta direccin. Creamos pues nuestra
funcin saludar_menu() que servir de ndice para las direcciones a las que responder
nuestro mdulo saludar.
saludar/saludar.module
<?php
/**
* @file
* Archivo para empezar a programar con Drupal
*/
/**
* Implementa hook_menu().
*/
function saludar_menu() {
$items['saludar/hola-mundo'] = array(
'title' => 'Saludar',
'page callback' => 'saludar_hola_mundo',
'access callback' => TRUE,
);
return $items;
}
/**
* Callback que implementa la pgina: saludar/hola-mundo.
*/
function saludar_hola_mundo() {
return "Hola Mundo";
}

Lo que hemos hecho es aadir una url al array de elementos $items, y para esa direccin
elegimos un ttulo para la pgina y la funcin que implementa el contenido, que a su vez
devuelve como contenido un Hola Mundo. Con 'access callback' definimos con qu
permisos pueden acceder a esta pgina, en este caso podrn todos los usuarios (TRUE).
Cada vez que implementamos un cambio en hook_menu() necesitamos vaciar la cach
para poder visualizar estas modificaciones. En el men de administracin pulsamos en
Configuracin, y a continuacin en Rendimiento (en el bloque de Desarrollo), donde
podremos pulsar el botn Vaciar todas las cachs. Ahora s, podemos ver nuestro
primer Hola Mundo en la direccin /saludar/hola-mundo de nuestro sitio web.

Como puedes ver, adems de la pgina se ha creado un enlace en el men de

Navegacin. Esto es porque hemos obviado una de las opciones del array $items en el
hook_menu(): 'type', cuyo valor por defecto es la constante MENU_NORMAL_ITEM.
Si quisiramos crear la pgina sin que aparezca el men simplemente aadiramos en el
array:
'type' => MENU_CALLBACK,

Recuerda vaciar las cachs para ver los cambios!

Theming: maquetar el resultado con HTML

Hemos creado una pgina con el ttulo Saludar y hemos mostrado en su interior el texto
Hola Mundo. Como podis comprobar el contenido de nuestra pgina se muestra
dentro de un <div class=content>. Podramos formatear un poco el resultado con
HTML directamente en la funcin:
function saludar_hola_mundo() {
return '<p class="saludo"><em>Hola Mundo</em></p>';
}

Pero estaramos mezclando contenido y presentacin, as que vamos a ir un poco ms

all para separarlo, maquetando el Hola Mundo con HTML en un archivo de plantilla
aparte. Para ello devolvemos el resultado de la funcin theme():
function saludar_hola_mundo() {
$variables = array(
'message' => 'Hola Mundo',
);
return theme('saludar_hola_mundo', $variables);
}

Ahora estamos introduciendo Hola Mundo en el array de variables que le vamos a

pasar a la plantilla, y a continuacin utilizamos la funcin theme() para generar el
resultado de salida. Para ello la funcin theme() invoca el hook_theme(), utilizando el
primer parmetro 'saludar_hola_mundo' como nombre del hook.
Por tanto el siguiente paso es implementar el hook_theme() para nuestro mdulo en
saludar.module, indicando la plantilla que formatear la salida de 'saludar_hola_mundo'.
Al igual que con hook_menu(), la funcin que implementa el hook_theme() en el
mdulo se denomina nombremodulo_theme():
/**
* Implementa hook_theme().
*/
function saludar_theme() {
return array(
'saludar_hola_mundo' => array(
'template' => 'saludar-hola-mundo',
),
);
}

En nuestro hook_theme() estamos llamando a la plantilla (template): saludar-holamundo, para maquetar el callback: saludar_hola_mundo. Ahora solo falta crear la
plantilla en nuestro mdulo, creando un archivo con el nombre del template acabado en
.tpl.php.
saludar/saludar-hola-mundo.tpl.php
<p class="saludo"><em><?php echo $message; ?></em></p>

Vaciamos las cachs para que coja el nuevo archivo y podemos comprobar el resultado.
Como puedes ver estamos utilizando la variable message que definimos en la funcin
saludar_hola_mundo(). A partir de aqu puedes aadir nuevas variables de contenido
(por ejemplo la fecha) y modificar la plantilla para maquetar ese contenido con esas
variables.

Al utilizar theme() estamos separando la presentacin de la funcionalidad y el

contenido, y permitiendo que esa presentacin sea fcilmente sobreescrita en un tema.
Por ejemplo un maquetador o drupal themer podra simplemente copiar el archivo
saludar-hola-mundo.tpl.php del mdulo en el tema y modificarlo, sobreescribiendo as
el marcado HTML por defecto definido en nuestro mdulo.

Programar un bloque que diga Hola Mundo

Hemos aprendido a crear nuestra primera pgina desde un mdulo, con contenido
maquetado. Ahora vamos a aprender a construir un bloque para poder colocar nuestro
Hola Mundo en la regin de la pgina o pginas donde queramos ubicarlo. Para crear
el bloque tenemos primero que implementar en saludar.module el hook_block_info(),
que define todos los bloques que nuestro mdulo va a proveer:
/**
* Implementa hook_block_info().
*/
function saludar_block_info() {
$blocks['hola_mundo'] = array(
'info' => 'Bloque para Hola Mundo',
);
return $blocks;
}

En el array $blocks definimos todos los bloques de nuestro mdulo y proporcionamos

las opciones por defecto de cada bloque. Aqu hemos definido solamente info, pero

podramos haber definido si por defecto aparece activado o no, en qu regin, con qu
peso, etc. Estas opciones las puede configurar el administrador del sitio web drupal
desde la pantalla de Bloques en el men Estructura (/admin/structure/block). All vemos
nuestro bloque, en la seccin Desactivado.

Podemos colocarlo en una regin, por ejemplo en la barra lateral, pero an no podemos
verlo porque nos falta un paso, construir el bloque con el contenido, mediante
hook_block_view():
/**
* Implementa hook_block_view().
*/
function saludar_block_view($delta = '') {
switch ($delta) {
case 'hola_mundo':
$block['content'] = saludar_hola_mundo();
return $block;
}
}

En esta funcin definimos lo que se ve en cada bloque que implementa nuestro mdulo.
La variable $delta es la que nos identifica el bloque, y para el caso 'hola_mundo'
establecemos su contenido. Nuevamente en lugar de establecer el contenido del bloque
directamente con Hola Mundo, estamos reutilizando la funcin saludar_hola_mundo()
que escribimos anteriormente para utilizar la plantilla saludar-hola-mundo.tpl.php a
travs de hook_theme().

Ahora s, si actualizamos cualquier pgina podemos ver el bloque en la barra lateral, con
el mensaje Hola Mundo, tal y como lo maquetamos en la plantilla. A este bloque no le
hemos asignado ningn ttulo, si quisiramos proporcionar uno por defecto bastara con
utilizar la variable $block['subject'] en el hook_block_view().

Hacer el saludo configurable desde la interfaz de

administracin
Drupal, adems de una plataforma para desarrollo de aplicaciones, es un potente CMS o
gestor de contenidos. Esto es as porque la mayora de los mdulos no solo extienden la
funcionalidad aportando algo nuevo, si no que tratan de poner en manos de los usuarios
administradores herramientas para configurar esa funcionalidad y gestionar su
contenido. Por tanto a la hora de desarrollar un mdulo para Drupal puede ser muy
importante programarlo para que sea configurable, y como vamos a ver a continuacin,
implementar el formulario de administracin de las opciones del mdulo es bastante
sencillo.
Vamos a crear una pgina donde configurar el saludo de nuestro mdulo, as el
administrador podr cambiar el texto del mensaje Hola mundo por cualquier otro
saludo. Primero Colocaremos el acceso a esta pgina en el men de Configuracin
dentro de la zona de Administracin, en la url /admin/config:

Aadimos un nuevo elemento en el array del hook_menu de nuestro mdulo, en

saludar.module:
$items['admin/config/content/saludar'] = array(
'title' => 'Saludar',
'description' => 'Configurar las opciones para el saludo.',
'page callback' => 'drupal_get_form',
'page arguments' => array('saludar_configuracion'),
'access arguments' => array('administer site configuration'),
'file' => 'saludar.admin.inc',
);

Al situar la pgina bajo la ruta admin/config/content/ estamos ubicndola en ese

men, de ttulo Auditora del contenido, dentro de Administracin Configuracin.

En esta ocasin configuramos la opcin page callback para construir el formulario

con la funcin drupal_get_form(), page arguments para establecer el id del formulario
(saludar_configuracion) que le pasamos a drupal_get_form(), y access arguments
para que slo puedan acceder a la pgina de configuracin de nuestro mdulo aquellos
usuarios cuyo rol tenga asignado el permiso administer site configuration, traducido
en la pgina de permisos como Administrar configuracin del sitio.
Por ltimo hemos utilizado la opcin file para programar el formulario de
administracin en un archivo diferente. Por supuesto podramos omitirlo y seguir
programando todo en saludar.module, pero a medida que el mdulo empieza a crecer se
hace ms importante dividir la funcionalidad y dejar el .module con los hooks y
funciones ms generales, a modo de ndice del mdulo.
A continuacin creamos el archivo saludar.admin.inc en nuestro mdulo con tres
funciones, una para definir el formulario de configuracin, otra para validar dicho
formulario y otra para procesar el envo del formulario ya validado.
saludar/saludar.admin.inc
<?php
/**
* @file
* Callbacks de administracin del mdulo saludar.
*/
/**
* Define el formulario de opciones de configuracin.
*/
function saludar_configuracion() {
$form['saludar_saludo'] = array(
'#title' => 'Saludo que se muestra al usuario',
'#type' => 'textfield',
'#default_value' => variable_get('saludar_saludo', 'Hola Mundo'),
);
$form['submit'] = array(
'#type' => 'submit',
'#value' => 'Guardar configuracin',
);
$form['#submit'][] = 'saludar_configuracion_submit';
return $form;
}

/**
* Valida el formulario de opciones de configuracin.
*/
function saludar_configuracion_validate($form, &$form_state) {
if (trim($form_state['values']['saludar_saludo']) == '') {
form_set_error('saludar_saludo', 'El saludo no puede quedar
vaco.');
}
}
/**
* Procesa el envo del formulario de opciones de configuracin.
*/
function saludar_configuracion_submit($form, $form_state) {
variable_set('saludar_saludo', $form_state['values']
['saludar_saludo']);
drupal_set_message("Se han guardado las opciones de
configuracin.");
}

En saludar_configuracion() definimos los elementos del formulario en un array . En este

caso slo presentaremos un campo de texto textfield para establecer el Saludo que se
muestra al usuario. Puedes consultar la Drupal Form Api Reference para conocer todos
los elementos y sus propiedades.
Este saludo lo vamos a guardar en la base de datos con una variable que llamaremos
saludar_saludo (una vez ms utilizamos saludar_ como prefijo para evitar colisiones con
otros mdulos). Por eso definimos el valor por defecto del campo de texto mediante la
funcin de Drupal variable_get(), que mostrar el ltimo valor registrado por el
administrador, o la cadena 'Hola Mundo' si no se ha configurado el saludo an.
'#default_value' => variable_get('saludar_saludo', 'Hola Mundo'),

Por ltimo la funcin define el botn de submit y la funcin que procesar el envo, y
devuelve el formulario.

Como ejemplo de validacin comprobamos que no se haya enviado una cadena vaca,
accediendo al valor del campo que recibimos del array $form_state['values']. Si hay un
error invocamos la funcin form_set_error(), definiendo el campo donde se ha
producido y el mensaje de error correspondiente.

Finalmente en la funcin saludar_configuracion_submit() procesamos el envo validado

guardando el saludo en la base de datos mediante la funcin variable_set(), y emitimios
un mensaje de confirmacin mediante drupal_set_message().

Hemos visto que podemos controlar la validacin y el envo del formulario a travs de
estas dos funciones, pero para este ejemplo podramos hacerlo mucho ms sencillo y
ninguna de las dos seran necesarias. Por un lado la validacin de campo obligatorio se
puede implementar directamente con '#required' => TRUE. Por otro lado podemos
utilizar la funcin system_settings_form(), que aade el botn de submit, e invoca
internamente tras el envo a la funcin system_settings_form_submit(), que ya se
encarga de guardar el valor del campo en una variable con el mismo nombre que el
campo, en este caso "saludar_saludo". Simplificando el ejercicio, podramos dejar el
archivo saludar.admin.inc slo con esta funcin:
function saludar_configuracion() {
$form['saludar_saludo'] = array(
'#title' => 'Saludo que se muestra al usuario',
'#type' => 'textfield',
'#default_value' => variable_get('saludar_saludo', 'Hola Mundo'),

'#required' => TRUE,

);
return system_settings_form($form);
}

Ahora solo nos queda utilizar el valor de configuracin guardado para mostrarlo en el
saludo. Para hacer esto modificamos la funcin saludar_hola_mundo() del archivo
saludar.module, que quedar as:
function saludar_hola_mundo() {
$variables = array(
'message' => variable_get('saludar_saludo', 'Hola Mundo'),
);
return theme('saludar_hola_mundo', $variables);
}

Eso es todo, ahora nuestro Hola Mundo se ha convertido en un saludo configurable

que mostraremos en la pgina o bloque que hemos creado para ello. Los bloques
adems tienen una pgina de configuracin especfica en la que podramos haber
incluido el campo para configurar el saludo, de manera similar a cmo lo hemos hecho
en saludar.admin.inc, pero utilizando los hooks hook_block_configure() y
hook_block_save(). Te lo dejo como ejercicio de investigacin y prctica.

Saludando por su nombre al usuario que inicia sesin

Este ejercicio se puede hacer de manera muy sencilla, tan solo hay que responder al
hook de inicio de sesin que se llama hook_user_login(), en nuestro saludar.module:
/**
* Implementa hook_user_login().
*/
function saludar_user_login(&$edit, $account) {
drupal_set_message("Hola " . $account->name);
}

Ya sabemos como escribir un saludo en una pgina y en un bloque, ahora lo hacemos en

un sitio nuevo. Estamos haciendo uso de la funcin drupal_set_message(), para escribir
un mensaje de estado o confirmacin, que tambin podra ser de advertencia o error,
estableciendo un segundo parmetro.

El hook_user_login() nos proporciona el evento al que reaccionar y tambin el propio

objeto usuario: $account, donde la propiedad name nos da su nombre. Pero... y si
quisiramos saludarle tambin en otras ocasiones? Obviamente podemos programar el
saludo o cualquier otra accin en cada hook de cada evento que deseemos, pero de
nuevo vamos aprovechar la potencia de Drupal para dejar que sea el administrador y no
el programador el que pueda cambiar y decidir en qu momento ejecutar esa accin.

Hacer configurable en la interfaz qu eventos

mostrarn el saludo
Drupal dispone de un mdulo del ncleo, Trigger, que permite desde la interfaz de
administracin activar ciertas acciones en determinados eventos del sistema, como
cuando un usuario inicia sesin o cuando se crea contenido. Necesitamos activar este
mdulo porque vamos a crear una accin de saludar para que el administrador pueda
decidir qu eventos van a accionar (trigger) el saludo, en el men de administracin
Estructura Disparadores (admin/structure/trigger).
Primero creamos la accin de saludar utilizando hook_action_info() en nuestro
saludar.module:
/**
* Implementa hook_action_info().
*/
function saludar_action_info() {
return array(
'saludar_usuario_action' => array(
'type' => 'user',
'label' => 'Saludar al usuario',
'configurable' => FALSE,
'triggers' => array('any'),
),
);
}

Cada elemento en el array que devuelve este hook define una accin, en este caso
'saludar_usuario_action', que clasificamos de tipo usuario, su etiqueta ser Saludar al
usuario, en principio no ser configurable y estar disponible para cualquier disparador
(se puede limitar qu disparadores tendrn la accin disponible). Con esta funcin
implementada ya podemos seleccionar en la interfaz a qu disparadores queremos
asignar esta accin, por ejemplo tras iniciar sesin.

Lo siguiente es eliminar la funcin saludar_user_login() que implementamos en el

apartado anterior, y sustituir ese hook por la accin genrica que accionarn los
disparadores asignados en la interfaz.
/**
* Accin de drupal que saluda al usuario.
*/
function saludar_usuario_action() {
$message = "Bienvenido!";
if (user_is_logged_in()) {

$message = "Hola " . $GLOBALS['user']->name;

}
drupal_set_message($message);
}

En la accin estamos teniendo en cuenta si el usuario es annimo o est autenticado,

saludndole por su nombre en ese caso. Para ello hacemos uso de la variable global
user, que contiene el objeto usuario actual, y su propiedad name solo disponible si
el objeto es un usuario autenticado.
Otra opcin es utilizar la funcin format_username(), que directamente nos da el
nombre del usuario o bien el nombre usado en el sitio para indicar usuarios annimos,
generalmente Annimo (se define en Configuracin Personas Opciones de la
cuenta). Como ves la API de Drupal ya cuenta con muchas funciones de utilidad
implementadas que conviene conocer.
function saludar_usuario_action() {
drupal_set_message("Hola " . format_username($GLOBALS['user']));
}

Ahora puedes comprobar que el saludo se muestra correctamente para los distintos
eventos que configures en la pgina de Disparadores, y de paso ir conocindolos y ver
cundo se ejecutan.

Traducir cadenas de texto con Drupal: t(Hello

World)
La funcin t() sirve para poder traducir la cadena en los distintos idiomas que pudiera
tener la web. El idioma por defecto es el ingls y es en este idioma como deberemos
crear las cadenas de texto al programar. Por tanto en los ejemplos anteriores deberamos
sustituir la cadena Hola Mundo por la expresin t(Hello World), y as con todas las
expresiones de texto por su equivalente en ingls bajo la funcin t(). De esta manera se
podrn traducir desde la interfaz estas cadenas a cualquier idioma.

Por supuesto las cadenas que contienen variables, como en el ltimo ejemplo del saludo
al usuario, tambin se pueden traducir. En la cadena de texto utilizamos variables con el
smbolo @ delante, y definimos estas variables en un array como segundo parmetro de
la funcin t().
$message = t("Hola @name", array('@name' => $GLOBALS['user']>name));

Aunque se pueda traducir desde la interfaz, podramos proporcionar con nuestro mdulo
sus cadenas de texto ya traducidas. Para ello crearamos en el mdulo una carpeta
translations con un archivo general.pot que contendra todas las cadenas a traducir,
y un archivo .po para cada idioma con las cadenas traducidas, por ejemplo: es.po.
Existen herramientas para generar este tipo de archivos, y concretamente en Drupal
encontrars de gran utilidad el mdulo Translation template extractor, con el que podrs
fcilmente extraer estos archivos de traduccin para las cadenas de texto de un mdulo
especfico.
En estos primeros ejemplos he utilizado el espaol en el cdigo para facilitar la
comprensin. Pero Drupal est desarrollado por una comunidad internacional con el
ingls como idioma base. Por ello es una buena prctica escribir todo en ingls, tanto los
nombres de funciones y variables como los comentarios, lo que ayudar a que cualquier
otro desarrollador de Drupal pueda entenderlo. sta y muchas otras directrices
constituyen los estndares de programacin de Drupal, que conviene conocer y
acostumbrarse a seguir al desarrollar cdigo. De esta manera podras contribuir algn
da a la comunidad con tus propios mdulos no?
Espero que este tutorial te haya servido y animado a continuar este camino. Puedes
dejar aqu tus comentarios, cualquier duda, o sugerencia para mejorar el artculo. Os
dejo el enlace para descargar el cdigo del mdulo saludar.