Introducción

Esta página documenta los hooks API (Interface de Programación de Aplicaciones) disponibles para desarrolladores de plugin de WordPress, y su uso.

Este artículo asume que usted ya ha leído Escribiendo un Plugin, que le ofrece una visión general (y muchos detales) sobre como desarrollar un plugin. Este artículo trata específicamente sobre el API de los "Hooks", también conocidos como "Filtros" y "Acciones", que WordPress utiliza para poner su plugin en marcha. Estos hooks se pueden utilizar también en plantillas tal y como se describe aquí.

Nota: Esta información se aplica a versiones de WordPress Versions 1.2 y superiores. Antes de la Version 1.2, las modificaciones se llamaban "hacks" e involucraba editar el código fuente del mismo WordPress.

Hooks, Acciones y Filtros

WordPress dispone de Hooks para permitir a los plugin 'anclarse' en el resto de WordPress; esto es, llamar a las funciones de su plugin en momentos específicos, y de esta forma, poner su plugin en marcha. Hay dos tipos de hooks:

1. Acciones: Las Acciones son los hooks que lanza el núcleo de WordPress en puntos específicos durante la ejecución, o cuando ocurre un evento concreto. Su plugin puede especificar que una o más de sus funciones PHP se ejecuten en esos puntos, utilizando el API Acción.
2. Filtros: Los Filtros son los hooks que lanza el WordPress para modificar textos de varios tipos antes de añadirlos a la base de datos o enviarlos a la pantalla del navegador. Su plugin puede especificar que una o más de sus funciones PHP se ejecuten para modificar tipos específicos de texto en esos momentos, utilizando el API de Filtro.

A veces se puede conseguir el mismo fin ya sea con acciones como con filtros. Por ejemplo, si desea que su plugin cabie el texto de un post, usted podría añadir una función de acción a publish_post ( de forma que el post se modifica cuando es guardado en la base de datos), o una función de filtro a the_content (de forma que el post se modificará en el momento en que es mostrado en pantalla).

Para una lista completa de todos los hooks de acción y filtro consultar Adam Brown's WP Hooks Database.

Referencia de Funciones

Acciones

Las Acciones son disparadas por eventos específicos que tienen lugar en WordPress, tales como publicar un post, cambiar una plantilla o mostrando una página del panel de administración. Su plugin puede responder al evento ejecutando una función PHP, que puede hacer uno o más de lo siguiente:

• Modificar la base de datos
• Enviar un correo electrónico
• Modificar lo que se muestra en la pantalla del navegador (del admin o de un usuario final)

Lo pasos básicos para hacer que esto suceda (descritos en más detalle más adelante) son:

1. Crear una función PHP, en su archivo de plugin, que podría ejecutarse cuando ocurre el evento.
2. Crear un Hook de acción en WordPress, llamando a add_action()
3. Poner su función PHP en un archivo de plugin, y activarlo.

Crear una Función de Acción

El primer paso para crear una acción en su plugin es crear una función PHP con la funcionalidad que usted desea para el mismo, y ponerla en su archivo de plugin (su archivo de plugin debe ir en la carpeta wp-content/plugins). Por ejemplo, si usted desea que sus amigos reciban un correo cada vez que usted crea un nuevo post, debería definir la siguiente función:

function email_friends($post_ID)  {
    $friends = 'bob@example.org,susie@example.org';
    mail($friends, "sally's blog updated", 
      'Acabo de publicar algo en mi bitácora: http://blog.example.com');
    return $post_ID;
}

Para la mayoría de las acciones, su función debería aceptar un único parámetro (normalmente el ID del post o comentario, dependiendo de la acción). Algunas acciones toman más de un parámetro -- Compruebe la documentación de la acción (si está disponible) o la fuente del código de WordPress para obtener más información. Además de un parámetro, usted también puede acceder a las variables golbales de WordPress, y llamar a otras funciones de WordPress (o funciones en su archivo de plugin).

Cualquier salida de texto hecha por la función (p.ej. con print) aparecerá en la página en la ubicación donde se invocó la acción.

NOTA: Tenga en cuenta que otros plugins o el núcleo de WordPress puede estar ya utilizando el nombre de función que usted ha pensado. Consulte Avoiding Function Name Collisions para más información.

Hook a WordPress

Una vez usted ha definido su función, el siguiente paso es "anclarla" o registrarla con WordPress. Para hacerlo, haga una llamada a add_action() en el espacio global de ejecución en su archivo de plugin:

add_action ( 'nombre_del_hook', 'nombre_de_su_función', [prioridad], [argumentos_aceptados] );

donde:

nombre_del_hook 

El nombre de un hook de acción provisto por WordPress, que indica con que evento ha de asociarse su función.

nombre_de_su_función 

El nombre de la función que usted quiere que se ejecute siguiendo al evento especificado por nombre_del_hook. Esta puede ser una función PHP estándar, una función presente en el núcleo de WordPress, o una función definida por usted en su archivo de plugin (tal como 'email_friends' definida anteriormente).

prioridad 

Un número entero opcional que puede usarse para especificar el orden en el cual se ejecutarán las funciones asociadas con una acción particular (por defecto: 10). Los número más pequeños se ejecutarán antes, y las funciones con la misma prioridad se ejecutarán en el orden en el que han sido añadidas a la acción.

