Crear un complemento de presentación de diapositivas para WordPress

() translation by (you can also view the original English article)

La integración de la funcionalidad de presentación de diapositivas en WordPress es una característica muy necesaria para casi cualquier tema, pero ¿qué tan difícil es incluir y cuán flexible es? En este tutorial vamos a, de diferentes maneras, incluir una de las presentaciones de diapositivas de jQuery más populares y usadas, Nivo Slider.

En realidad, ya existe un complemento codificado de WordPress para el Nivo Slider, justo en la página oficial de Nivo Slider. Pero de todos modos vamos a construir uno en este tutorial, y definitivamente lo haremos de manera diferente. En este tutorial vamos a crear un complemento de control deslizante de Nivo que tendrá funcionalidad de widget, funcionalidad de código corto e incluso podrás integrarlo como una simple función de llamada y codificarlo en tu tema donde lo desee el usuario.

Al seguir este tutorial, se implica que está ejecutando un servidor Apache y MySQL local o remotamente para poder instalar WordPress. Además, que tienes instalada una versión 3.1+ de WordPress, que tienes acceso a su sistema de archivos y que tienes conocimientos básicos de PHP, CSS, JavaScript y HTML.

Paso 1 Creando el Plugin

Una de las partes más fáciles de este tutorial. Vamos a crear una carpeta llamada nivoplugin dentro del directorio wp-content / plugins dentro de su instalación de WordPress. Dentro de ese directorio crearemos un archivo nivoplugin.php con el siguiente código:

<?php
/*
  Plugin Name: Nivo Plugin
	Description: Simple implementation of a nivo slideshow into WordPress
	Author: Ciprian Turcu
	Version: 1.0
*/
?>

Esta es la información básica del complemento que usa WordPress para identificar el nombre y los detalles del complemento. Cosas como Plugin Name, Description, Author y versión del Plugin son parámetros obligatorios que se agregan como texto comentado en la parte superior de cada complemento para que WordPress pueda identificar el complemento, administrarlo, ejecutarlo y mostrar la información requerida al respecto en la página de complementos. .

"Para obtener más información sobre el texto del encabezado del complemento y otras opciones que se le pueden agregar, lea Cómo escribir un complemento en el Códice de WordPress".

Paso 2 Creando la Funcionalidad de Administración de Presentación de diapositivas

La presentación de diapositivas está hecha de imágenes, por lo que para realizar una implementación sencilla del jQuery Nivo Slider necesitamos una forma de agregar y administrar imágenes en el panel de administración. Nuestro enfoque hará un buen uso de la funcionalidad de WordPress de tipo de publicación personalizada. Los tipos de publicaciones personalizadas se utilizarán para crear una nueva página personalizada donde cada publicación contenga todos los detalles de imagen requeridos: el nombre y, por supuesto, la parte más importante, la imagen en sí. Vamos a utilizar el título y el editor para la información de nombre y descripción y la funcionalidad de imagen destacada para cargar la imagen, gestionarla e identificarla.

function np_init() {
	$args = array(
		'public' => true,
		'label' => 'Nivo Images',
		'supports' => array(
			'title',
			'thumbnail'
		)
	);
	register_post_type('np_images', $args);
}
add_action('init', 'np_init');

En el ejemplo anterior, estamos agregando un enlace a la función np_init utilizando la etiqueta de enlace de inicio que se ejecutará antes de que se ejecuten los encabezados. Necesitamos hacer esto para poder incluir dentro de la función register_post_type con sus parámetros. Esta función es la función que se usa para agregar y administrar un nuevo tipo de publicación personalizada. Básicamente, incluimos un nuevo tipo de publicación personalizada llamada np_images con algunos argumentos.

Los argumentos son una matriz de valores que representan la configuración de ese nuevo tipo de publicación personalizada. Cosas como si está destinado a ser usado públicamente, lo configuramos como verdadero, le damos una etiqueta con el nombre Nivo Images y establecemos el hecho de que cada publicación tiene un título y una imagen destacada con el title y la thumbnail de las variables como una La matriz al atributo principal supports.

Esto crea el tipo de publicación personalizada y se ve así:

En este punto, tenemos un tipo de publicación personalizado registrado y en funcionamiento con el nombre de np_images. Podemos agregar nuevas publicaciones, eliminarlas y editarlas como con publicaciones regulares, pero hechas a medida para nuestro propósito de administrar imágenes para la presentación de diapositivas. Básicamente, este es el lugar donde agregamos imágenes para la presentación de diapositivas de Nivo como publicaciones.

Paso 3 Incluyendo los scripts y estilos de Nivo Slider

