Agregar Hooks a Medida en WordPress: Acciones a Medida

Spanish (Español) translation by Eva Collados Pascual (you can also view the original English article)

Uno de los puntos clave para la construcción de soluciones clave en WordPress es la comprensión de los hooks. Por sí mismos no es que impliquen una gran dificultad de comprensión, y los revisaremos en breve en este tutorial.

Pero si lo que buscas implica un desarrollo más avanzado de WordPress, vale la pena que sepas como implementar tus propios hooks, de todas formas.

En esta serie de dos partes, vamos a ver el sistema de hooks en WordPress y como se implementa, y echaremos un vistazo a como podemos definir tanto nuestros propios filtros como acciones.

Primeros Pasos

Antes de empezar, este tutorial asume que dispones de un entorno de desarrollo preparado que incluye la última versión de WordPress. En el momento en que escribo este artículo, la última versión era WordPress 4.5.2.

Si necesitas una guía para establecer tu entorno de desarrollo, te animo a que leas este tutorial. Te proporcionará todo lo que necesites para montar tu servidor local, una copia de PHP, una base de datos, y WordPress.

Si necesitas algo más, entonces las series en las que este tutorial se incluye proporcionan incluso más información, por ejemplo a como instalar WordPress, recorridos sobre temas y plugins, y más.

Pero en este tutorial, nos vamos a centrar en los hooks y las acciones. Así que una vez estés preparado, comencemos.

¿Qué Son Los Hooks?

Antes de verlos en profundidad, merece la pena entender el patrón de diseño dirigido por eventos (también conocido como arquitectura o metodología diseñada para reaccionar a eventos).

Si ya has trabajado con los hooks de WordPress, desarrollado interfaces web o con cualquier recurso JavaScript, te resultará familiar este patrón incluso aunque no supieses nombrar concepto.

En cualquier caso, así es como se define en Wikipedia:

La Arquitectura dirigida por eventos, Event-driven architecture o EDA, es un patrón de arquitectura software que promueve la producción, detección, consumo de, y reacción a eventos.

Si estás en tus comienzos respecto al diseño o desarrollo a través de patrones, todo esto te sonará complicado, pero otra forma de abordarlo es la siguiente:

El software contiene algunos puntos en los que difunde un mensaje indicando que algo ha sucedido.
Nosotros, como desarrolladores, somos capaces de escribir código que escucha estos mensajes y puede responderles con un código específico.

Ten en cuenta que la definición versa también sobre la producción de eventos. Cuando pasemos a hablar sobre la creación de nuestros propios hooks, revisaremos estos conceptos. Por ahora, veamos dos eventos muy comunes en la programación web.

Usar JavaScript

Primero, imagina que estás trabajando en el desarrollo de interfaces. Tienes un botón con el siguiente atributo para ID command-button, y cuando el usuario realiza un clic sobre él, quieres que muestre un cuadro de alerta.

Usando jQuery, puedes implementar la funcionalidad así:

(function( $ ) {
    'use strict';
    
    // jQuery's DOM-ready event-handler
    $(function() {
    
        /**
         * Listen for the 'click' event on the button identified
         * with the 'command-button' ID attribute.
         * 
         * When the user clicks on it, display an alert dialog.
         */
        $( '#command-button' ).bind( 'click', function( evt ) {
            alert( 'You clicked the button.' );
        });
    
    });

})( jQuery );

Los comentarios en el código siguiente deberían explicar exactamente lo que está sucediendo. Inmediatamente, el navegador ejecuta un evento cuando el usuario cliquea el botón. Cuando esto sucede, nuestro código interpreta el evento y responde mostrando el cuadro de diálogo.

Por supuesto, otras librerías, frameworks, o vanilla JavaScript recogen también esta funcionalidad. El propósito de mostrártelo mediante jQuery es debido a que es una de las librerías más comunes de JavaScript, y porque es además una de las librerías incluidas en WordPress.

