Cómo crear widgets personalizados de WordPress

Spanish (Español) translation by Marilu (you can also view the original English article)

Construir widgets de WordPress es como construir un plugin, pero es más simple y directo. Todo lo que necesitas es tener un solo archivo en el cual va todo el PHP y es más fácil de codificar que un plugin que puede tener más de un archivo. Hay tres funciones principales de un widget que pueden desglosarse en widget, update y form.

function widget()
function update()
function form()

Estructura básica

El esquema básico de nuestro widget es muy simple y hay un puñado de funciones que necesitarás conocer. La estructura mínima de nuestro widget es algo así:

add_action( 'widgets_init', 'register_my_widget' );	// function to load my widget

function register_my_widget() {}						// function to register my widget

class My_Widget extends WP_Widget () {}		// The example widget class

function My_Widget() {}						// Widget Settings

function widget() {}						// display the widget

function update() {}						// update the widget

function form() {}							// and of course the form for the widget options

Paso 1

Antes de hacer todo eso, primero cargaremos nuestro widget cuando sea necesario mediante la función "widget_init". Este es un gancho de acción y puedes encontrar más sobre él en el codex de WordPress.

1	add_action( 'widgets_init', 'register_my_widget' );

Lo siguiente que haremos es registrar nuestro widget en WordPress para que esté disponible en la sección de widgets.

1	function register_my_widget() {
2	register_widget( 'My_Widget' );
3	}

Paso 2

Incluiremos nuestro widget en una clase. ¡El nombre de la clase es importante! Una cosa que debe tenerse en cuenta es que el nombre de la clase y el nombre de la función deben ser los mismos.

1	class My_Widget extends WP_Widget {}

Ahora pasaremos algunos parámetros de ajuste a esta clase. Por ejemplo, podemos pasar esto por el ancho y la altura. También podemos dar a nuestro widget una pequeña descripción si queremos, lo cual es útil si lo unes a tu tema comercial.

function My_Widget() {
	function My_Widget() {
		$widget_ops = array( 'classname' => 'example', 'description' => __('A widget that displays the authors name ', 'example') );
		$control_ops = array( 'width' => 300, 'height' => 350, 'id_base' => 'example-widget' );
		$this->WP_Widget( 'example-widget', __('Example Widget', 'example'), $widget_ops, $control_ops );
	}

Ahora que hemos completado los requisitos básicos de nuestro widget, centraremos nuestra atención en las tres funciones de las que hablamos antes, ¡que son las funciones importantes o los principales bloques de construcción de nuestro widget!

Paso 3 Function Widget()

La primera función está relacionada con la visualización de nuestro widget. Pasaremos un par de argumentos a nuestra función de widget. Pasaremos argumentos del tema, que pueden ser un título y otros valores específicos. A continuación pasamos la variable de instancia, que está relacionada con la clase de nuestra función.

1	function widget( $args, $instance )

Después de eso extraeremos los valores del argumento porque queremos que los valores estén disponibles localmente. ¡Si no sabes de qué se trata esta variable local, no te preocupes ahora mismo y simplemente añade este paso!

1	extract( $args );

A continuación estableceremos el título y otros valores para nuestro widget, que pueden ser editados por el usuario en el menú de widgets. También incluimos las variables especiales como $before_widget, $after_widget. Estos valores se manejan por el tema.

$title = apply_filters('widget_title', $instance['title'] );
$name = $instance['name'];
$show_info = isset( $instance['show_info'] ) ? $instance['show_info'] : false;

echo $before_widget;

// Display the widget title 
if ( $title )
	echo $before_title . $title . $after_title;

//Display the name 
if ( $name )
	printf( '<p>' . __('Hey their Sailor! My name is %1$s.', 'example') . '</p>', $name );

if ( $show_info )
	printf( $name );

echo $after_widget;

Paso 4 Update Function()

Lo siguiente es la función de actualización. Esta función tomará los ajustes del usuario y los guardará. Solo actualizará los ajustes según el gusto del usuario.

function update( $new_instance, $old_instance ) {
	$instance = $old_instance;

	//Strip tags from title and name to remove HTML
	$instance['title'] = strip_tags( $new_instance['title'] );
	$instance['name'] = strip_tags( $new_instance['name'] );
	$instance['show_info'] = $new_instance['show_info'];

	return $instance;
}

Una cosa a tener en cuenta aquí es que estamos quitando los valores para que cualquier XHTML pueda ser eliminado del texto, lo que, en palabras simples, podría afectar el funcionamiento de nuestro widget.

Paso 5 Form Function()

El siguiente paso esbozará la creación de la forma que servirá como cuadro de entrada. Esto tomará los ajustes y valores definidos por el usuario. La función de formulario puede incluir casillas de verificación, casillas de entrada de texto, etc.

Antes de crear estos campos de entrada, tendremos que decidir qué mostrar cuando el usuario no seleccione nada del widget. Para ello le pasaremos algunos valores por defecto como el título, la descripción, etc.

//Set up some default widget settings.

$defaults = array( 'title' => __('Example', 'example'), 'name' => __('Bilal Shaheen', 'example'), 'show_info' => true );

$instance = wp_parse_args( (array) $instance, $defaults ); ?>

Ahora crearemos el cuadro de texto de entrada. Incluiremos estas opciones en el párrafo que acompaña a la etiqueta.

// Widget Title: Text Input
<p>
	<label for="<?php echo $this->get_field_id( 'title' ); ?>"><?php _e('Title:', 'example'); ?></label>
	<input id="<?php echo $this->get_field_id( 'title' ); ?>" name="<?php echo $this->get_field_name( 'title' ); ?>" value="<?php echo $instance['title']; ?>" style="width:100%;" />
</p>

//Text Input 
<p>
	<label for="<?php echo $this->get_field_id( 'name' ); ?>"><?php _e('Your Name:', 'example'); ?></label>
	<input id="<?php echo $this->get_field_id( 'name' ); ?>" name="<?php echo $this->get_field_name( 'name' ); ?>" value="<?php echo $instance['name']; ?>" style="width:100%;" />
</p>


// Checkbox
<p>
	<input class="checkbox" type="checkbox" <?php checked( $instance['show_info'], true ); ?> id="<?php echo $this->get_field_id( 'show_info' ); ?>" name="<?php echo $this->get_field_name( 'show_info' ); ?>" /> 
	<label for="<?php echo $this->get_field_id( 'show_info' ); ?>"><?php _e('Display info publicly?', 'example'); ?></label>
</p>

Conclusión

Y eso es todo. Acabas de hacerte un widget muy bonito y sencillo que muestra el nombre del autor del blog. Además, da la opción al usuario de mostrarlo públicamente al público o no. Guarda el código en un archivo PHP y súbelo a tu directorio de temas. Llámalo en tus functions.php. Después de eso ve a tu panel de widgets y verás el widget recién creado.

Todo el código está incluido en el archivo de descarga para que sea más fácil de copiar y pegar. ¡Diviértete!