Teleportz

Tutorial: Crear un widget para WordPress

12/08/2011 WordPress Santiago

En este tutorial aprenderemos a utilizar la API de WordPress para poder crear un widget. El widget que crearemos mostrará los últimos tweets de nuestra cuenta (De Twitter!) usando javascript.

Primer paso: Obtener el código para mostrar los tweets

Como dije antes, en este tutorial usaremos el widget oficial de Twitter. Lo primero que debemos hacer es ir al sitio de recursos de Twitter y obtener el código javascript. En mi caso, el código es el siguiente:

<script src="http://widgets.twimg.com/j/2/widget.js"></script>
<script>
new TWTR.Widget({
  version: 2,
  type: 'profile',
  rpp: 4,
  interval: 6000,
  width: 250,
  height: 300,
  theme: {
    shell: {
      background: '#333333',
      color: '#ffffff'
    },
    tweets: {
      background: '#000000',
      color: '#ffffff',
      links: '#4aed05'
    }
  },
  features: {
    scrollbar: false,
    loop: false,
    live: false,
    hashtags: true,
    timestamp: true,
    avatars: false,
    behavior: 'all'
  }
}).render().setUser('santiagodi').start();
</script>

Ahora que ya tenemos esto, vamos a crear el widget... en el siguiente paso.

Paso 2: Crear la base del widget

Los widgets pueden ser incluidos en un plugin o directamente en un theme. En este tutorial nosotros crearemos un plugin, ya que este método tiene varias ventajas (La mas importante: usar el widget sin importar el theme activo).

Creemos un archivo con el nombre ultimos_tweets.php y ubiquemoslo en la carpeta wp-content/plugins. Lo primero que debemos hacer después de creado el archivo es agregar los datos del plugin (Como pueden ser nombre, version, etc). Así que editemos el archivo y peguemos el siguiente contenido:

<?php
/*
Plugin Name: Ultimos Tweets
Plugin URI: http://teleportz.com.ar
Description: Muestra los ultimos tweets de tu cuenta.
Version: 1.0
Author: Santiago Dimattia
Author URI: http://teleportz.com.ar
License: MIT
*/

Prueben a entrar al panel de adminisración de WordPress y podrán ver su nuevo plugin, como en la siguiente imágen.

Widget: Ultimos Tweets #1

Ahora que ya tenemos el plugin listo, debemos agregar la base de nuestro widget. Al final del archivo, agreguen lo siguiente:

/**
 * Creamos el widget
 *
 */
class WP_Widget_Ultimos_Tweets extends WP_Widget {

	function __construct()
	{
		$opciones = array(
			'classname'     => 'widget_ultimos_tweets',
			'description'   => 'Muestra los ultimos tweet de tu cuenta'
		);
		parent::__construct('ultimos_tweets', 'Ultimos Tweets', $opciones);
	}

	function widget($args, $instance)
	{
		
	}

	function update($new_instance, $old_instance)
	{
		
	}

	function form($instance)
	{
		
	}

}

/**
 * Registramos el widget (Si no lo hacemos, WordPress no podrá detectarlo)
 * 
 */
function widget_register_ultimos_tweets()
{
	register_widget('WP_Widget_Ultimos_Tweets');
}
add_action('widgets_init', 'widget_register_ultimos_tweets');

Les dejo la explicación del código:

  • __construct: Esta función define la información del widget.
    • classname: La clase CSS que se le aplicará al widget.
    • description: La descripción del widget.
    • Primer parámetro ("ultimos_tweets"): ID único para identificar el widget.
    • Segundo parámetro ("Ultimos Tweets"): El nombre del widget.
    • Tercer parámetro ("$opciones"): Array con las opciones que definimos mas arriba (classname y description).
  • widget(): Esta función es la que muestra el widget en nuestro blog
    • $args: Array conteniendo el HTML necesario para mostrar el widget, definidas por el theme activo. Variables disponibles:
      • name: Nombre de la sidebar en la cual se encuentra agregado el widget.
      • id: ID de la sidebar.
      • description: Descrición de la sidebar.
      • before_widget y after_widget: Código HTML para rodear el widget.
      • before_title y after_title: Código HTML para rodear el título del widget.
      • widget_name: El nombre del widget.
      • widget_id: El ID del widget.
    • $instance: Array con las opciones del widget.
  • update(): Esta función es la que filtrará y actualizará las configuraciones del widget definidas en la función form().
    • $new_instance: Array con las nuevas opciones del widget.
    • $old_instance: Array con las opciones actuales del widget.
  • form(): Esta función mostrará el formulario con las opciones del widget
    • $instance: Array con las opciones actuales del widget.

Ya teniendo la base del widget, deberemos rellenar las funciones... pero eso lo dejamos para el siguiente paso.

Paso 3: Mostrar el formulario con las opciones

Para hacer el código mas corto, solo agregaremos tres opciones: Título, usuario de twitter y un checkbox para saber si mostrar la fecha o no. Reemplazen la función form() por la siguiente:

function form($instance)
{
	// Obligamos a $instance a ser un array con todas las opciones disponibles
	$instance = wp_parse_args( (array) $instance, array(
					'titulo'           => 'Ultimos Tweets',
					'cuenta_twitter'   => 'teleportzblog',
					'mostrar_fecha'    => '1',
	));
	
	// Filtramos los valores para que se muestren correctamente en los formularios
	$instance['titulo'] = esc_attr($instance['titulo']);
	$instance['cuenta_twitter'] = esc_attr($instance['cuenta_twitter']);
	$instance['mostrar_fecha'] = (int) $instance['mostrar_fecha'];
	
	// Mostramos el formulario
	?>
	
	<p>
		<label for="<?php echo $this->get_field_id('titulo'); ?>">Título:</label></p>
		<input value="<?php echo $instance['titulo']; ?>" class="widefat" type="text" id="<?php echo $this->get_field_id('titulo'); ?>" name="<?php echo $this->get_field_name('titulo'); ?>">
	</p>
	
	<p>
		<label for="<?php echo $this->get_field_id('cuenta_twitter'); ?>">Cuenta de Twitter (sin @):</label></p>
		<input value="<?php echo $instance['cuenta_twitter']; ?>" class="widefat" type="text" id="<?php echo $this->get_field_id('cuenta_twitter'); ?>" name="<?php echo $this->get_field_name('cuenta_twitter'); ?>">
	</p>
	
	<p>
		<label for="<?php echo $this->get_field_id('mostrar_fecha'); ?>">Mostrar fecha?:</label></p>
		<input type="checkbox" <?php if($instance['mostrar_fecha']) { echo 'checked="checked"'; } ?> value="1" id="<?php echo $this->get_field_id('mostrar_fecha'); ?>" name="<?php echo $this->get_field_name('mostrar_fecha'); ?>">
	</p>
	
	<?php
}

Lo primero que hace la funcion es obligar a $instance a tener definidas todas las opciones, y en el caso de que alguna no se encuentre definida, mostrar una por defecto. Luego de eso, filtramos las variables para no tener errores cuando sean mostradsa en los campos de texto.
Y ya al final, mostramos los campos de texto. Resultado:

Widget: Ultimos Tweets #2

Paso 4: Actualizando las opciones...

Ya que tenemos la primera función lista, seguiremos por la segunda: update(). Actualizemos dicha funcion por lo siguiente:

function update($new_instance, $old_instance)
{
	return array(
		'titulo'          => strip_tags($new_instance['titulo']),
		'cuenta_twitter'  => strip_tags($new_instance['cuenta_twitter']),
		'mostrar_fecha'   => (int) $new_instance['mostrar_fecha'],
	);
}

Lo único que necesita hacer esta función es returnear las opciones del widget ya filtradas, para evitar problemas de seguridad.
Prueben a agregar el widget al sidebar y podrán ver que la parte administrativa ya funciona perfectamente!

Paso 5: Mostrar el widget de Twitter

Y llegamos a la última función: widget()...

function widget($args, $instance)
{
	/**
	 * Hacemos un extract para que los valores de los arrays esten disponibles
	 * como variables.
	 *
	 * Ejemplo: extract(array('test' => 'aaa', 'test2' => 'bbb'))
	 * creara las variables $test y $test2 con los valores "aaa" y "bbb", respectivamente.
	 */
	extract($args);
	extract($instance);
	
	// Definimos la variable $fecha con el contenido "true" o "false"
	// según sea el valor de $mostrar_fecha
	if( (bool) $mostrar_fecha)
	{
		$fecha = 'true';
	}
	else
	{
		$fecha = 'false';
	}
	
	// Mostramos el contenedor del widget (definido por el theme)
	echo $before_widget;
	
	// Mostramos el título de la pagina, rodeado del contenedor, pero solo si el título no está vacio!
	if( ! empty($titulo))
	{
		echo $before_title.$titulo.$after_title;
	}
	
	// Mostramos el código que nos dio Twitter
?>
	
	<script src="http://widgets.twimg.com/j/2/widget.js"></script>
	<script>
		new TWTR.Widget({
			version: 2,
			type: 'profile',
			rpp: 4,
			interval: 6000,
			width: 250,
			height: 300,
			theme: {
				shell: {
					background: '#333333',
					color: '#ffffff'
				},
				tweets: {
					background: '#000000',
					color: '#ffffff',
					links: '#4aed05'
				}
			},
			features: {
				scrollbar: false,
				loop: false,
				live: false,
				hashtags: true,
				timestamp: <?php echo $fecha; ?>,
				avatars: false,
				behavior: 'all'
			}
		}).render().setUser('<?php echo $cuenta_twitter; ?>').start();
	</script>
	
<?php

	// Mostramos el contenedor del widget (definido por el theme)
	echo $after_widget;
}

No voy a explicar el funcionamiento de esta función ya que es mucho mas fácil leyendo los comentarios, pero cualquier duda, pregunten.

Terminamos!

Si entramos a nuestro blog, ya podremos ver nuestro widget en acción:

Widget: Ultimos Tweets #3

Si lo desean, pueden descargar el plugin ya armado desde este enlace

.
Mantenete al tanto...
Categorías
Twitter: @teleportzblog
Links