Trabajando con WordPress

La implementación de este patrón no es necesariamente idéntico en todos los lenguajes de programación o paradigmas. Normalmente depende de lo que proporcionen las API's del framework, el soporte, o la aplicación.

En WordPress, el registro de nuestro propio código a través de un evento que lo dispara es un poco distinto. Por ejemplo, digamos que estás trabajando en la administración de páginas de WordPress y quieres añadir un nuevo elemento de submenu al menú principal Ajustes. Lo llamaremos Tuts+ Options.

Para lograr esto, hemos añadido el siguiente código a nuestro archivo functions.php o a nuestro plugin o a cualquier clase de proyecto en el que estés centrado:

<?php

add_action( 'admin_menu', 'tutsplus_admin_menu' );
/**
 * Adds a 'Tuts+ Options' submenu to the 'Settings'
 * menu in the WordPress administration menu.
 */
function tutsplus_admin_menu() {

    add_submenu_page(
      'options-general.php',
		'tutsplus-admin-menu',
		'Tuts+ Options',
		'manage_options',
		'tutsplus-admin-menu-top',
		'tutsplus_admin_options'
	);
}

Puedes consultar el Codex para leer más sobre el hook admin_menu así como sobre la función add_submenu_page.

Este código no añade ninguna nueva funcionalidad al menú, simplemente está pensada para demostrar que WordPress proporciona un evento admin_menu, casi como un navegador dispone de un evento para los clics. Es ahora cuando tenemos la capacidad de insertar nuestro propio código definiendo una función que será iniciada en cualquier instante en el que el evento tenga lugar.

Estos son dos ejemplos prácticos de los patrones de diseño orientados a eventos, ambos han sido implementados y usados.

Comprensión de las Acciones de WordPress

Ahora que hemos hecho un primer patrón de diseño dirigido por eventos y visto dos de sus implementaciones, echemos un vistazo a las acciones específicas de WordPress. Revisaremos qué está disponible y como lo podemos implementar las propias

Ajustando Nuestro Archivo

Para los propósitos del código en este tutorial, usaremos el tema predeterminado twentysixteen que viene incluido con WordPress.

En la raíz del directorio de temas, crea un archivo php con el nombre tutsplus-actions.php. Después, en functions.php, añade la siguiente línea de código:

1	<?php
2	include_once( 'tutsplus-actions.php' );

Estas instrucciones le indican al tema que inicie el archivo que hemos creado. El motivo por el cual queremos hacer esto es para conservar nuestro código fuera del núcleo del tema, así podremos eliminarlo fácilmente simplemente eliminando la declaración include_once anterior.

Una Breve Definición para las Acciones

En WordPress, los hooks están incluidos en una de estas dos categorías: acciones o filtros. Las acciones son puntos dentro del ciclo vital de WordPress que te permiten añadir, eliminar o modificar cierta funcionalidad. Los filtros, por otra parte, son puntos en el ciclo de vida de WordPress en los cuales puedes añadir, eliminar o modificar datos.

En breve, las acciones están pensadas para trabjar con funcionalidades, y los filtros con información. Nos centraremos más en los filtros en la segunda parte de estas series.

Una cosa que deseo puntualizar, es que si optases investigar más sobre las acciones y los filtros tras la lectura de esta serie de tutoriales (a lo cual te animo), podrías encontrar que algunos se refieren a ellas de manera genérica como hooks

Aunque es técnicamente correcto, es más pragmático y claro diferenciar el tipo de hook con el que estás trabajando cuando estás escribiendo, presentando, o discutiendo sobre este tema con alguien más.

Ya que las acciones están pensadas para gestionar un tipo de funcionalidad, y los filtros están planteados para otro.

Trabajar Con Acciones

Aunque ya hemos visto un ejemplo específico de acción en el código de más arriba, veamos un ejemplo más completo y práctico.

