Agregar y Eliminar Imágenes Mediante el Cargador de Archivos de WordPress

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

En el artículo anterior de esta serie, comenzamos a trabajar con la última versión del Cargador de Archivos de WordPress para adquirir una mejor comprensión del mismo e incorporarlo a nuestros proyectos.

La parte más difícil del trabajo con esta nueva característica (bueno, nueva desde 3.5) se debe a que no está tan documentada como otras. Esto obviamente deja a muchos desarrolladores - especialmente a los principiantes - rompiéndose la cabeza al comenzar a trabajar con él. Añade a esto la completa transformación del sistema que lo sustenta, el resultado es mucho que clarificar.

Basándome en vuestros comentarios a propósito del primer artículo, vamos a extender el enfoque de esta serie un poco más. En este artículo, vamos a ver una aplicación práctica de la funcionalidad que introdujimos en el artículo anterior. Después, en el artículo próximo (o quizá próximos) veremos algunos detalles sobre la forma en que funciona el Cargador de Archivos.

Volviendo A Donde Lo Dejamos

En el último artículo, empezamos trabajando con un plugin que introducía una "Imagen de Pie Destacada" al final de cada entrada, en el caso de que se hubiese seleccionado una. Esta meta box está disponible tanto para los tipos de post para las entradas como para las páginas.

Hasta este momento, hemos añadido con éxito el meta box, iniciado el Cargador de Archivos de WordPress y seleccionado una imagen que usaremos como destacada, pero no hemos hecho nada con la información que nos proporciona el Cargador de Archivos.

En este artículo, continuaremos implementando la funcionalidad de forma que las imágenes destacadas se sitúen al final de nuestras entradas. Luego, volveremos nuestra atención sobre algunos detalles técnicos de las APIs que tenemos a nuestra disposición.

Para seguir adecuadamente donde lo dejamos, necesitamos replicar la funcionalidad que nos ofrece la meta box de la "Imagen Destacada" estándar. Para lograrlo:

Tenemos que capturar información desde el Cargador de Archivos
Mostrar la imagen que ha sido seleccionada
Ajustar adecuadamente el tamaño de la imagen
Crear una opción para poder eliminar la imagen

Ciertamente, tenemos trabajo por delante esperándonos.

Antes de tocar nada, asegúrate de actualizar la función renderMediaUploader para que acepte el parámetro $ de manera que podamos emplear jQuery en nuestros ejemplos.

La declaración de la función se vería así:

1	function renderMediaUploader( $ ) { ... }

Y la invocación de la función ahora debe ser así:

1	renderMediaUploader( $ );

Ahora sí, seguimos.

1. Capturar la Imagen

Una vez hayas seleccionado una imagen desde el Cargador, recibirás los datos en JavaScript. Específicamente, la información nos será devuelta en JSON. Esto nos permitirá analizar varias propiedades de la imagen y con ello podremos mostrarla y guardarla junto con nuestro post.

Pero antes, vamos a actualizar nuestro código. Encuentra la línea de código en admin.js igual a lo siguiente:

file_frame.on( 'insert', function() {
 
    /**
     * We'll cover this in the next version.
     */
 
});

Y reemplázalo con esto:

file_frame.on( 'insert', function() {

    // Read the JSON data returned from the Media Uploader
    json = file_frame.state().get( 'selection' ).first().toJSON();

});

Obviamente, esto no es nada terriblemente complicado; pero, recuerda añadir json como variable definida al principio del archivo junto con file_frame e image_data.

Si tienes curiosidad por saber lo que nos devuelve, eres libre de volcar los contenidos de json en tu consola de depuración favorita. No haremos esto en este artículo en particular, pero quizá veamos algo más en uno futuro, artículos en profundidad.

2. Mostrar la Imagen Seleccionada

Para que podamos mostrar la imagen seleccionada, necesitamos cerciorarnos de que tenemos un elemento de imagen en nuestra meta box que es accesible vía JavaScript para que podamos actualizar sus atributos en cualquier momento en el que la imagen sea seleccionada.

Añadamos el siguiente código en views/admin.php. Esto contiene el elemento de imagen vacío que usaremos para mostrarla.

<p class="hide-if-no-js">
    <a title="Set Footer Image" href="javascript:;" id="set-footer-thumbnail">Set featured image</a>
</p>

<div id="featured-footer-image-container" class="hidden">
    <img src="" alt="" title="" />
</div><!-- #featured-footer-image-container -->

Fíjate en que estamos aprovechando la clase CSS de WordPress hidden para ocultar el contenedor. Usando JavaScript, eliminaremos esta clase para poder mostrar la imagen ( y básicamente lo opuesto para ocultarla y sustituirla por un ancla que sirva para seleccionar de nuevo una imagen).

Ahora, podemos revisitar el JavaScript y mostrar la imagen en cualquier momento que la seleccionemos. Tenemos que hacer dos cosas:

Ocultar el ancla para permitir que el usuario seleccione la imagen
Mostrar la imagen destacada dentro de contenedor

Para conseguirlo, volvamos al código JavaScript que vimos antes en el artículo. Tras recuperar los datos desde JSON, vamos a confirmar que disponemos de una URL de imagen para después proceder.

file_frame.on( 'insert', function() {

    // Read the JSON data returned from the Media Uploader
    json = file_frame.state().get( 'selection' ).first().toJSON();

  // First, make sure that we have the URL of an image to display
	if ( 0 > $.trim( json.url.length ) ) {
		return;
	}

	// After that, set the properties of the image and display it
	$( '#featured-footer-image-container' )
		.children( 'img' )
			.attr( 'src', json.url )
			.attr( 'alt', json.caption )
			.attr( 'title', json.title )
                        .show()
		.parent()
		.removeClass( 'hidden' );

	// Next, hide the anchor responsible for allowing the user to select an image
	$( '#featured-footer-image-container' )
		.prev()
		.hide();

});

