Languages: English • Español • API 日本語 中文(简体) • (Add your language)
Esta página documenta la Interfaz de Programación de la Aplicación (API, por sus siglas en ingles) y como usar los ganchos (hooks) que ofrece.
Este articulo asume que ya has leído Writing a Plugin, artículo que provee una vista general de como desarrollar un Plugin. Este artículo es específicamente acerca del API que usa "hooks", también conocidos como "filtros" (filters) y "acciones" (actions) que WordPress usa para poner en marcha tu Plugin. Estos hooks pueden utilizarse también en temas tal y como se describe aquí.
Nota: Esta información es aplicable a WordPress versiones 1.2 y superiores. Antes de la versión 1.2, las modificaciones se denominaban hacks e implicaban la modificación del código fuente de WordPress en si.
Los Ganchos son provistos por WordPress para permitirle a tu Plugin incorporarse al resto de WordPress sin mayor inconveniente. Existen dos tipos:
En ocasiones puedes lograr el mismo resultado con una acción o con un filtro. Por ejemplo, si quieres que tu Plugin modifique el texto de una entrada, puedes agregar una acción a publish_post (para que el post sea modificado al ser guardado en la base de datos), o bien puedes agregar un filtro a the_content (para que la entrada sea modificada al ser enviada a la pantalla del navegador).
Acciones son causadas por eventos específicos que ocurren en WordPress, como publicar una entrada, cambiar de Tema, o mostrar una pagina en el panel de administración. Tu Plugin puede responder al evento al ejecutar una función de PHP; función que puede hacer una o varias de las siguientes acciones:
Los pasos básicos para lograr esto son:
add_actionEl primer paso en la creación de una función en tu Plugin es hacer la función PHP con la funcionalidad deseada en un archivo, mismo que sera guardado en el directorio wp-content/plugins del servidor. Por ejemplo, si quieres que tus conocidos reciban un mensaje de corre cada vez que publiques una entrada en tu blog, puedes definir la siguiente función:
function email_amigos($post_ID) {
$amigos = 'bob@ejemplo.org,susie@ejemplo.org';
mail($amigos, "Blog de Luz actualizado",
'He publicado algo en mi blog: http://blog.ejemplo.com');
return $post_ID;
}
Para la mayoría de las acciones tu función debe aceptar un único parámetro (usualmente el identificador de la entrada o del comentario, dependiendo de la acción). Algunas acciones pueden aceptar mas de un parámetro, verifica la documentación de la acción (de estar disponible) o el código fuente de WordPress para mas información. Además del único parámetro también puedes acceder las variables globales de WordPress, llamar funciones disponibles en WordPress o funciones disponibles en tu Plugin
Nota: Mantén en mente que otros Plugins o el núcleo de WordPress pueden ya estar usando el nombre de la función que tienes en mente. Lee Avoiding Function Name Collisions para mas información.
Después de haber definido tu función, el siguiente paso es "engancharse" (registrar tu función con WordPress). Para hacer esto, llama a add_action() en el espacio de ejecución global de tu Plugin:
add_action ( 'nombre_del_gancho', 'tu_accion', [prioridad], [argumentos] );
Donde los parámetros son:
nombre_del_gancho es el nombre de la acción provista por WordPress, que le informa a que evento deseas asociar tu función.tu_accion es el nombre de la función que quieres sea ejecutada al ocurrir el evento especificado por hook_name. Puede ser una función integrada en PHP, una función presente en el núcleo de WordPress, o una función definida por ti en el archivo de tu Plugin (como email_amigos en el ejemplo de arriba).prioridad es un argumento opcional (dígito) que puede ser usado para especificar el orden en que serán ejecutadas las funciones asociadas con la acción (valor predeterminado: 10). Números mas bajos corresponden a una ejecución mas temprana, y funciones con la misma prioridad son ejecutadas en el orden en el que fueron añadidos a la acción.accepted_args es un argumento opcional (dígito) que define cuantos argumentos la función puede aceptar (valor predeterminado: 1). Es útil dado que algunos ganchos pueden transmitir mas de un argumento a tu función. Este parámetro esta disponible a partir de WordPress 1.5.1Continuando el ejemplo de arriba, se agregaría la siguiente linea al archivo de tu Plugin:
add_action('publish_post', 'email_amigos');
Así mismo, puedes Quitar Acciones de ganchos de acción.
El ultimo paso para que tu acción funcione es instalar el archivo y activar el plugin. La función PHP escrita y la llamada add_action deben estar en un archivo PHP juntas, y el archivo PHP a su vez debe estar instalado en el directorio wp-content/plugins. Una vez instalado, es necesario ir a la pagina de administración de WordPress y activar el Plugin. Lee el articulo Managing Plugins para mas detalles.
Lee Plugin API/Action Reference para una lista actualizada de acciones en la versión actual WordPress y ligas a las listas de versiónes anteriores
Filtros son funciones a través de las cuales WordPress transmite datos en ciertos puntos de la ejecución, justo antes de tomar alguna acción con esos datos (como agregarlo a la base de datos o enviarlo a la pantalla del navegador). Los filtros se encuentran entre la base de datos y el navegador cuando WordPress esta generando paginas, y entre el navegador y la base de datos cuando WordPress esta agregando entradas y comentarios a la base de datos; la mayoría de los datos entrantes y salientes en WordPress pasan a través de por lo menos un filtro. WordPress usa algunos filtros por diseño, y tu Plugin puede agregar su propio filtrado.
Los pasos básicos para añadir tus propios filtros a WordPress son:
add_filterUna función de filtro toma los datos entrantes sin modificar y regresa datos modificados (o en algunos casos, un valor nulo para indicar que los datos deben ser eliminados o simplemente no ser tomados en cuenta). Si los datos no son modificados por tu filtro entonces deben ser regresados en su forma original para que otros Plugins puedan realizar sus propias modificaciones de ser necesario.
El primer paso en la creación de un filtro es establecer la función PHP que hará el filtrado y guardarla en el archivo de tu Plugin, mismo que sera instalado en el directorio wp-content/plugins. Por ejemplo, si quieres asegurarte que las entradas en tu blog y los comentarios no contengan palabras soeces, puedes definir una variable global con una lista de palabras prohibidas con la siguiente función:
function filter_soez($contenido) {
global $palabras_soeces;
foreach($palabras_soeces as $soez) {
$content=str_ireplace($soez,'{censored}',$contenido);
}
return $content;
}
Nota: Mantén en mete que otros Plugins o el núcleo de WordPress pueden ya estar usando el nombre de la función que tienes en mente. Lee Avoiding Function Name Collisions para mas información.
Después de haber definido tu función, el siguiente paso es engancharla, o registrarla con WordPress. Para hacerlo, hay que llamar a add_filter en el espacio de ejecución global de tu Plugin:
add_filter('nombre_del_gancho', 'tu_filtro', [prioridad], [argumentos]);
Donde los parámetros son:
nombre_del_gancho es el nombre de la acción provista por WordPress, que define cuando tu filtro debe ser aplicado.tu_filtro es el nombre de la función que quieres sea usada para realizar el filtrado. Puede ser una función integrada en PHP, una función presente en el núcleo de WordPress, o una función definida por ti en el archivo de tu Plugin.prioridad es un argumento opcional (dígito) que puede ser usado para especificar el orden en que serán ejecutadas las funciones asociadas el filtro en particular (valor predeterminado: 10). Números mas bajos corresponden a una ejecución mas temprana, y funciones con la misma prioridad son ejecutadas en el orden en el que fueron añadidos al filtro.accepted_args es un argumento opcional (dígito) que define cuantos argumentos la función puede aceptar (valor predeterminado: 1). Es útil dado que algunos ganchos pueden transmitir mas de un argumento a tu función. Continuando el ejemplo de arriba añadiríamos:
add_filter('comment_text','filter_soez');
También puedes eliminar ganchos de filtros usando la función de WordPress remove_filter(). Lee Removing Actions and Filters.
El ultimo paso para que tu filtro funcione es instalar el archivo y activar el Plugin. La función PHP escrita y la llamada add_filter deben estar en un archivo PHP juntas, y el archivo PHP a su vez debe estar instalado en el directorio wp-content/plugins. Una vez instalado, es necesario ir a la pagina de administración de WordPress y activar el Plugin. Lee el articulo Managing Plugins para mas detalles.
Lee Plugin API/Action Reference para una lista actualizada de ganchos para filtros en la versión actual WordPress y ligas a las listas de versión anteriores.
Este es un ejemplo, descrito por Ozh en la lista de correo wp-hackers para crear un Plugin que modifique (o sobre-escriba) la función predeterminada bloginfo(). Obviamente implica modificar comportamiento del núcleo de WordPress:
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;
}
En algunos casos puedes encontrar que deseas que tu Plugin deshabilite una acción o filtro incluido en WordPress, o agregado por algún otro Plugin. Puedes realizar esto al llamar remove_filter('filter_hook','filter_function') o remove_action('action_hook','action_function')
Por ejemplo, remove_action('publish_post','generic_ping'); evitaría que tu blog envie pings cada vez que una nueva entrada de blog sea publicada.
Recuerda que si un gancho fue registrado usando una prioridad que no sea la predeterminada de 10, también necesitaras especificar la prioridad en la llamada a remove_action(). También recuerda que no debes tratar de quitar cosas a menos que sepas que es lo que hace y por que lo hace. Por favor verifica la documentación de WordPress o del Plugin, o el código fuente en WordPress y en el mismo Plugin.
La manera mas eficiente de encontrar las acciones y los filtros habilitados en WordPress en una instalación es realizar una búsqueda por add_action y add_filter en el código fuente de WordPress.
En WordPress 2.1 la mayoría de las acciones y filtros realizados se encuentran en el archivo wp-includes/default-filters.php, junto con algunos más en los siguientes archivos:
wp-admin/admin-ajax.phpwp-admin/admin-functions.phpwp-admin/custom-header.phpwp-admin/edit.phpwp-admin/index.phpwp-admin/options-permalink.phpwp-admin/upload-functions.phpwp-admin/upload.phpwp-includes/bookmark.phpwp-includes/general-template.phpwp-includes/kses.phpwp-includes/plugin.phpwp-includes/rewrite.phpwp-includes/template-loader.phpwp-includes/theme.phpLa mayoría de las acciones y los filtros predeterminados se encuentran en el archivo wp-includes/default-filters.php.
Además de los ganchos descritos arriba, otra manera para un plugin cambiar el comportamiento de WordPress es modificando las funciones del núcleo de WordPress. Existe un grupo de funciones que existen con el propósito de ser modificadas por Plugins. WordPress carga estas funciones solamente si continúan sin definir después de haber registrado todos los Plugins.
Estas funciones son definidas en el archivo wp-includes/pluggable.php. Aquí hay una lista actualizada (hasta WordPress 2.1); documentación para ellas puede ser encontrada en Function Reference:
set_current_userwp_set_current_userwp_get_current_userget_currentuserinfoget_userdataupdate_user_cacheget_userdatabyloginwp_mailwp_loginis_user_logged_inauth_redirectcheck_admin_refererwp_redirectwp_get_cookie_loginwp_setcookiewp_clearcookiewp_notify_postauthorwp_notify_moderatorwp_new_user_notificationwp_verify_noncewp_create_noncewp_saltwp_hash