argumentos_aceptados 

Un argumento de número entero, opcional, que define el número de argumentos que puede aceptar la función (por defecto 1), útil porque algunos hooks pueden pasar más de un argumento a su función. Este parámetro es nuevo desde la versión 1.5.1.

En el ejemplo anterior,podríamos poner la siguiente línea en el archivo de plugin:

add_action ( 'publish_post', 'email_friends' );

Igualmente, usted además puede Quitar Acciones de los hooks de acción. Consulte esta sección para detalles.

Instalar y Activar

El último paso para hacer funcionar su hook de acción es instalar el archivo y activar el plugin. La función PHP que usted escribió y la llamada a add_action deben ir en un archivo PHP juntas, y el archivo PHP debe instalarse en la carpeta wp-content/plugins. Una vez instalado, usted necesitará visitar la sección admin de WordPress y activar su plugin; consulte Gestionando Plugins para más detalles.

Hooks Actuales para Acciones

Consulte API Plugin/Referencia de Acción para la lista actual de hooks de acción en WordPress, y enlaces a versiones previas de WordPress.

Filtros

Los Filtros son funciones a través de las cuales WordPress hace pasar los datos, en momentos particulares de la ejecución, justo antes de tomar alguna acción con ellos (tal como añadir la información a la base de datos o mandarla a la pantalla del navegador). Los filtros se situan entre la base de datos y el navegador (cuando WordPress añade nuevos post y comentarios a la base de datos); la mayor parte de las entradas y salidas en WordPress pasa a través de, al menos, un filtro. WordPress hace algún filtro por defecto, y su plugin puede añadir sus propios filtros.

Los pasos básicos para añadir sus propios filtros a WordPress (descritos en más detalle más adelante) son:

1. Crear un afunción PHP que filtre los datos.
2. Hacer un hook al filtro en WordPress, llamando a add_filter()
3. Poner su función PHP en un archivo de plugin, y activarlo.

Crear una Función de Filtro

Una función de filtros toma una entrada de datos sin modificar, y devuelve los datos modificados (o, en algunos casos, un valor null para indicar que la información debería ser borrada o ignorada). Si los datos no son modificados por su filtro, entonces deberá obtenerse la información original de forma que los subsiguientes plugins puedan continuar modificando los datos si es necesario.

Así, el primer paso en crear un filtro para su plugin es crear una función PHP que haga el filtro, y ponerla en el archivo de plugin (su archivo de plugin debe ubicarse en la carpeta wp-content/plugins). Por ejemplo, si usted quiere asegurarse de que sus post y comentarios no contenganFor example, if you want to make sure that your posts and comments contain no mal lenguaje, debería definir una variable con una lista de palabras prohibidas, y crear la siguiente función:

function filter_profanity($content) {
    $profanities = array('malapalabra','tambiénmala','...');
    $content=str_ireplace($profanities,'{censurado}',$content);
    return $content;
}

Why does this work without a loop? Because $profanities is an array, and str_ireplace loops through the array for you. The str_ireplace function is used instead of str_replace because str_ireplace is case insensitive.

NOTE: Keep in mind that other plugins or the WordPress core may already be using the function name you have thought of. See the Plugin Development Suggestions for more information.

Hook in your Filter

After your function is defined, the next step is to "hook" or register it with WordPress. To do this, call add_filter() in the global execution space of your plugin file:

add_filter ( 'hook_name', 'your_filter', [priority], [accepted_args] );

where:

hook_name 

The name of a filter hook provided by WordPress, which defines when your filter should be applied.

your_filter 

The name of the function that you want to use for filtering. This can be a standard PHP function, a function present in the WordPress core, or a function defined by you in the plugin file.

priority 

An optional integer argument that can be used to specify the order in which the functions associated with a particular filter are executed (default: 10). Lower numbers correspond with earlier execution, and functions with the same priority are executed in the order in which they were added to the filter.

accepted_args 

An optional integer argument defining how many arguments your function can accept (default 1), useful because some hooks can pass more than one argument to your function.

In the example above, we would put the following in the main executing section of the plugin file, to tell WordPress to filter comments for profanity:

add_filter('comment_text','filter_profanity');

You can also remove filters from filter hooks using the remove_filter() function. See Removing Actions and Filters.

Install and Activate

The last step in getting your filter hook to work is to install the file and activate the plugin. The PHP function you wrote and the add_filter() call must go into a PHP file together, and the PHP file must be installed in the wp-content/plugins directory. Once it is installed, you will need to visit the admin section of WordPress and activate your plugin; see Managing Plugins for more details.

Current Hooks for Filters

See Plugin API/Filter Reference for a current list of filter hooks in WordPress, and links to previous versions of WordPress.

Example

This is an example, as described by Ozh on the wp-hackers email list, for a plugin to modify (or overwrite) the default bloginfo() function. This will require modifying a core function behavior.

add_filter('bloginfo', 'mybloginfo', 1, 2);
add_filter('bloginfo_url', 'mybloginfo', 1, 2);

function mybloginfo($result='', $show='') {
        switch ($show) {
        case 'wpurl':
                $result = SITE_URL;
                break;
        case 'template_directory':
                $result = TEMPL_DIR;
                break;
        default: 
        }
        return $result;
}