Cómo crear bloques de Gutenberg con ACF

En este tutorial te voy a enseñar a cómo crear bloques de Gutenberg con Advanced Custom Fields para que puedas tener tus propios bloques personalizados.

Para ponernos un poco en contexto, con la llegada de Gutenberg a la versión 5.0, WordPress deja atrás al clásico editor WYSIWYG para que el usuario comience a generar contenidos con bloques. De esta forma, WordPress incluye en su core la posibilidad de crear contenido en tu web sin recurrir a maquetadores visuales de terceros.

ACF adaptó su fabuloso plugin (en la versión PRO) y nos facilitó la vida (una vez más) para poder crear bloques de Gutenberg de una forma sencilla y poder introducirlos en nuestras páginas y entradas.

En este ejemplo, te voy a mostrar cómo crear bloques de Gutenberg con ACF, pero ojo, tiene que ser con la versión PRO de Advanced Custom Fields. En concreto, vamos a ver cómo crear un slider de imágenes. No soy partidario de los sliders y menos usarlos en la home pero entiendo que para determinados desarrollos puede ser interesante introducirlo y además es perfecto en este tutorial para mostrar de que forma fácil podemos crear bloques propios para nuestro desarrollo.

Voy a usar la librería bxSlider. Una librería minimalista, atractiva y ligera para cargar tus imágenes en un slider.

Repaso al proyecto

El bloque que vamos a crear, lo voy a registrar a nivel del fichero functions.php y que esté incluido en el tema como un añadido extra dentro de un directorio que vamos a llamar inc.

Puedes descargarte desde mi repositorio de Github el proyecto o bien puedes ir a la web de bxSlider y descargarte desde su repositorio para ir siguiendo mis pasos e ir creando lo necesario.

La estructura dentro del tema de WordPress para este bloque va a ser:

• inc/slider-acf-block/slider-acf-block.php
• inc/slider-acf-block/bxslider/css/jquery.bxslider.css
• inc/slider-acf-block/bxslider/css/images/controls.png
• inc/slider-acf-block/bxslider/css/images/bx_loader.gif
• inc/slider-acf-block/bxslider/js/jquery.bxslider.js
• inc/slider-acf-block/bxslider/js/slider.js

De todos estos ficheros, los que vamos a crear y tocar van a ser slider-acf-block.php y slider.js para que funcione el bloque. El resto son descargados de la librería de bxSlider.

Aquí te muestro el bloque creado para este tutorial:

Registrar el bloque ACF en nuestro tema de WordPress

Lo primero que tienes que hacer es registrar el bloque para que ACF lo detecte al crear un nuevo grupo de campos. Debes de añadir el siguiente código al fichero functions.php:

//* Register Slider Block in ACF
add_action( 'acf/init', 'ea_register_slider_acf_block_types' );
function ea_register_slider_acf_block_types() {

    // Register a Slider ACF Block.
    acf_register_block_type(array(
        'name'              => 'slider-acf-block',
	'title'             => __('Slider ACF Block'),
	'mode'				=> 'auto',
        'description'       => __('Un bloque personalizado de slider con ACF'),
        'render_template'   => 'inc/slider-acf-block/slider-acf-block.php',
        'category'          => 'common',
	'icon'              => 'images-alt2',
	'keywords'          => array( 'slider', 'carousel' ),

	'enqueue_assets'	=> function() {
	       wp_enqueue_style( 'slider-css', get_stylesheet_directory_uri() . '/inc/slider-acf-block/css/jquery.bxslider.css', array(), '5.3.2' );
		wp_enqueue_script( 'slider-lib-js', get_stylesheet_directory_uri() . '/inc/slider-acf-block/js/jquery.bxslider.js', array('jquery'), '5.3.2', true );
		wp_enqueue_script( 'slider-script-js', get_stylesheet_directory_uri() . '/inc/slider-acf-block/js/slider.js', array('jquery'), '5.3.2', true );
	}
    ));
}

Con esta función le decimos a ACF que:

• El name es el ID que tendrá tu bloque, en este caso ‘slider-block-acf’.
• El campo title del bloque va a ser el nombre que le asignemos, ‘Slider Block ACF’.
• La descripción que nos aparecerá del bloque cuando lo elijas en el editor.
• Con render_template le indicamos la plantilla que se va a encargar de mostrar el contenido del slider en tu frontend va a ser inc/slider-acf-block/slider-acf-block.php. Va  a ser la plantilla que tenga el HTML y el PHP para añadir los campos de ACF y poder darle forma al bloque.
• Va a ser un bloque del tipo común, es lo que ponemos en category. Existen estos tipo de bloques en el core de WordPress common, formatting, layout, widgets, embed.
• El icono que se va a mostrar cuando elijas el bloque en tu editor. Puedes elegir los iconos desde aquí.
• Las keywords son las palabras con las que quieres que se encuentre este bloque en el editor.
• Y con enqueue_assets le indicamos que ficheros vamos a necesitar para renderizar el contenido de nuestro bloque. Necesitaremos añadir estilos .css y ficheros .js para cargar la librería bxSlider. De esta forma estos ficheros solo se cargan cuando está cargado el bloque.

