Los hooks de Drupal

A lo largo de los últimos meses he dedicado parte de mi tiempo a diseñar y desarrollar el módulo Mapstraction CCK para Drupal, dentro de esta actividad, he ido documentando los distintos hooks que he ido necesitando para poder llevar a buen puerto las distintas aplicaciones que he ido desarrollando.
Los Hooks son el mecanismo que provee Drupal para interactuar con los distintos procesos que se ejecutan en un sitio web.Conocer su funcionamiento es fundamental para cualquier programador de módulos así como también para aquellos diseñadores o Themers que deseen modificar aspectos al parecer imposibles de lograr.
En este momento, me ha parecido una buena idea compartir esta documentación que he ido recopilando para que cualquier desarrollador interesado pueda ver su labor facilitada dentro de lo posible. No están todos los hooks integrados dentro del API de Drupal, pero son parte de los más utilizados para poder llevar a cabo el desarrollo de cualquier módulo. Espero que os sea de ayuda, y si veis algíun fallo u os queda alguna duda, no dudéis en informarme. 

Hooks de Drupal documentados:

• Help
• Theme
• Elements
• Nodeapi
• Block

hook_help()

hook_help($path, $arg)

Proporciona ayuda online al usuario.

Implementando este hook, un módulo puede enviar documentación tanto al core como a otros módulos. Toda la ayuda al usuario debe ser retornada usando este hook.

Parámetros

•     $path:Se envía el path de la página de Drupal que se está pidiendo en ese momento, por ejemplo admin/node o user/edit. Si aparece un % en el path, también aparecerá. También reconoce descriptores especiales despues del símbolo #. Por ejemplo:
•    admin/help#modulename: El texto de ayuda del módulo, mostrado en la página admin/help y a través de la ayuda propia del módulo.
•     user/help#modulename: La ayudapara los usuarios de la página.
•     $arg: Un array que se corresaponde con el resultado de llamar a la función arg(). Si una página necesita mostrar la información específicamente para cada uno de los parámetros que pueden tomar estos argumentos.

Retorna

Una cadena que contenga el texto de ayuda.

hook_theme()

hook_theme($existing, $type, $theme, $path)

Registra en él las implementaciones de temas para un módulo (o tema). Estos temas definen la forma en la que se mostrarán los contenidos.

Parámetros

•    $existing: Un array con las implementaciones existentes que puede ser utilizado para sobreescribirlas.
•     $type: Indica que tipo está siendo procesado. Es útil para que los temas indiquen si es ese el tema usado, o su 'padre'. Puede tener estos valores:
•     'module': Un módulo está siendo inspeccionado para buscar las implementaciones de temas.
•     'base_theme_engine': Un motor de tema está buscando un tema que es padre del tema que está siendo usado actualmente.
•     'theme_engine': Un motor de tema está buscando el tema actual.
•     'base_theme': un tema básico estábuscando implementaciones de tema.
•     'theme': El tema actual en uso está siendo comprobado.
•     $theme: El nombre del tema actual usado.
•     $path: El path del tema o del módulo, así no es necesario buscarlo.

Retorna

Un array asociativo de hooks de temas. Estos son los posibles valores que se pueden indicar a llas claves de este array:

