Introducción a los filtros y las acciones de WordPress

This post was published 14 years ago so it may be outdated.

Nota: Este tutorial está pensado para aquellos que saben algo del desarrollo de plugins y themes para WordPress y de PHP. No está orientado a expertos, pero sí a iniciados.

Cuando se desarrolla una aplicación, se debe pensar también en un método para ampliarla, y en el caso de una aplicación de código abierto esto es mucho más importante. Pongámonos en el caso de WordPress, en el que por defecto no podemos disponer de (por poner un ejemplo) encuestas o carruseles. ¿Cómo añadimos esto? Podemos decantarnos en un principio por añadir estas funciones en nuevas versiones de WordPress, sin embargo hay una cantidad enorme de cosas que añadir y al final siempre habría alguna que no estaría disponible.

Así que hay que implementar una forma de extender la aplicación, y aquí es donde tenemos que pensar cómo hacerlo. En un principio la solución está clara: indico que código modificar para añadir la función y listo. Además se puede automatizar el proceso, de modo que el usuario sólo tendría que subir un archivo y darle a un botón y la nueva función estaría disponible. Esta solución nos puede servir al principio, pero ¿qué ocurre al actualizar la aplicación? Pues que todos los archivos modificados se reemplazan por los de la nueva versión, dejándonos en el mejor de los casos sin la función añadida y en el caso normal, con un montón de errores de llamdas a funciones inexistentes.

Y aquí es donde entran los filtros y las acciones. El método que utiliza WordPress (entre otras aplicaciones) es permitir definir filtros y acciones. El fundamento de las acciones es bastante simple, definen ciertas posiciones en los archivos de la aplicación, y cuando se llega a esas posiciones, se cargan todas las funciones que estén en la lista de acciones a ejecutar en esa posición. Un ejemplo, imaginemos que yo defino el punto “antesdemostrarlostitulos”, pues bien, si yo añado una función que muestre el texto “El título es: ” a la lista de funciones a ejecutarse en el punto “antesdemostrarlostitulos”, cuando la aplicación llegue a ese punto, cargará mi función, y por tanto se mostrará el texto. Esto hace que aunque se actualicen los archivos originales, siempre se ejecutará, porque este punto siempre estará en el mismo lugar (a no ser, claro, que los desarrolladores lo eliminen). Con los filtros ocurre algo similar. Imaginemos que yo defino el punto “antesdemostrarelcontenido” y añado un filtro que altere el contenido de modo que muestre todo el texto en mayúsculas. Aunque más adelante se actualice la aplicación, el resultado del filtro se mantendrá constante. Tenéis un esquema a modo de resumen en la imagen de la derecha.

Los lugares de los filtros y las acciones los tienen que definir los desarrolladores de la aplicación, aunque veremos más adelante cómo crear nuestras propias posiciones para filtros y acciones, así que es conveniente tener a mano una lista de los filtros y las acciones que tiene la aplicación por defecto, ya que de lo contrario la única forma de conocerlos es buscarlos manualmente.

En este tutorial nos centraremos en la creación y el uso de filtros y acciones en WordPress, y dejaremos de lado los diversos filtros y acciones que tiene por defecto, que por cierto, podéis ver aquí.

Aplicar un filtro

Tenemos la variable $contenido que almacena el texto que genera nuestro plugin, y queremos añadir un filtro llamado mostrar_contenido_mi_plugin que permita a otros programadores modificar el contenido que mostrará nuestro plugin. Bien, recurriremos a la función apply_filters, que nos devolverá la variable tras pasar por todas las funciones que se hayan añadido al filtro. Veámoslo en código:

[php]
<?php
$contenido = la_funcion_de_mi_plugin(); // La variable ahora tiene el contenido devuelto por nuestro plugin
$contenido = apply_filters(‘mostrar_contenido_de_mi_plugin’, $contenido); // Pasamos el filtro, la primera variable es el nombre y la segunda el valor que se filtrará
echo $contenido; // Mostramos la variable, aunque también podríamos volver a modificarla nosotros o hacer lo que quisiéramos con ella
?>
[/php]

Aplicar una acción

