Como integrar valores de WordPress en plugins de JQuery

• Artículos
• Lunes, 21 de diciembre de 2015

Hoy es inevitable no aprovechar la variedad y calidad de los plugins de jQuery. Poder combinar la potencia de WordPress con cualquier plugin jQuery es fácil siempre que lo hagas de la forma correcta. En lugar de establecer valores estáticos como rutas a ficheros en los jQuery, con un poco de código es posible asignar los valores desde el conveniente panel de control del WordPress. La idea es poner a disposición de un script de jQuery valores obtenidos de la base de datos de WordPress.

Un carrusel Vegas de fotos combinado con una página de opciones ACF

El objetivo es aprovechar un conocido y potente plugin de imágenes de fondo llamado Vegas, para que el usuario pueda cargar fácilmente las imágenes a través de una página de opciones creada con el plugin Advanced Custom Fields.

Vegas permite pasar la configuración deseada a través de una función que recibe los valores deseados. En un caso normal es cuestión de pasar ese script y el plugin se encarga de cargar las imágenes en el contenedor indicado. Un script tendría una configuración tal que así:


$elmt.vegas({
delay: 7000,
timer: false,
animation: 'random',
slides: [
{ src: '/img/slide1.jpg' },
{ src: '/img/slide2.jpg' },
{ src: '/img/slide3.jpg' }
]
});


Puesto que hay valores por defecto, lo que nos interesa es obtener los orígenes de las imágenes a través de los atributos src. En lugar indicar valores estáticos la idea es poder cambiarlos desde la página de opciones en el panel de control y que el script pueda tomar las url de las imágenes que cargamos a través del gestor de medios de WordPress. Esto nos ofrece mucha flexibilidad y al mismo tiempo cualquier usuario puede modificar las imágenes con rapidez.

Paso 1. Instalar plugin Advanced Custom Fields Pro o complementos de pago

En este ejemplo utilizaré el plugin Advanced Custom Fields (ACF) pero es posible implementarlo con otras opciones. En el caso de ACF los módulos de Opciones y Repetidor son de pago, a no ser que se disponga de la versión Pro. En cualquier caso, los módulos (add-on) de pago son reutilizables en otros proyectos y sólo es necesaria la versión gratuita del ACF (absolutamente recomendable y a un precio ridículo).

Paso 2. Registrar plugin Vegas en nuestro WordPress

El siguiente paso es disponer del plugin Vegas en nuestro sitio web. Por eso hay que descargar los archivos fuentes y registrarlos adecuadamente. Para descargar Vegas es posible hacerlo descargando un .zip y descomprimiendo los archivos en una carpeta en tu tema o plugin, o con otras opciones más ordenadas como Bower (recomiendo siempre esta última). Vegas se compone básicamente de un archivo fuente js, una hoja de estilos, y un script con la personalización.

Para simplificar el tutorial, se puede introducir el código en el archivo functions.php del tema o en el que haga la misma función. Como sólo nos interesa en la página de inicio, usaremos una condición (conditional tags en WordPress Codex) para sólo cargar estos recursos en esta página.

// en functions.php
function cargar_vegas_acf_en_inicio(){

if (is_front_page()) :
 
// encolamos vegas css en la home
wp_enqueue_style( 'vegas-css',  get_template_directory_uri() .'/bower_components/vegas/dist/vegas.min.css', false,null);

// encolamos vegas js en el pie de la home
wp_enqueue_script('vegas-js', get_template_directory_uri() .'/bower_components/vegas/dist/vegas.min.js',array(),null,true);  

endif;
}

add_action('wp_enqueue_scripts','cargar_vegas_acf_en_inicio', 101);

En este punto es bueno comprobar el código fuente por si en efecto carga correctamente estos archivos en la página de inicio. Si están bien, podemos continuar. Cuidado con las rutas a los archivos que suele ser el error más común.

Nota. No pierdas de pista este archivo que más adelante lo modificaremos.

Paso 3. Crear la página de Opciones ACF

Instalar el plugin ACF y el complemento de Options Page y Repetidor, es sumamente sencillo crear los valores que necesitamos. Este tutorial asume que vamos a utilizar tres imágenes para el carrusel. Con el campo repetidor sería posible crear un numero indeterminado de imágenes, pero para ello necesitaríamos modificar el script que utiliza Vegas, adaptando el código para reflejar un valor dinámico.

Para empezar hay que crear el campo personalizado en ACF. Es crucial que indiquemos que vamos a usar una página de Opciones. En el ejemplo he creado una con el nombre Opciones ACF.

En nuestro archivo functions.php agregaremos el siguiente código (esto es opcional).

if( function_exists('acf_add_options_page') ) {
	
	acf_add_options_page(array(
		'page_title' 	=> 'Opciones',
		'menu_title'	=> 'Opciones ACF',
		'menu_slug' 	=> 'theme-general-settings',
		'capability'	=> 'edit_posts',
		'redirect'		=> false
	));
}	

Una vez creado podremos ver que al crear los campos personalizados encontraremos la opción en Localización para que se muestre en una página de Opciones ACF. Esto es accesible en el menú lateral del panel de control.