•     ‘arguments’: (obligatorio) Un array indicando los argumentos que utiliza este hook. Las claves de este array representan el nombre de la variable, y su valor sera utilizado por defecto si no se especifica su valor en el método theme().
•     ‘file’: El fichero en el que está definido el tema. Este fichero sera incluido antes de que el tema sea renderizado, para asegurarse de que las funciones de preprocesado están correctamente cargadas. Permite dividir el código de los temas en distintos ficheros de forma sencilla.
•     ‘path’: Sobrescribe el path del fichero a utilizar. Normalmente se utiliza el path del modulo, pero si no es así, se puede indicar otro. Este path debe ser realtivo al directorio root de Drupal.
•     ‘template’: Si se especifica, la implementación del tema es una plantilla, y en este parámentro se indica el nombre del fichero sin extensión. La extension que tundra este fichero sera tpl.php. Si se indica el element ‘path’, la plantilla debe estar en ese path.
•     ‘function’: Si se especifica, sera el nombre de la function que se invoque cuando se requiera el tema. Si no se especifica, se asumirá el nombre por defecto. Por ejemplo, si un modulo registra el tema ‘node’, 'theme_node' sera el valor por defecto de esta función.
•     ‘pattern’: Una patron de expression regular que se utilize para permitir la implementación del tema para tener un nombre dinámico. La convención indica usar __ para diferenciar la parte dinámica del tema. Por ejemplo, para permitir que cada foro sea mostrado de diferente manera, el patrón será ‘foro__’. Entonces cuando algún foro sea mostrado, se llamará a la función de elta manera: theme(array('foro__'. $tid, 'foro'), $foro).
•    ‘preprocess functions’: Una lista de funciones que se utilizarán para preprocesar los datos. Normalmente no se utiliza.
•     ‘override preprocess functions’: Dar el valor TRUE cuando un theme no precise las funciones de preprocesado estándar. Se puede utilizar para dar un control absoluto sobre como se gestionan las variables.
•     ‘type’: (Creado automáticamente) Dónde el hook del theme se indica: 'module', 'theme_engine', or 'theme'.
•     ‘theme path’: (Credo automáticamente) El directorio del modulo o el theme, aí no es necesario buscarlos.
•     ‘theme paths’: (Creado automáticamente) Un array con sugerencias de plantillas .tpl.php relacionadas con este theme.

hook_elements()

hook_elements()

Permite a los módulos declarar sus propio elementos de Forms API y especificar sus valores por defecto.

Los valores retornados por este hook serán incorporados con los elementos devueltos por hook_form() y podrán ser retornados por defecto por cualquier Form API además de los mencionados debajo.

Parámetros

Este hook no recibe ningún parámetro.

Retorna

Un array asociativo describiendo los tiopos de elementos definidos. Los arrays contienen un subarray para cada tipo de elemento con el nombre interno del tipo como llave. Cada subarray tiene un número de posibles atributos:

•     '#input': booleano indicando si el elemento contiene un valor o no.
•     '#process': Array de funciones de callback a las que se les envía $element y $form_state.
•     '#after_build': Array de funciones de callback a las que se les envía $element y $form_state.
•     '#validate': Array de funciones de callback a las que se les envía $form y $form_state.
•    '#element_validate': Array de funciones de callback a las que se les envía $element y $form_state.
•     '#pre_render': Array de funciones de callback a las que se les envía $element y $form_state.
•     '#post_render': Array de funciones de callback a las que se les envía $element y $form_state.
•     '#submit': Array de funciones de callback a las que se les envía $form y $form_state.

hook_nodeapi()

hook_nodeapi(&$node, $op, $a3 = NULL, $a4 = NULL)

Actúa en nodos definidos por otros módulos. A pesar de lo que su nombre pueda hacer pensar, este hook no está reservado para módulos de nodos. Al contrario, permite a los módulos reaccionar a las acciones que afecten a todo tipo de nodos independientemente de que ese nodo haya sido definido por el módulo. Si estás escribiendo un módulo de nodo, Si usted está escribiendo un módulo de nodo, no debe utilizar este hook para llevar a cabo acciones sólo en su tipo de nodo.

Parámetros