Supongamos ahora que en lugar de filtrar nuestro contenido lo que queremos hacer es permitir que otros programadores puedan ejecutar sus funciones en la acción despues_de_mostrar_contenido_plugin, acción que se aplicará justo después de mostrar el contenido de nuestro plugin. Esto puede ser útil en mucho casos, como por ejemplo a la hora de hacer recuentos tras ocurrir cierto evento o para mostrar los enlaces para compartir al final de los artículos. En este caso usaremos la función do_action, quedando en código así:

[php]
<?php
$contenido = la_funcion_de_mi_plugin(); // La variable ahora tiene el contenido devuelto por nuestro plugin
echo $contenido; // Mostramos la variable
do_action(‘despues_de_mostrar_contenido_plugin’); // En este caso el único parámetro obligatorio es el nombre de la acción
?>
[/php]

Añadir y eliminar una función de un filtro

Ya tenemos el filtro creado, pero ahora queremos añadir nuestra función al filtro para modificar el resultado. ¿Cómo lo hacemos? Fácil, con la función add_filter.

[php]
function nuestro_plugin() {
$contenido = la_funcion_de_mi_plugin(); // La variable ahora tiene el contenido devuelto por nuestro plugin
$contenido = apply_filters(‘mostrar_contenido_de_mi_plugin’, $contenido); // Pasamos el filtro, la primera variable es el nombre y la segunda el valor que se filtrará
echo $contenido; // Mostramos la variable, aunque también podríamos volver a modificarla nosotros o hacer lo que quisiéramos con ella
}

function modificar_texto($texto) {
$texto = ‘<div id="contenido">’. $texto .'</div>’; // Modificando el texto
return $texto; // Devolvemos el texto
}

add_filter(‘mostrar_contenido_de_mi_plugin’, ‘modificar_texto’); // Añadimos al filtro mostrar_contenido_de_mi_plugin la función modificar_texto

nuestro_plugin(); // Ejecutamos el plugin
[/php]

Ahora imaginemos que en un caso específico no queremos añadir cierta función al filtro, es decir, queremos eliminar la función del filtro en ciertas circunstancias. En este caso usaremos la función remove_filter, que funciona de forma contraria a add_filter:

function modificar_texto($texto) {
$texto = ‘<div id="contenido">’. $texto .'</div>’; // Modificando el texto
return $texto; // Devolvemos el texto
}

add_filter(‘mostrar_contenido_de_mi_plugin’, ‘modificar_texto’); // Añadimos al filtro mostrar_contenido_de_mi_plugin la función modificar_texto

if (se_dan_ciertas_circunstancias()) { // Supogamos que devuelve true cuando queremos eliminar la función del filtro
remove_filter(‘mostrar_contenido_de_mi_plugin’, ‘modificar_texto’); // Eliminamos del filtro
}

nuestro_plugin(); // Ejecutamos el plugin
[/php]

Añadir y eliminar una función de una acción

Volviendo a las acciones, supongamos que queremos añadir una función nuestra a la acción que hemos aplicado antes, así que tendremos que usar la función add_action.

[php]
<?php
function nuestro_plugin() {
$contenido = la_funcion_de_mi_plugin(); // La variable ahora tiene el contenido devuelto por nuestro plugin
echo $contenido; // Mostramos la variable
do_action(‘despues_de_mostrar_contenido_plugin’); // En este caso el único parámetro obligatorio es el nombre de la acción
}

function mostrar_texto() { echo ‘Ya se ha ejecutado mi plugin’; } // Esta función es la que añadiremos a la acción
add_action(‘despues_de_mostrar_contenido_plugin’, ‘mostrar_texto’); // Añadimos la función a la acción

nuestro_plugin(); // Ejecutamos el plugin
?>
[/php]

Y como antes, también podemos eliminar una función de una acción mediante remove_action:

if (se_dan_ciertas_circunstancias()) {
remove_action(‘despues_de_mostrar_contenido_plugin’, ‘mostrar_texto’); // Eliminamos la función de la acción
}

nuestro_plugin(); // Ejecutamos el plugin
?>
[/php]

Ulzurrun de Asanza i Sàez