Languages: English • Español • ウィジェット API 日本語 中文(简体) • (Add your language)
Esta página contiene documentación técnica del API (Interfaz de Programación de Aplicaciones) para widgets de WordPress. El público objetivo de esta información incluye a diseñadores de temas para WordPress, creadores de plugin y cualquiera que desde escribir un widget. Este documento asume unos conocimientos básicos de PHP.
Un widget es una función PHP que imprime información en forma de cadenas a la salida estándar (STDOUT) cuando se le invoca. Para convertir una función PHP en un widget de WordPress, ésta ha de ser registrada como tal. Esto se hace utilizando un PHP callback (un pseudo-tipo en la documentación de PHP) que se registra gracias a una función API de WordPress.
El API de WordPress está ubicado en wp-includes/widgets.php.
|
|
Las funciones listadas más adelante se utilizan para añadir barras laterales funcionales al tema.
register_sidebars( $count, $args );
Registra una o más barras laterales para utilizar en el tema actual. Muchos temas disponen de una única barra lateral. Por esta razón, el parámetro count es opcional y el valor por defecto es 1.
El parámetro $args se pasará a register_sidebar() y sigue su formato, con la excepción del nombre, que es tratado con sprintf() para insertar o añadir un número único a cada barra lateral si count es mayor que uno.
Por ejemplo, la siguiente línea creará barras laterales con los nombres "Foobar 1" y "Foobar 2":
register_sidebars(2, array('name'=>'Foobar %d'));
register_sidebar( $args );
El parámetro opcional $args es un array asociativo que será pasado como primer argumento en toda respuesta de widget activos. (Si se pasa una cadena en vez de un array, será pasada a través de parse_str() para generar un array asociativo). El uso básico de estos argumentos es pasar etiquetas HTML específicas de un tema para envolver al widget y a su título. Aquí están los valores por defecto:
'before_widget' => '<li id="%1$s" class="widget %2$s">', 'after_widget' => "</li>n", 'before_title' => '<h2 class="widgettitle">', 'after_title' => "</h2>n"
Hay momentos en los que usted puede querer llamar a esta función en vez de registrar las barras laterales. Un ejemplo podría ser cuando usted desea dar nombres únicos a sus sidebars, tales como "Barra Lateral Derecha" y "Barra Lateral Izquierda", o cuando deberían ser marcadas de forma diferente. Los nombres aparecen en el interface de administración y se utilizan como índice para mantener la disposición de las barras. Tenga en cuenta que la disposición de las barras laterales se pueden reutilizar y sobre-escribir cuando se elige otro tema que utiliza los mismos nombres de barras laterales.
Los valores por defecto before/after están pensados para temas que generan barras laterales marcadas como una lista con títulos "h2". Esta es la convención recomendada para los temas. Los temas construidos utilizando esta estructura pueden registrar barras laterales sin problemas gracias a las etiquetas before/after. Si un tema no puede ser marcado de esta forma, estas etiquetas deben especificarse al registrar la barra. Está recomendado copiar la id y los atributos literales de claase de forma que una llamada a un sprintf interno pueda funcionar y que los estilos CSS se puedan aplicar a widgets individuales.
dynamic_sidebar( $sidebar );
Esta función llama a cada una de las respuestas de widget activos por orden, e imprime el marcado para las barras laterales. Si usted dispone de más de una barra lateral, debería dar a esta función el nombre o el número de la barra lateral que desea mostrar. Esta función devuelve true si termina correctamente, o false si encuentra un fallo.
El valor de retorno podría utilizarse para determinar si se va a mostrar una barra lateral estática. Esto aseguraría que su tema se mostrará correctamente cuando el plugin de widget no esté activo. Debajo se muestra el uso recomendado de esta función, junto con un test para prevenir errores fatales:
<ul id="sidebar">
<?php if ( !function_exists('dynamic_sidebar') || !dynamic_sidebar() ) : ?>
<li>{static sidebar item 1}</li>
<li>{static sidebar item 2}</li>
<?php endif; ?>
</ul>
Si sus barras laterales fueron registrados con un número, deberían ser recuperadas con un número. Si tenían nombres cuando usted las registró, debería utilizar sus nombres.
El desarrollo de Widget es más sencillo desde la versión 2.8. Para crear uno, solo necesita extender la clase estándar widget y algunas de sus funciones.
La clase base contiene información sobre la función que debe ser extendida para obtener un widget funcional.
class My_Widget extends WP_Widget {
function My_Widget() {
// procesos efectivos, reales del widget
}
function form($instance) {
// saca el formulario de opciones en admin
}
function update($new_instance, $old_instance) {
// procesa las opciones del widget que se guardarán
}
function widget($args, $instance) {
// saca el contenido del widget
}
}
register_widget('My_Widget');
Este ejemplo crea un Widget llamado FooWidget que tiene un formulario de configuraciones para cambiar el título.
/**
* FooWidget Class
*/
class FooWidget extends WP_Widget {
/** constructor */
function FooWidget() {
parent::WP_Widget(false, $name = 'FooWidget');
}
/** @see WP_Widget::widget */
function widget($args, $instance) {
extract( $args );
$title = apply_filters('widget_title', $instance['title']);
?>
<?php echo $before_widget; ?>
<?php if ( $title )
echo $before_title . $title . $after_title; ?>
Hello, World!
<?php echo $after_widget; ?>
<?php
}
/** @see WP_Widget::update */
function update($new_instance, $old_instance) {
$instance = $old_instance;
$instance['title'] = strip_tags($new_instance['title']);
return $instance;
}
/** @see WP_Widget::form */
function form($instance) {
$title = esc_attr($instance['title']);
?>
<p><label for="<?php echo $this->get_field_id('title'); ?>"><?php _e('Title:'); ?> <input class="widefat" id="<?php echo $this->get_field_id('title'); ?>" name="<?php echo $this->get_field_name('title'); ?>" type="text" value="<?php echo $title; ?>" /></label></p>
<?php
}
} // clase FooWidget
Este widget puede registrarse en el gancho widgets_init:
// registrar el widget FooWidget
add_action('widgets_init', create_function('', 'return register_widget("FooWidget");'));
Esto es todo. Usted habrá obtenido automáticamente un widget múltiple. No hay que darle más vueltas.
Hay más información disponible en información sobre la versión 2.8.
Gracias por preguntar. Aquí tiene unas cuantas ideas:
Widgets can be coded for multiple instances or a single instance.