Esto puede sonar como algo ligeramente complicado o consumir más tiempo de lo habitual. No lo es. Vamos a descargar la versión gratuita jQuery de Nivo Slider e incluiremos los scripts y estilos necesarios para que luego podamos usarlos con algunos códigos e imágenes personalizados.

Para descargar las fuentes, vamos a la página de Precios en nivo.dev7studios.com y hacemos clic en el botón Descargar jQuery Plugin (versión gratuita) a la izquierda para descargar las fuentes.

Para los propósitos de este tutorial, vamos a mantener las cosas muy simples. Descomprimimos el archivo e incluimos todo el directorio dentro de nuestro directorio de complementos. Dentro de la carpeta nivo-slider tenemos otra carpeta llamada demo. Vamos a eliminarlo ya que no tenemos ningún uso y no queremos un complemento desordenado con cosas innecesarias en él.

Registro e inclusión de scripts y estilos

La siguiente parte de este paso es incluir los archivos necesarios de Nivo Slider. En nuestro archivo nivoplugin.php agregaremos lo siguiente:

1	add_action('wp_print_scripts', 'np_register_scripts');
2	add_action('wp_print_styles', 'np_register_styles');

Esto se enganchará a algunas funciones (el segundo parámetro es el nombre de la función). Necesitamos estos ganchos para incluir correctamente los scripts y los estilos en el front-end. Echemos un vistazo a las funciones de devolución de llamada de nuestros ganchos anteriores.

function np_register_scripts() {
	if (!is_admin()) {
		// register
		wp_register_script('np_nivo-script', plugins_url('nivo-slider/jquery.nivo.slider.js', __FILE__), array( 'jquery' ));
		wp_register_script('np_script', plugins_url('script.js', __FILE__));

		// enqueue
		wp_enqueue_script('np_nivo-script');
		wp_enqueue_script('np_script');
	}
}

function np_register_styles() {
	// register
	wp_register_style('np_styles', plugins_url('nivo-slider/nivo-slider.css', __FILE__));
	wp_register_style('np_styles_theme', plugins_url('nivo-slider/themes/default/default.css', __FILE__));

	// enqueue
	wp_enqueue_style('np_styles');
	wp_enqueue_style('np_styles_theme');
}

La función de devolución de llamada de script registra e incluye 3 archivos javascript importantes: jQuery (como una dependencia de Nivo Slider), archivo base nivo-slider (jquery.nivo.slider.js) y nuestro archivo de script personalizado (script.js). Nivo Slider requiere jQuery para funcionar y necesitamos un script personalizado para activarlo.

El archivo script.js:

1	jQuery(document).ready(function($) {
2	$('#slider').nivoSlider();
3	});

El script es bastante simple, requiere jQuery para adjuntar la función nivoSlider a la etiqueta con el id del control slider. Esa etiqueta tomará las propiedades y funcionalidad de nivo-slider.

Por último, en nuestro paso anterior, la función de devolución de llamada de estilo registra e incluye 2 archivos más importantes: el archivo nivo-slider.css que tiene todos los estilos necesarios para que el control deslizante se vea y funcione en consecuencia, y un archivo default.css dentro de los temas / carpeta predeterminada que usamos para crear un tema de la presentación de diapositivas con el tema predeterminado nivo-slider.

Paso 4 Nuevos tamaños de imagen

Como se mencionó al principio, este tutorial cubrirá la implementación de un widget, un shortcode y una función para codificar el control deslizante si es necesario mediante el uso del complemento que estamos creando. Para el código corto y la función necesitamos prácticamente los mismos tamaños de imagen y para el widget un tamaño más pequeño para la altura y el ancho de las imágenes.

Primero, debemos tener en cuenta el hecho de que estamos utilizando imágenes destacadas en publicaciones personalizadas para nuestras presentaciones de diapositivas. Entonces, ¿cómo redimensionamos y recortamos esas imágenes para adaptarlas a nuestras necesidades? Vamos a agregar nuevos tamaños de imagen que WordPress cambiará de tamaño y recortará en cada nueva carga de imagen. Para agregar los nuevos tamaños de imagen, usaremos la función add_image_size agregando el siguiente código dentro de la función np_init:

1	add_image_size('np_widget', 180, 100, true);
2	add_image_size('np_function', 600, 280, true);

En el código fuente anterior implementamos 2 tamaños de imagen a los que llamaremos más adelante utilizando los nombres np_widget para widget y np_function para shortcode y la función PHP para identificarlos.

Una cosa más

Para habilitar las miniaturas posteriores en el complemento, se debe agregar la siguiente línea de código en nuestro complemento. Vamos a agregarlo por encima de las líneas add_action.