Crear los campos ACF en nuestro tema de WordPress

Ahora, en tu administrador de WordPress, tienes que crear un nuevo grupo de campos con ACF. Este campo se va a mostrar cuando sea un bloque y en el listado debe de aparecer el bloque con su title, registrado en el fichero functions.php:

Después de crear el grupo de campos, tienes que añadirle campos. Para este ejemplo he decidido usar un campo de tipo repeater y dentro de este, un subcampo de tipo imagen para añadir tantas imágenes como se desee. El subcampo de tipo imagen va a ser de tipo array.

Recordarte que para usar estas características debes de usar Advanced Custom Fields PRO.

Si ahora vas a una entrada de tu WordPress y en el editor de Gutenberg buscas ‘slider’ debe de aparecer el bloque que has registrado. Verás el nombre, descripción, icono, etc. Pero cuando lo añadas no vas a ver nada más porque todavía no has añadido el fichero que renderiza el contenido del bloque. Vamos a crearlo.

Creando la plantilla para mostrar los campos ACF

El siguiente paso va a ser crear la plantilla para que ACF muestre el contenido. El fichero es inc/slider-acf-block/slider-acf-block.php como le hemos indicado en la función que hemos añadido a functions.php y va a tener el siguiente contenido:

<?php 

/**
 * Slider Block Template.
 *
 * Aquí vamos a renderizar el contenido de nuestro bloque cuando sea llamado en nuestro editor
 */

$id = 'slider-' . $block['id'];
if( !empty($block['anchor']) ) {
    $id = $block['anchor'];
}
?>

<div id="<?php echo esc_attr($id); ?>" class="bxslider">

    <?php if( have_rows( 'slider_acf_block_repeater' ) ): ?>
        <?php while( have_rows( 'slider_acf_block_repeater' ) ): the_row(); ?>
            <?php $sliderImage = get_sub_field( 'slider_acf_block_image' ); ?>
            <img 
                src="<?php echo esc_url( $sliderImage['url'] ); ?>" 
                alt="<?php echo esc_attr( $sliderImage['alt'] ); ?>"
            />
        <?php endwhile; ?>
    <?php endif; ?>

</div>

Lo primero que ves en el código es que estamos creando una variable con la ID dinámica para añadirle al div contenedor del bloque.

Lo siguiente es el div contenedor del bloque al que le pasamos la ID dinámica dentro del atributo id. Como atributo de clase, le establecemos .bxslider que va a ser la clase que le pasemos en la librería para que cree el slider dentro de este div.

Por otro lado, hay una sentencia condicional en la que comprueba si contiene datos nuestro campo repeater creado slider_acf_block_repeater. De ser así, creamos un bucle while recorriendo todos los datos de las imágenes (que se añadirán posteriormente con el editor de bloques). De la imagen obtendremos la url y el atributo alt para mostrarlas en el frontend. Se usa la variable $sliderImage para obtener los valores del campo slider_acf_block_image que recordemos, es un array de tipo imagen.

Ahora vayamos con los ficheros JavaScript.

Inicializando el slider con Javascript

Vamos a añadir la funcionalidad a nuestro código para que la librería de bxSlider haga funcionar el slider. En el fichero inc/slider-acf-block/bxslider/js/slider.js añadiríamos el siguiente código:

(function ($) {
    $(window).on('load', function () {
        $('.bxslider').bxSlider({
            auto: true,
            stopAutoOnClick: true,
            pager: true,
            slideWidth: 700
        });
    })
})(jQuery);

Es un sencillo script que cuando estén cargados los elementos en la página va añadir la funcionalidad a las imágenes que están dentro del contenedor que le indicamos, recuerda que era .bxslider. Al objeto bxslider le pasamos a sus propiedades unos valores para que las imágenes: cambien automáticamente, se paren cuando pasemos el ratón por encima, tenga paginación y un ancho de 700. Puedes ver más propiedades aquí.

Ahora solo falta que incluyas las librerías .css y .js para que funcione todo. También las imágenes de los controles:

• inc/slider-acf-block/bxslider/css/jquery.bxslider.css
• inc/slider-acf-block/bxslider/css/images/controls.png
• inc/slider-acf-block/bxslider/css/images/bx_loader.gif
• inc/slider-acf-block/bxslider/js/jquery.bxslider.js

Una vez echo esto, ya puedes ir a tu editor para crear tu bloque de slider.

Creando el bloque en nuestro editor

Una vez hecho los anteriores pasos, vemos que de forma sencilla tenemos un bloque personalizado para nuestra web. Vamos a nuestro editor y ya podemos empezar a introducir imágenes:

Y de esta forma tan sencilla hemos visto cómo crear bloques de Gutenberg con Advanced Custom Fields. Espero que te sirva para tus proyectos.

Si te interesa seguir aprendiendo más, puedes visitar mi entrada de cómo es la jerarquía de plantillas de WordPress.