Plugins (VII) Conectores: Acciones y filtros

Los conectores son una forma estandarizada de «conectarse» a  WordPress. Permiten ejecutar funciones en momentos determinados y modificar el resultado esperado. Los conectores son el medio principal que tienen los plugins para interactuar con el contenido que tenemos dentro de WP. Dentro de los conectores podemos diferenciar entre Acciones y Filtros.

Un conector es simplemente la invocación de una función PHP con distintos parámetros según la siguiente sintaxis.

<?php add_action ($etiqueta, $funcion_que_annadir, $prioridad, $argumentos_aceptados);?>

Acciones y filtros

Cómo ya hemos dicho existen dos tipo de conectores, las acciones que se desencadenan mediante eventos (como al publicar una nueva entrada) y los de filtro que modifican el contenido de WP antes de guardarlo en la BBDD o mostrarlo por la pantalla.

Acciones

Las acciones se desencadenan mediante eventos, y al contrario que con los filtros, las acciones no necesitan valores de retorno. El núcleo notific al código que ha tenido lugar un evento.

Vamos a ver como es un ejemplo del conector de acción:

<?php add_action('nombre_conector', 'prowp_function'); ?>

La función add_Action acepta cuatro parámetros al igual que los filtros:

Orden parametros tipo Descripción
 1 action  (cadena)  la acción que se va a utilizar
 2  custom_filterfunction  (cadena)  la función personalizada por la que pasar la accion
 3  priority  (entero)  prioridad de ejecución de la accion, determina el orden de llamada dentro del mismo conector
 4  acepted_args (entero) El número de argumentos que acepta la función

Podemos ver a continuación un ejemplo de como funciona una accion:

function prowp_email_new_coment()
{
  wp_mail('yo@ejemplo.com', 'Nuevo comentario en el blog', 'Hay un nuevo comentario comentario en el blog: http://mialtoweb.es');
}

add_action('comment_post', 'prowp_email_new_comment');

Esta acción lo que hace es enviar un mail a un correo dado cuando WP detecta que se ha enviado un nuevo comentario al blog. Se puede observar que la función no recibe argumentos (aunque puede recibirlos) ni devuelve nada.

Conectores de acción más habituales

Hay muchos conectores de acción pero algunos de los más utilizados son los siguientes:

Conector Donde se desencadena
publish_post Al publicar una nueva entrada
create_category Al crear una nueva categoría
switch_theme Al cambiar el tema
admin_head En la sección <head> del escritorio administrativo
wp_head En el <head> del tema
wp_footer En el pie del tema
init En la sección después de cargarse WO pero antes de enviar encabezados, es un lugar idoneo para interceptar solicitudes $_GET y $_POST
admin_init Igual que init pero solo en el escritorio administrativo
user_register Al crear un nuevo usuario
comment_post Al crear un nuevo comentario

A continuación veremos algunos casos de estos conectores más utilizados:

Por ejemplo el wp_head nos permite añadir código personalizado a la sección head:

function custom_css()
{
  ?>


<style type="text/css">
  /*Código css a ejecutar*/
  </style>


  <?php
}

add_action('wp_head', 'custom_css');

Así se puede usar wp_footer, que nos permite introducir cualquier código personalizado en el pie de la pagina del tema como por ejemplo para añadir el código de google analitics…

function wp_ganalitics()
{
  ?>
  <script type="text/javascript">
    /*Código de google analitics*/
  </script>
  <?php
}

add_action('wp_footer', 'wp_ganalitics');

Desde aquí como puedes ver las opciones son casi ilimitadas

Filtros

De este modo si queremos hacer un conector de filtro podría ser algo así:

<?php add_filter ( 'the_content', 'prowp_function');?>

En este ejemplo vemos como para usar el filtro se debe de utilizar la función add_filter() y que recibe el contenido del post que debe de pasar primero por la función personalizada prowp-function.

Con esto podemos empezar a conocer un poco más profundamente a la función add_filter() que admite hasta cuatro parámetros:

Orden parametros tipo Descripción
 1  filter_action  (cadena)  el filtro que se va a utilizar
 2  custom_filterfunction  (cadena)  la función personalizada por la que pasar el filtro
 3  priority  (entero)  prioridad de ejecución del filtro, determina el orden de llamada dentro del mismo conector
 4  acepted_args (entero) El número de argumentos que acepta la función

Por ejemplo veamos el siguiente filtro que añadiremos a un plugin:

function control_lenguaje($content)
{
  $malsonante = array('tonto', 'capullo');
  $content = str_replace($malsonante, '[censurado]', $content);
  return $content;

}

add_filter('the_content', 'control_lenguaje');

petisoEste código añade un filtro donde se recoge el contenido de una entrada y se le pasa por la función control_lenguaje, la cual recibe como argumento el contenido.

A continuación se declara un array con las palabras malsonantes que queremos que registre nuestro WP, y se toma la cadena guardada en $content cambiando las palabras de esa cadena que se encuentran en nuestro array de palabras que no queremos que aparezcan y las cambiamos por las cadena [censurado]

Finalmente devolvemos la cadena por medio de un return y ya se mostrará el contenido pero modificando las palabras seleccionas por [censurado], pero no ha modificado la entrada en la base de datos, solo ha modificado la entrada a la hora de mostrarla.

Es un ejemplo muy sencillo de un primer plugin ya operativo.

Conectores de filtro más habituales

Existen más de 1500 conectores diferentes en WP,  aunque en realidad se utilizan comúnmente solo unos pocos como los que vamos a ver aquí:

Conector Definición
the_content Se a aplica al contenido de una entrada antes de mostrarla
the_content_rss Se aplica al contenido de una entrada antes de incluirla en el RSS
the_title Se aplica al título antes de mostrarlo
comment_text se aplica al texto de un comentario antes de mostrarlo
wp_title se aplica al elemento <title> de una página antes de mostrarla
the_permalink Se aplica a la URL de un enlace permanente

Si se tiene un poco de imaginación y conocimientos de WP, viendo estos conectores se pueden intuir muchos otros.

Conclusiones

Ya hemos dado algo de funcionalidad a nuestros plugins, y como podemos ver solo con los conectores se pueden lograr resultados muy interesantes.

Los conectores son una de las características menos documentadas de WP, por ello espero que esta entrada os haya resultado útil y didáctica, pero siempre se puede ampliar información o buscar el conector adecuado en las siguientes direcciones del codex.

Para acciones

http://codex.wordpress.org/Plugin_API/Action_Reference

Para filtros:

http://codex.wordpress.org/Plugin_API/Filter_Reference