Así es cuestión de crear un campo repetidor con un mínimo de 3 imágenes (campo personalizado de imagen) como campos de segundo nivel. La idea es poder subir las imágenes sin preocuparnos de obtener el enlace a la imagen en nuestro servidor, pues este valor será facilitado al script de configuración de vegas como CDATA y por tanto accesible desde el jQuery.

Paso 4. Obtener para nuestro script Vegas los valores de ACF

Recapitulamos el archivo empezado (y no terminado) en functions.php y que nos permitirá con una función obtener los valores de las imágenes subidos al Options ACF. Es aquí donde reside lo más relevante y que permite poner a disposición del script jQuery los valores procedentes de PHP gracias a la función wp_localize_script().

// en functions.php
function cargar_vegas_acf_en_inicio(){

if (is_front_page()) :

// encolamos vegas css en la home
wp_enqueue_style( 'vegas-css',  get_template_directory_uri() . '/bower_components/vegas/dist/vegas.min.css', false,null);

// encolamos vegas js en el pie de la home
wp_enqueue_script('vegas-js', get_template_directory_uri() .'/bower_components/vegas/dist/vegas.min.js',array(),null,true);  

//encolaremos el script de configuración de vegas (la ruta cambia según cada tema) y que tendremos en la documentación de Vegas. Es el que modificaremos más tarde.

wp_enqueue_script('vegas_script', get_template_directory_uri() .'/assets/scripts/vegas_script.js',array(),null,true);

// cargamos el script de vegas con los valores de PHP que nos trae un array devuelto por la función 

$imgs_carrusel = load_vegas(); // retorna array necesario para wp_localize_script

//localizamos script con los valores obtenidos desde load_vegas();

wp_localize_script('vegas_script', 'php_vars', $imgs_carrusel );

endif;

}
add_action('wp_enqueue_scripts','cargar_vegas_acf_en_inicio', 101);

Repito que lo más importante es poder pasar (localizar es una palabra algo confusa aquí) los valores obtenidos con la función load_vegas(), que será exclusivamente los enlaces a las imágenes en nuestro sitio web.

La función wp_localize_script, admite tres variables.

• 1. Handle: Debe coincidir con el nombre del script al que queremos pasar la información.
• 2. Nombre del objeto: Es el objeto que contendrá nuestros datos y que se pasa al código de nuestra página en forma de CDATA.
• 3. Array con valores: Este array contiene los valores que hemos extraído gracias a la función load_vegas.

function load_vegas(){

// cargar valores de campos personalizados ACF Options Page
// importante pasar atributo option!!

    if( have_rows('acf_img_inicio', 'option') ): 

    $img_carrusel=array();
    $cnt = 0;
    
    while( have_rows('acf_img_inicio', 'option') ): the_row(); 


    $image = get_sub_field('acf_img_inicio_sub'); 

    // obtener url sanando salida
    $image_link = esc_html($image['url']); 

    // asignar índice y valor al array
    $img_carrusel[$cnt]=$image_link;
  $cnt++;

  endwhile; 

  return $img_carrusel;

  endif; 

}

Paso 5. Adaptación del script de configuración según los valores obtenidos

El último paso es pasar las variables en el script aprovechando que ya están disponibles en el array php_vars (los nombres de las variables son arbitrarios). Como se ha previsto, el código pasará un cantidad fija de 3 valores, que contienen el enlace a las imágenes. Hay que notar que otros valores son posibles de personalizar. Todo depende de la necesidad del proyecto.

$('body').vegas({
    slides: [
        { src: php_vars[0]},
        { src: php_vars[1]},
        { src: php_vars[2]}
  
    ],
     
     delay: 6000,
     animation: 'random',
     timer: false
});

Opcional. Adaptar el número de imágenes pasadas al script jQuery.

El ejemplo anterior implica que vamos a pasar tres imágenes al script (a través del array php_vars, lo que limita bastante las posibilidades. Es mejor contar con una solución flexible donde en función del número de imágenes subidas se adapte el script. Si nos fijamos en la función Vegas, se le pasa como argumento un objeto con diferentes propiedades. La que nos interesa es slides, que a su vez es un array que tiene la particularidad de contener la clave src con la ruta que extraemos del php_vars. Para ello habrá que recorrer de manera dinámica, en función del ancho del array php_vars y completar el array correspondiente.

Por tanto, el script podría quedar así:

// array que contendrá las rutas (src:) de las imágenes
var imagenes = [];
// recorremos el array php_vars y llenamos el array correspondiente
for (var x=0; x < php_vars.length;x++){
 var obj = {src: php_vars[x]};
 imagenes.push(obj);
}	

// creamos una variable con todas las opciones que pasamos a la función
var valores = {
transitionDuration: 4000,
delay: 5000,
slides:imagenes,		
animation: 'fade',
timer: false,
loop: true
}

$('body').vegas(valores);

Conclusión

Este tutorial pretende mostrar una posibilidad entre muchas para poder pasar variables en PHP a un script de jQuery. Lo más importante es comprender el funcionamiento de la función wp_localize_script(). La combinación de ACF con esta técnica permite multitud de posibilidades para adaptar útiles plugins de jQuery, pues el procedimiento es muy similar.