1	add_theme_support( 'post-thumbnails' );

"Los tamaños de imagen agregados con add_image_size solo funcionarán para las nuevas imágenes que se carguen después de que se active la función".

Paso 5 La función PHP

Una de las características principales del complemento es una función de PHP que puede utilizar en cualquier parte del código de su tema para insertar la gran presentación de diapositivas de 600x280 Nivo.

Debido a que estamos utilizando publicaciones personalizadas para administrar nuestras imágenes para la presentación de diapositivas, debemos consultar esas publicaciones y obtener los títulos e imágenes del tipo de publicación personalizada. Para eso vamos a utilizar un nuevo bucle WP_Query con los parámetros de la variable $ args que selecciona el tipo de publicación personalizada y crea una presentación de diapositivas con un máximo de 5 imágenes a partir de la consulta. A continuación, creamos una variable $result que tiene todo el código HTML necesario para la presentación de diapositivas de Nivo. Estamos utilizando las envolturas de código HTML de demostración de nuestra carpeta de descarga de scripts de Nivo.

function np_function($type='np_function') {
	$args = array(
		'post_type' => 'np_images',
		'posts_per_page' => 5
	);
	$result = '<div class="slider-wrapper theme-default">';
	$result .= '<div id="slider" class="nivoSlider">';

	//the loop
	$loop = new WP_Query($args);
	while ($loop->have_posts()) {
		$loop->the_post();

		$the_url = wp_get_attachment_image_src(get_post_thumbnail_id($post->ID), $type);
		$result .='<img title="'.get_the_title().'" src="' . $the_url[0] . '" data-thumb="' . $the_url[0] . '" alt=""/>';
	}
	$result .= '</div>';
	$result .='<div id = "htmlcaption" class = "nivo-html-caption">';
	$result .='<strong>This</strong> is an example of a <em>HTML</em> caption with <a href = "#">a link</a>.';
	$result .='</div>';
	$result .='</div>';
	return $result;
}

Dentro del bucle, estamos usando la función wp_get_attachment_image_src para recuperar la imagen destacada de nuestra publicación personalizada. Usamos el valor np_function para el tamaño de la imagen que agregamos anteriormente en np_init. Debido a que estamos dentro del bucle, podemos usar $ post-> ID para identificar la publicación. La función tiene un parámetro, $ type, que se usa para establecer el tamaño de las imágenes desde wp_get_attachment_image_src con uno de los tamaños de imagen establecidos previamente. La variable tiene el valor predeterminado de np_function. Si no se proporciona ningún parámetro al llamar a la función, la variable predeterminada se activará.

Los títulos de las publicaciones se agregan como valores al parámetro HTML del título de la etiqueta de imagen y se pueden ver en la parte inferior de la presentación de diapositivas de la imagen como texto flotante sobre las imágenes dentro de un fondo oscuro transparente.

El control deslizante se redimensiona automáticamente como el tamaño de la imagen en su interior, por lo que, independientemente del tamaño de imagen que usemos, tendremos una presentación de diapositivas de ese tamaño.

La presentación de diapositivas en el tamaño de np_function se ve así:

Esta vista previa de la presentación de diapositivas es la implementación de shortcode que se tratará a continuación.

Paso 6 El código corto

Otra característica principal es la implementación de shortcode. Esto es realmente muy fácil de implementar y se puede hacer con una línea de código. Simplemente agregue esta línea en la función np_init sobre todo lo que está allí:

1	add_shortcode('np-shortcode', 'np_function');

El gancho de shortcode realmente utilizará nuestra función PHP para devolver el contenido de la presentación de diapositivas. Eso es todo, muy simple y rápida implementación del shortcode. Para usarlo, solo agregue [np-shortcode] en el contenido de cualquier publicación o página. Ese texto será reemplazado con la presentación de diapositivas real.

Paso 7 Construyendo el Widget

En este paso, vamos a construir un widget simple que tendrá el único propósito de mostrar una pequeña presentación de diapositivas en la barra lateral donde sea que se coloque.

Ya tenemos el tamaño establecido para ello en el paso 4 y tenemos todas las demás funciones que incluyen y generan la presentación de diapositivas de Nivo que podemos utilizar para integrar en el widget. Así que todo lo que queda ahora es construir el widget e integrar el código anterior.

function np_widgets_init() {
	register_widget('np_Widget');
}

add_action('widgets_init', 'np_widgets_init');

En esta primera parte vamos a implementar un nuevo gancho que debe agregar entre los demás. Este gancho usa la etiqueta widgets_init y usa una función que vamos a llamar np_widgets_init. Esta función se ejecuta cuando se crean los widgets. Como resultado, vamos a registrar el widget con el nombre de np_Widget como se muestra en el ejemplo anterior.

