Cómo Usar WordPress Media Uploader

Desde la versión 3.5 de WordPress se incluye un nuevo Media Uploader para poder agregar archivos e imágenes a la biblioteca. Se trata de un gestor de archivos creado con Backbone.js, una librería de JavaScript para desarrollar aplicaciones web dinámicas.

Al igual que ocurre con cualquier cosa relativamente nueva, nos enfrentamos a la escasa documentación que puede haber a la hora de ponernos manos a la obra, por lo que necesitamos cierta investigación.

Como desarrolladores, vamos a ver cómo usar WordPress Media Uploader en nuestro plugin, en nuestro tema, en nuestro widget o en cualquier plantilla o página de WordPress. Así, podremos subir imágenes a la biblioteca o seleccionarlas para usarlas en donde queramos.

Incluir el Media Uploader de WordPress de un modo sencillo

El código que veréis a continuación podéis copiarlo y pegarlo directamente, pero es muy recomendable leer la siguiente explicación acerca de lo que estamos haciendo.

Necesitamos seguir una serie de pasos:

1. Tenemos que incluir Media Uploader para mostrarlo cuando sea necesario.
2. Debemos definir una instancia de nuestra referencia a Media Uploader, que será frame_uploader, y si ésta ya ha sido definida, tenemos que abrirla.
3. Seguidamente tenemos que obtener los datos de la imagen que el usuario seleccione, que en este caso serán mostrados por la consola.
4. Finalmente, definimos cuándo abrir Media Uploader, que en este caso es al hacer click en el elemento MIELEMENTO.

El código es sencillo y está muy comentado, así que no necesita mucha explicación.

(function( $ ) {
 'use strict';

 /** Definimos las variables para la ventana de Media Uploader y para obtener los datos de la imagen seleccionada */
 var frame_uploader, datos_imagen;

 $(function() {

 /** Si ya existe una instancia de frame_uploader, la abrimos en lugar de crear una nueva instancia. */

 if ( undefined !== frame_uploader ) {
 frame_uploader.open();
 return;
 }

 /**
 * Si no existe la instancia, debemos crearla.
 * Aquí usamos la librería wp.media para definir las opciones del Media Uploader.
 * Necesitamos establecer el título y el texto del botón de aceptar.
 * En este caso solamente permitiremos que el usuario seleccione una imagen.
 */

 frame_uploader = wp.media.frames.frame_uploader = wp.media({
 title: "Insert Media",
 button: {
 text: "Aceptar"
 },
 multiple: false
 });

 /**
 * Aquí definimos las acciones a realizar cuando la imagen se selecciona
 * En 'datos_imagen', obtenemos los datos de la imagen en formato JSON
 */
 frame_uploader.on( 'select', function() {

 datos_imagen = frame_uploader.state().get( 'selection' ).first().toJSON();

 /**
 * Ya podemos acceder a todas las propiedades de la imagen que están en la variable 'datos_imagen'
 * Debemos usar los datos para lo que queramos realizar.
 *
 * A modo de ejemplo, vamos a mostrar todas las propiedades por la consola.
 */

 for ( var propiedades_imagen in datos_imagen ) {

 console.log( propiedades_imagen + ': ' + datos_imagen[ propiedades_imagen ] );

 }
 /**
 * Algo que podéis si usaís Media Uploader en un plugin es mostrar la imagen en un div,
 * mostrar la URL de la imagen en un campo INPUT o ambas.
 */
 });

 /**
 * Vamos a abrir Media Uploader cuando hacemos click en un elemento.
 * Es IMPRESCINDIBLE que reemplacéis el ID del div 'MIELEMENTO' por el del botón o elemento HTML
 * que se usará para abrir Media Uploader.
 */

 $("#MIELEMENTO").click(function() {
 frame_uploader.open();
 });

 });

})( jQuery );

Si queréis, también podéis incluir el script anterior en un archivo js separado del resto del código.

Incluyendo los Scripts adicionales necesarios

Para que Media Uploader funcione desde el escritorio de WordPress tenemos que agregar también los siguientes scripts mediante PHP en la página que incluyamos el código JavaScript anterior.

wp_enqueue_media();

Se trata de una implementación muy básica pero que funciona. Es posible insertar galerías y múltiples imágenes, pero puede que veamos éso más adelante.

El código ha sido probado con las versiones de WordPress más recientes, pero si no os funciona o tenéis algún problema, no dudéis en comentarlo aquí.

---