En su paquete, WordPress ofrece dos tipos de post: Entradas (para los artículos del blog) y Páginas (para contenido estático o aquel que rara vez cambia). Para un plataforma tipo blog, este tipo de contenido es ciertamente todo lo que necesitas. Pero WordPress ha ido evolucionando desde hace años hasta convertirse en un CMS.

Y una de las características que convierten a WordPress extensible es su capacidad para permitirnos introducir nuestros propios tipos de posts. WordPress los denomina entradas personalizadas (o custom post types en inglés), y son fantásticos cuando necesitamos crear contenido con sus propios requerimientos y que necesita ser nombrado de una manera más específica que "entradas" o "páginas".

Para crear nuestros propio custom post type,será necesario que realicemos dos cosas:

definir una función que se enlace con el hook init que proporciona WordPress.
registrar nuestra entrada personalizada mediante una de las funciones proporcionadas por la API.

Registrar Nuestras Acciones

Con el fin de registrar nuestra acción, haremos uso de la función add_action que nos provee la API de WordPress. Esto le indica a WordPress que estamos introduciendo una acción que precisa iniciar la función identificada por el nombre que le hemos descrito en la llamada a la función.

Nuestro código debería parecerse a lo siguiente:

1	<?php
2	add_action( 'init', 'tutsplus_register_post_type' );

En el código anterior, estamos registrando una función con el hook init que ya existe en WordPress. Este hook se inicia pronto dentro del ciclo de WordPress y es un buen lugar para registrar una entrada personalizada.

Lo siguiente de debemos hacer, es definir la función.

1	<?php
2	function tutsplus_register_post_type() {
3
4	}

La clave para entender como se construye esta función es sencilla:Le hemos dado el nombre de tutsplus_register_post_type ya que este es el segundo argumento que hemos enviado a la llamada add_action.

Esto literalmente le da instrucciones a WordPress para que haga lo siguiente: Durante init haz una llamada a la función tutsplus_register_post_type.

Así de claro y rápido. No hemos topado aún con nada complicado, y si refrescas tu pantalla de administración de WordPress, verás que todavía funciona aunque no esté haciendo nada nuevo.

Cambiemos ésto.

Crear una Entrada Personalizada

Ahora que ya tenemos la estructura del código para añadir nuestras propias acciones, vamos a hacer que suceda algo. En concreto, vamos a crear una entrada personalizada llamada time_traveler llamada que incluirá un título, un editor, un extracto y nada más.

Para conseguir ésto, necesitamos revisar la función register_post_type en el Codex. La documentación nos da una sólida explicación para todos los argumentos que la función es capaz de aceptar.

Específicamente, usaremos lo siguiente:

label
labels
description
public
show_ui
supports

Ahora sacaremos provecho del resto de funcionalidades que nos proporcionan los valores predeterminados WordPress. El argumento será como sigue:

<?php

$args = array(
    'label'  => 'Time Travelers',
    'labels' => array(
		'name'          => 'Time Travelers',
		'singular_name' => 'Time Traveler',
		'add_new_item'  => 'Add New Traveler',
		'edit_item'     => 'Edit Traveler',
		'new_item'      => 'New Traveler',
		'view_item'     => 'View Traveler',
		'search_items'  => 'Search Travelers',
		'not_found'     => 'No Travelers',
	),
	'description' => 'A post type used to provide information on Time Travelers.',
	'public'      => true,
	'show_ui'     => true,
	'supports'    => array(
		'title',
		'editor',
		'excerpt',
	),
);

Y finalmente, la versión completa del código para registrar la entrada personalizada será así:

<?php
add_action( 'init', 'tutsplus_register_post_type' );
function tutsplus_register_post_type() {

  $args = array(
        'label'  => 'Time Travelers',
  	'labels' => array(
  		'name'          => 'Time Travelers',
  		'singular_name' => 'Time Traveler',
  		'add_new_item'  => 'Add New Traveler',
  		'edit_item'     => 'Edit Traveler',
  		'new_item'      => 'New Traveler',
  		'view_item'     => 'View Traveler',
  		'search_items'  => 'Search Travelers',
  		'not_found'     => 'No Travelers',
  	),
  	'description' => 'A post type used to provide information on Time Travelers.',
  	'public'      => true,
  	'show_ui'     => true,
  	'supports'    => array(
  		'title',
  		'editor',
  		'excerpt',
  	),
  );

  register_post_type( 'time_traveler', $args );

}

Cuando refresques el área de administración de tu instalación de WordPress, debería aparecer un nuevo elemento de menú justo bajo Comentarios con la siguiente etiqueta Time Travelers.

Cuando pulses sobre Añadir Nuevo, deberías ver un lugar para el título (o el nombre del viajero, traveler en inglés), el editor (para la información relativa a éste), y un extracto (quizá para algunas notas sobre él). También deberías ver una meta bos para publicar la información.

Por supuesto el código de arriba nos muestra como sacar ventaja de las acciones existentes para crear entradas personalizadas. ¿Pero que ocurre si queremos crear nuestras acciones personales?

Definir Acciones Personalizadas

Cuando se trata de crear nuestras propias acciones, hay tres cosas que debemos hacer. De una manera muy fundamental, necesitaremos hacer lo siguiente:

definir el hook
añadir funcionalidad al hook
permitir que los desarrolladores puedan hacer llamadas al hook

El ejemplo más simple que puedo ofrecerte es el siguiente código:

<?php

/**
 * Define the action and give functionality to the action.
 */
 function tutsplus_action() {
   do_action( 'tutsplus_action' );
 }

 /**
  * Register the action with WordPress.
  */
add_action( 'tutsplus_action', 'tutsplus_action_example' );
function tutsplus_action_example() {
  echo 'This is a custom action hook.';
}

Siéntete libre de añadir este código a tutsplus-actions.php de forma que puedas continuar trabajar y explorar el código tras el tutorial.

Después de esto, podemos llamar a nuestra función tutsplus_action desde cualquier punto de nuestro código. Digamos por ejemplo, que quisiésemos mostrarlo en la parte superior de nuestra área de administración. Si quisiésemos eso, podríamos añadir el siguiente código:

<?php

add_action( 'admin_notices', 'tutsplus_admin_notice' );
function tutsplus_admin_notice() {
  tutsplus_action();
}

Si refrescas tu escritorio, verás en su parte superior el siguiente texto "This is a custom action hook".

Advierte que yo no recomiendo anclar en admin_notices a menos que estés planeando específicamente notificar a los usuarios con un mensaje de éxito, advertencia o error. Lo uso aquí únicamente como medio para mostrarte nuestro hook personalizado.

Repasando Nuestro Tipo de Entrada.

Digamos que queremos crear una entrada personalizada que nos permita pasar el nombre tanto en singular como en plural de nuestro tipo de entrada a una función a través de una acción de hook.

¿Qué aproximación debemos adoptar para conseguirlo? Empleando lo que acabamos de ver, sabemos que lo primero que debemos hacer es crear una función personal que llame a una acción. Así que vamos a por ello:

<?php

function tutsplus_register_custom_post_type() {

  // Set the action at priority of 10 and note that it accepts 2 arguments.
  do_action( 'tutsplus_register_custom_post_type', 10, 2 );

}

Después, tenemos que hacer algo que puede parecer contradictorio. Como queremos que nuestra funcionalidad se inicie dentro del contexto del hook init, necesitamos hacer que nuestro hook se dispara durante la acción init.

Para hacer esto, conectamos nuestro hook personalizado al hook init:

<?php
add_action( 'init', 'tutsplus_register_custom_post_type' );
function tutsplus_register_custom_post_type() {

  // Set the action at priority of 10 and note that it accepts 2 arguments.
  do_action( 'tutsplus_register_custom_post_type', 10, 2 );

}

