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.
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:
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.
|
|
Funciones de Activation/Desactivation | |
---|---|
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:
Lo pasos básicos para hacer que esto suceda (descritos en más detalle más adelante) son:
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.
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:
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.
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.
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.
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:
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.
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:
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.
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.
See Plugin API/Filter Reference for a current list of filter hooks in WordPress, and links to previous versions of WordPress.
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; }