50 Actions (acciones) de WordPress - Introducción

Spanish (Español) translation by Oscar Abad Folgueira (you can also view the original English article)

La razón por la que WordPress es el gestor de contenidos más popular en el mundo es la flexibilidad. La maravillosamente simple estructura de los "hooks" le da a WordPress esta habilidad. Sin filter hook y action hooks, WordPress no sería tan extensible y no tendríamos un repositorio tan amplio de plugins y temas.

En esta serie de tutoriales vamos a ver las acciones (actions), uno de los dos tipos de hooks de WordPress. A lo largo de este curso aprenderemos casi todo lo que hay que saber sobre los actions (acciones):

En la primera parte, que es éste artículo, vamos a aprender qué son las actions de WordPress y cómo utilizarlas con siete funciones del core de WordPress.
En la siguientes cinco partes, veremos un amplio conjunto de ejemplos sobre las actions de WordPress. En cada parte, vamos a ver 10 actions (acciones) aprendiendo para qué son buenas y haciendo un ejemplo con cada action.
En el final de esta serie, resumiremos lo que hemos aprendido y los 50 ejemplos que hemos hecho.

Va a ser un viaje largo e increíble. ¡Agárrate!

¿Qué es un action (acción) de WordPress?

En el Codex, los actions los define como:

Los actions son ejecutados por eventos específicos que tienen un lugar específico en WordPress, como publicando un post, cambiando temas, o mostrando la página de administración. Un action es una función PHP definida en tu plugin (o tema) y hooked (enganchada), i.e. configurada para responder a alguno de estos eventos.

Por lo tanto, en esencia, los actions son funciones lanzadas por un evento de WordPress y se ejecutan antes o después de un evento. Los Actions son un de los dos tipos de "hooks" en WordPress - el otro tipo son los "filters" (filtros) que veremos más adelanta - puedes ver "50 filtros de Wordpress" si quires saber más sobre los filters de WordPress.

Usando Actions en WordPress

Definir lo que son los actions es la cosa más sencilla que vamos a ver en esta serie de tutoriales. Por suerte, aprende cómo crear y usar actions es casi tan fácil. Vamos a ver cómo enganchar las funciones a los actions (acciones), crear nuevos actions, eliminar algunos y algunas otras funciones relacionadas con los actions en el core de WordPess.

Enganchar una Función a un Action

Probablemente la función más fácil es esta: Se utiliza para enganchar (hook) nuestra función a un action hook que vamos a usar.

<?php

add_action( $hook_name, $function_name, $priority, $arguments );

?>

Vamos a ver qué son estos parámetros:

$hook_name es el nombre del action hook que vamos a utilizar
$function_name es el nombre de nuestra función
$priority es un número entero que especificamos para establecer el orden en que se ejecutará la función en el action hook
$arguments es el número de argumentos que usa nuestra función y que permite el action hook

Veamos un ejemplo rápido:

<?php

add_action( 'add_meta_boxes', 'my_function', 10, 2 );

function my_function( $post_type, $post ) {
  // do stuff with $post_type and $post
}

?>

Demasiado fácil, ¿verdad?

Eliminar Funciones de un Action Hook

Disponemos de dos funciones para eliminar funciones de los action hooks: remove_action() y remove_all_actions(). Veamos cómo usarlos:

<?php

// remove_action( $hook_name, $function_name, $priority );
remove_action( 'login_enqueue_scripts', 'some_function', 10 );

// remove_all_actions( $hook_name, $priority
remove_all_actions( 'wp_enqueue_scripts', 10 );

?>

La función remove_action() tiene tres parámetros: el nombre del hook, el nombre de la función que vamos a eliminar del hook, y la prioridad que se ha establecido usando add_action(). La función remove_all_actions() no tiene el parámetro $function_name ya que elimina todas las funciones enganchadas a el action.

Crear un Action Hook

Si desarrollas plugins o temas WordPress es una buena práctica crear algunos hooks en tu código para que otros programadores puedan extender tu plugin o tema. Para hacer esto, disponemos de dos funciones: do_action() y do_action_ref_array(). Veamos cómo funciona la primera:

<?php

do_action( $hook_name, $arg1, $arg2, /* ... */ $argN );

/*
 * Usage:
 * 
 * add_action( hook_name, my_function )
 * 
 * function my_function( $arg1, $arg2 ) {
 *     // do stuff with $arg1, $arg2 and so on
 * }
 * 
 */

?>

Como puedes ver, la función tiene virtualmente un número infinito de parámetros que puedes definir tantos argumentos como necesites. Si necesitas almacenar tus argumentos en un array, piensa, necesitas utilizar la segunda función:

<?php

$args = array( $arg1, $arg2, /* ... */ $argN );

do_action_ref_array( $hook_name, $args );

/*
 * Usage:
 * 
 * add_action( hook_name, my_function )
 * 
 * function my_function( $args ) {
 *     // do stuff with $args[0], $args[1] and so on
 * }
 * 
 */

?>

Conseguir el Número de Veces que un Action es Ejecutado

Si alguna vez necesitas saber cuántas veces se ha llamado a un action, puedes usar esta función para contar las llamadas al action:

<?php

function tuts_foo() {
	$action_count = did_action( 'some_action_name' );
	if ( 1 === $action_count ) {
		// run code if 'some_action_name' has been fired only once
	}
}

?>

Como puedes ver, el único parámetro que tiene la función es el nombre del action hook.

Comprobar si Algo se ha Enganchado a un Action

Imagina que estas desarrollando una extensión para un plugin Wordpress muy popular y que necesitas comprobar si es usuario ha instalado el plugin o no. (Después de todo, tu plugin no funcionará si el otro no está instalado y activado.)

Para comprobarlo, puedes usar la función has_action() para estar seguro de que el action del plugin está disponible:

<?php

if( has_action( 'some_popular_plugin_action' ) {
	add_action( 'some_popular_plugin_action', 'extension_to_the_some_popular_plugin' );
} else {
	wp_die( 'Sorry to kill your website but I need "Some Popular Plugin" to work with.' );
	// CAUTION: This is a joke. Don't shut down a website because your plugin can't work with it.
}

?>

Al igual que la función did_action(), la función has_action() tiene solo un parámetro: el nombre del action hook.

Conclusión

Ahora que hemos visto casi todo sobre la creación y el uso de los actions, podemos seguir con el viaje de cinco artículos sobre ejemplos de action. Revisaremos solo 50 de ellos pero si eres curioso o curiosa, puedes encontrar cientos más en el core.

Espero que disfrutes con esta serie de tutoriales tanto como lo he hecho yo cuando los he creado. Si crees que puedes ayudarme con los tutoriales sugiriéndome mas actions y preguntándome por más ejemplos, no dudes en decírmelo y compartirlo a través de un comentario. Y si te ha gustado lo que has leído en esta serie de tutoriales, no te olvides de compartir los artículos.

¡Nos vemos en el siguiente tutorial!

¡Sé el primero en conocer las nuevas traducciones–sigue @tutsplus_es en Twitter!