Observa en el código de arriba que estamos especificando dos parámetros adicionales para do_action. El primero es 10, que indica la prioridad con la que sera iniciado el hook.

Puede ser cualquier cifra en donde cuanto más alto sea el número inferior será la prioridad con la que será iniciado. El segundo parámetro indica la cantidad de argumentos que el hook personalizado será capaz de aceptar. En nuestro caso, tenemos uno para la versión en singular de nuestra entrada personalizada, y otro para la versión en plural.

Tras esto, necesitamos dotar de funcionalidad al hook. Aquí, reconstruiremos el código para registrar un tipo de entrada de forma que acepte dos argumentos, y estos serán usados en el array que se envíe a la función register_post_type de WordPress.

<?php

function tutsplus_register_post_type( $singular, $plural ) {

  $args = array(
      'label'  => $plural,
  	'labels' => array(
  		'name'          => $plural,
  		'singular_name' => $singular,
  		'add_new_item'  => 'Add New Traveler',
  		'edit_item'     => 'Edit Traveler',
  		'new_item'      => 'New Traveler',
  		'view_item'     => 'View Traveler',
  		'search_items'  => 'Search Travelers',
  		'not_found'     => 'No Travelers',
  	),
  	'description' => 'A post type used to provide information on Time Travelers.',
  	'public'      => true,
  	'show_ui'     => true,
  	'supports'    => array(
  		'title',
  		'editor',
  		'excerpt',
  	),
  );

  register_post_type( 'time_traveler', $args );

}

Toma nota de que también hemos corregido la función para que no sea añadida a ningún hook en particular. En su lugar, la llamamos desde la definición de una función que está vinculada con nuestra acción personalizada.

<?php
add_action( 'tutsplus_register_custom_post_type', 'tutsplus_register_time_traveler_type' );
function tutsplus_register_time_traveler_type() {
  tutsplus_register_post_type( 'Time Traveler', 'Time Travelers' );
}

En el código superior, somos capaces de llamar a la función responsable del registro de la entrada personalizada, y al mismo tiempo pasarle nuestros argumentos de forma que podamos añadir un poco de funcionalidad personal al código.

Conclusión

La definición de hooks personalizados no es complicado, y además nos dota de un gran poder y flexibilidad a los desarrolladores. Evidentemente, la parte más complicada del código de arriba es cómo definimos un hook dentro del contexto de otro (es decir, estamos definiendo tutsplus_register_custom_post_type dentro de init).

He optado mostrar esto como ejemplo final porque hay ocasiones en las que podrías querer registrar un hook personalizado y éste necesite ser iniciado antes de que un hook pre-existente sea completado.

El registro de un hook que va a mantenerse por sí mismo es fácil: Simplemente no lo vincules a un hook preexistente, y crea una función básica tal y como vimos con el código vinculado a admin_notices.

En los próximos artículos de esta serie, veremos los filtros y lo que estos pueden hacer por nosotros desde el punto de vista de la modificación de datos. También hablaremos sobre cómo definir nuestros propios filtros de forma que seamos capaces de introducir funcionalidades propias como hemos hecho en este mismo tutorial.

Hasta el próximo artículo, si estás buscando nuevas utilidades que amplíen tu selección de herramientas para WordPress o código para prepararte y convertirte en experto en WordPress, no olvides echar un vistazo a lo que tenemos en Envato Market.

Recuerda, puedes echar un vistazo a todos los cursos y tutoriales que he creado en mi página de perfil, y además seguirme a través de mi blog y/o Twitter en @tommcfarlin en donde hablo sobre practicas de desarrollo para diferentes tipos de software y como podemos emplearlas en WordPress.

Por favor no dudes en dejar tu consulta o comentarios en el feed inferior, mi ánimo es responderlos todos.