•     &$node: El nodo sobre el que se está actuando.
•     $op: Indica que acción se está llevando a cabo en el nodo. Puede tener los siguientes valores:
•     'delete': El nodo está siendo borrado.
•    'delete_revision': La revisión del nodo que está siendo borrada. Puedes borrar datos asociados a esa revisión.
•     'insert': El nodo está siendo creado.
•     'load':El nodo en cuestión va a ser cargado de la BD. Se puede utilizar para añadir datos en este momento.
•     'prepare': El nodo va a ser mostrado en un formulario de añadir/editar.
•     'search result': El nodo es mostrado como resultado de una búsqueda, si quieres mostrar informacion extra con el resultado, retórnala.
•     'print': Se prepara la vista del nodo para ser mostrada.
•     'update': El nodo se está modificando.
•     'update index': El nodo se está indexando, si quieres indexar información adicional que no estodavía visible a través de nodeapi "view", se debería retornar aquí.
•     'validate': Se utiliza para comprobar los datos del nodo.Los errores deben mostrarse de la forma form_set_error().
•     'view': El nodo se está montando antes de mostrarse. El módulo puede añadir elemntos $node->content antes de mostrar. Este hook se llama después del hook_view(). El formato de $node->content es el mismo que el usado en las Forms API.
•     'alter': El array $node->content ha sido mostrado, así que el teaser o el cuerpo están filtrados y contienen HTML, esta opción debería usarse sólo cuando sea necesaria la sustitución de texto, el filtrado u otra sean necesarias.
•     'rss item': Una feed RSS es generada. El módulo puede retornar propiedades que serán añadidas al eloemento RSS generado para este nodo.
•     $a3
•     Para "view", pasa el parámetro $teaser de node_view().
•     Para "validate", pasa el parámetro $form de node_validate().
•     $a4
•     Para "view", pasa el parámetro $page de node_view().

Retorna

El valor que se retorna depende de la operación:

•     'submit', 'insert', 'update','delete', 'print' y 'view' no retornan valor.
•     'load' debería retornar un array que contenga pares campo=>valor que serán añadidos al objeto nodo.

hook_block()

hook_block($op = 'list', $delta = 0, $edit = array())

Con el se declara uno o varios bloques para un módulo. Cualquier módulo puede definir uno o varios bloques utilizando este hook. Las funciones en las que se define el contenido que mostrará el bloque se pueden definir en cualquier parte del módulo y en caso de no retornar nada, el bloque no se mostrará.

Parámetros

•     $op, en el que se define la operación del nodo que se requiere en ese momento:

•     'list': La definición de los bloques definidos en el módulo.
•     'configure': El formulario de configuración de los bloques.
•     'save': Salvar las opciones de configuración.
•     'view': Procesar el bloque cuando está activo para mostrarlo en una determinada región.

•     $delta,se refiere a cual de los bloques definidos en el módulo se refiere la acción de $op.

Retorna

En función del parámetro de $op que se le pase al hook, deberá retornar la función una cosa u otra:

•     $op == 'list': Un array asociativo con los siguientes campos:
•     'info': (Obligatorio) El nombre del bloque para el usuario.
•     'cache': Una de las siguientes opciones en función del comportamiento del bloque respecto a la caché. Opciones:
•     BLOCK_CACHE_PER_ROLE (por defecto): El bloque puede cambiar dependiendo del rol al que pertenece el usuario quevisualiza la página.
•     BLOCK_CACHE_PER_USER: El bloque puede cambiar en función del usuario que visualiza la página. Este ajuste puede consumir recursos de sitios con gran número de usuarios, y debe usarse sólo cuando BLOCK_CACHE_PER_ROLE no es suficiente.
•     BLOCK_CACHE_PER_PAGE: El bloque puede cambiar dependiendo de la página que se está viendo.
•     BLOCK_CACHE_GLOBAL: El bloque es el mismo para todos los usuarios en cada página, donde es visible.
•     BLOCK_NO_CACHE: El bloque no debe quedar en caché.
•     'weight','status','region','visibility','pages': Se le puede dar un peso, activar por defecto, elegir una región por defecto, limitar las páginas en las que se mostrará, etc. Estas opciones serán registradas en la primera carga del bloque y se podrán modificar manualmente en la administración del bloque.
•     $op == 'configure': El formulario de configuración del bloque.
•     $op == 'save': no retorna nada y se almacenan las variables del bloque de la siguiente manera:

variable_set('geo_block_height', $edit['height']);

•     $op == 'view': Retorna un array con el elemento subject,que suele ser el título del bloque y el elemento content, que es la función en la que se decide que muestra el bloque.