La clase

Para crear un nuevo widget, estamos implementando una nueva clase llamada np_Widget que extiende la clase WP_Widget. Como primera función, el __construct es la función principal y más importante de la clase y de nuestra funcionalidad de widget. La función tiene parámetros que usamos para darle al widget una ID única que en nuestro caso se llama np_widget, un nombre, Nivo Slideshow e incluso una descripción, como lo muestra el siguiente código:

class np_Widget extends WP_Widget {

	public function __construct() {
		parent::__construct('np_Widget', 'Nivo Slideshow', array('description' => __('A Nivo Slideshow Widget', 'text_domain')));
	}
}

Por supuesto, esto es solo el comienzo de nuestro widget, hay algunas otras funciones que necesitamos implementar y configurar a medida que las necesitamos para que funcionen.

Backend Widget

El widget se ve como cualquier otro widget en el back-end. Necesitamos darle al widget un título que tenga la posibilidad de ser ingresado por el usuario y luego guardado por el complemento. Para hacer esto, necesitamos escribir la función form extendida desde la clase WP_Widget. En esta función, vamos a utilizar el parámetro $ instance que proporciona la función para obtener el title, que es una variable que luego se implementará, guardará y actualizará. Entonces creamos el elemento de entrada de formulario usando el siguiente código:

	public function form($instance) {
		if (isset($instance['title'])) {
			$title = $instance['title'];
		}
		else {
			$title = __('Widget Slideshow', 'text_domain');
		}
		?>
			<p>
				<label for="<?php echo $this->get_field_id('title'); ?>"><?php _e('Title:'); ?></label>
				<input class="widefat" id="<?php echo $this->get_field_id('title'); ?>" name="<?php echo $this->get_field_name('title'); ?>" type="text" value="<?php echo esc_attr($title); ?>" />
			</p>
		<?php
	}

Este código solo se ejecuta en el back-end y es requerido por las siguientes funciones para enviar el nombre del título para guardarlo y luego usarlo en el front-end. La variable $ instance tiene el valor del título y se usa directamente como el ejemplo anterior sin ninguna otra consulta o función de llamada.

Guardando los datos

Después de enviar el formulario desde la función anterior, debe procesarse y guardarse. Esto se hace en la función de update que también necesitamos agregar a la clase con el siguiente código:

	public function update($new_instance, $old_instance) {
		$instance = array();
		$instance['title'] = strip_tags($new_instance['title']);

		return $instance;
	}

El valor del campo se pasa a través de la variable $ new_instance que se elimina de las etiquetas, se inserta en la variable $ instance para que la función pueda devolverla y guardarla con WordPress como parte de su funcionalidad de widget extendido.

Widget Front-End

Por último, pero no menos importante, otra parte muy importante y también representativa de nuestro widget es la funcionalidad de front-end. Obviamente, cada pieza es importante para que el resultado final funcione, pero esta parte es lo que ves en tu tema.

La función de widget administra el extremo delantero del widget y tiene dos parámetros: $ args y $ instance. El parámetro $ args se usa para obtener variables como $ before_widget, $ after_widget y $ before_title, $ after_title que vamos a utilizar en nuestro código implementado. La función del widget se ve así:

	public function widget($args, $instance) {
		extract($args);
		// the title
		$title = apply_filters('widget_title', $instance['title']);
		echo $before_widget;
		if (!empty($title))
			echo $before_title . $title . $after_title;
		echo np_function('np_widget');
		echo $after_widget;
	}

Para implementar la presentación de diapositivas, estamos utilizando la función np_function, pero en este caso le estamos asignando el parámetro np_widget para que obtengamos los tamaños de imagen que queremos para el widget.

Esto cubre la implementación del widget Nivo Slider en nuestro complemento. En este punto, puede ingresar al panel de administración y agregar algunas publicaciones en el menú de imágenes de Nivo y adjuntarles imágenes destacadas para que aparezcan en la presentación de diapositivas.

"Para obtener más información sobre la API de widgets de WordPress, consulte la API de widgets de Codex de WordPress".

Conclusión

Es muy fácil y rápido implementar una presentación de diapositivas en WordPress si sabe lo que está haciendo y, especialmente, si la funcionalidad de presentación de diapositivas ya está desarrollada y simplemente la está integrando. Aún así, debes tener cuidado de no usar alguna funcionalidad que ya existe y, por supuesto, es fácil si la implementas de una manera muy básica como lo hicimos, ya que un enfoque más flexible con muchas opciones y características podría complicar un poco las cosas. Dependiendo de cuales sean las características.