El código tiene comentarios que explican claramente lo que está sucediendo, no obstante, lo que estamos haciendo es: respaldarnos con jQuery para confirmar que estamos mostrando y ocultando elementos adecuadamente.

Primero, estamos revisando la propiedad URL de json , comprobando que su longitud es superior a 0. Me gustaría usar $.trim y transformar así ésto en una práctica de código defensivo. Si es igual a cero, entonces volveremos ya que significa que no disponemos de imagen para mostrar.

Después de esto, aprovecharemos el nuevo elemento div que hemos creado en el paso anterior. Cogemos el elemento de imagen a través de la función children() y luego establecemos sus atributos src, alt y title basándonos en las propiedades accesibles a través del objeto json.

A partir de aquí, seleccionamos el contenedor padre de la imagen y eliminamos la clase hidden.

En definitiva, usamos el elemento featured-footer-image-container como punto desde el cual tenemos acceso al ancla - en este caso, se trata del elemento previo - y tras esto lo ocultamos.

Ahora, la imagen debería aparecer en el meta box de la entrada.

Pero tenemos un problema evidente: la imagen es demasiado grande para su contenedor. Esto quiere decir que necesitamos introducir un poco de CSS.

3. Aplicar Estilo a Nuestra Imágen Destacada

Para hacer esto, vamos a necesitar añadir un archivo CSS y actualizar el archivo principal del plugin de forma que ponga en cola la hoja de estilo.

Primero, crea un directorio css en tu carpeta de plugins, después añade admin.css al directorio. En este archivo añade el siguiente código:

#featured-footer-image-container img {

    width:  100%;
    height: auto;

}

Luego añade el siguiente hook en la función run() de tu plugin:

1	add_action( 'admin_enqueue_scripts', array( $this, 'enqueue_styles' ) );

Finalmente, añade la siguiente función:

/**
 * Registers the stylesheets for handling the meta box
 *
 * @since 0.2.0
 */
public function enqueue_styles() {

    wp_enqueue_style(
        $this->name,
        plugin_dir_url( __FILE__ ) . 'css/admin.css',
        array()
    );

}

Al ajustar adecuadamente tus selectores, registrado y vinculado tu hoja de estilo, deberías ser capaz de ver algo como esto:

Mucho mejor, ¿no?

4. ¿Cómo Eliminamos la Imagen?

De la misma forma que añadimos un elemento para mostrar la imagen, necesitamos añadir un elemento que nos permita también eliminarla.

Para hacer esto, volvemos a views/admin.php y añadimos el siguiente código:

1	<p class="hide-if-no-js hidden">
2	<a title="Remove Footer Image" href="javascript:;" id="remove-footer-thumbnail">Remove featured image</a>
3	</p><!-- .hide-if-no-js -->

Luego, necesitamos escribir algo de JavaScript adicional para que cuando la imagen sea visible, el ancla anterior muestre. Para conseguirlo, vamos a admin.js y agregamos lo siguiente bajo el código que añadimos con anterioridad.

1	// Display the anchor for the removing the featured image
2	$( '#featured-footer-image-container' )
3	.next()
4	.show();

Y de igual forma a como hicimos con el ancla inicial, necesitamos ajustar un controlador de eventos de forma que cuando el ancla "remove" sea pulsada, la imagen sea eliminada y en su lugar se restaure el enlace "Establecer Imagen Destacada".

Para hacer esto, primero revisitamos la función que se dispara tan pronto como el DOM se carga y añadimos el siguiente código:

$( '#remove-footer-thumbnail' ).on( 'click', function( evt ) {
    
	// Stop the anchor's default behavior
	evt.preventDefault();

	// Remove the image, toggle the anchors
	resetUploadForm( $ );
    
});

Ahora tenemos que definir la función resetUploadForm, así que vamos. Recuerda que para esto hace falta eliminar la imagen, ocultar el contenedor de "eliminar enlace", y restaurar el ancla para el enlace "elegir imagen".

/**
 * Callback function for the 'click' event of the 'Remove Footer Image'
 * anchor in its meta box.
 *
 * Resets the meta box by hiding the image and by hiding the 'Remove
 * Footer Image' container.
 *
 * @param    object    $    A reference to the jQuery object
 * @since    0.2.0
 */
function resetUploadForm( $ ) {
    'use strict';

	// First, we'll hide the image
	$( '#featured-footer-image-container' )
		.children( 'img' )
		.hide();

	// Then display the previous container
	$( '#featured-footer-image-container' )
		.prev()
		.show();

	// Finally, we add the 'hidden' class back to this anchor's parent
	$( '#featured-footer-image-container' )
		.next()
		.hide()
		.addClass( 'hidden' );

}

Hasta aquí, tenemos todo lo que necesitamos para seleccionar una imagen y eliminarla repetidamente.

Pero todavía queda trabajo por hacer, eso lo veremos en el próximo capítulo. Mientras, no olvides visitar el repositorio asociado en GitHub para obtener la versión actual del código fuente de este proyecto.

Proximamente

Es cierto que ya nos hemos ocupado de la mayor parte del trabajo de back-end en lo relativo a la selección de la imagen, su muestra y eliminación, pero todavía nos falta una pieza de la funcionalidad que es crucial: guardar la imagen de forma que se mantenga asociada al post.

Para conectar lo que el usuario ve con lo que hemos especificado en el back-end, necesitamos trabajar un poco para guardar los datos JSON en la base de datos, organizarlos, y mostrarlos en el diseño.

En los próximos artículo de esta serie, veremos como hacer esto exactamente. Mientras, puedes dejar tus sugerencias o dudas en el canal de comentarios inferior.