Crear bloques de Gutenberg con ACF

Seamos sinceros, Gutenberg ha venido para resolver muchos problemas técnicos y modernizar la forma en la que creamos contenido, pero para los desarrolladores ha sido un baldazo de agua fría por la cantidad de nuevas tecnologías que debíamos incorporar a nuestro ya sobrecargado kit de lenguajes de programación.

Pero que no cunda el pánico porque Elliot Condon y su equipo de desarrollo de ACF (Advanced Custom Fields) han implementado una nueva funcionalidad en su plugin que nos permite asignar un conjunto de campos a los nuevísimos bloques de Gutenberg.

Básicamente estos son los pasos que vamos a seguir para crear bloques personalizados de Gutenberg con ACF:

• Registrar el bloque de Gutenberg
• Crear los campos personalizados con el plugin ACF
• Exportar los campos a JSON y PHP (opcional)
• Crear el mockup del bloque (HTML y CSS)
• Encolar los estilos en el administrador de WordPress

⚠️Disclaimer: Para seguir estos pasos vamos a necesitar descargar la versión ACF PRO 5.8.0 del plugin de pago de ACF. Tengo ya dos webs en producción y la versión Beta funciona de maravillas.

Bloque a desarrollar

A modo de ejemplo vamos a desarrollar un bloque que nos permita crear un conjunto de charlas, con sus respectivos ponentes, títulos, descripciones, etc. Más o menos algo así (no me critiquéis el diseño que como podéis ver soy pésimo):

Primer paso: registrar el bloque de Gutenberg

En primer lugar tendremos que registrar el bloque de Gutenberg con los parámetros tal como lo haríamos con un bloque nativo. Para más opciones se puede consultar los pasos del Handbook.

<?php
/**
 * Registramos el bloque de Gutenberg para las charlas.
 */
function wcz_create_talk_gb_block() {
		// register a testimonial block
		acf_register_block( [
			'name'				=> 'talk',
			'title'				=> __( 'Talk', DOMAIN_NAME ),
			'description'		=> __('Block with basic info of the talk.', DOMAIN_NAME),
			'render_callback'	=> 'talk_block_render_callback',
			'mode'				=> 'auto',
			'icon'				=> 'image-filter',
			'keywords'			=> [ 'talk', 'quote' ],
			'enqueue_style'		=> get_template_directory_uri() . 'blocks/testimonial/testimonial.css',
		] );
}
add_action('acf/init', 'wcz_create_talk_gb_block');

Vamos a registrar el bloque utilizando la función acf_register_block() cuando se ejecuta el hook propio del plugin ACF llamado acf/init. Estos son los parámetros más importantes:

• name: el bloque necesita un nombre sin mayúscula, acentos o caracteres especiales.
• title: asignaremos un título que mostrará en el selector de bloques.
• render_callback: nombre de la función que se encargará de renderizar el HTML.
• icon: podemos elegir un icono del propio Dashicon de WordPress o bien pegar el código de un fichero svg.
• mode: Con la opción auto el bloque se renderiza automáticamente cada vez que pierde el foco.
• keywords: palabras claves para el filtro en el selector de bloques.
• enqueue_style: podemos encolar un CSS con los estilos específicos para el bloque.

Crear campos personalizados en ACF

Una vez que tenemos el bloque de Gutenberg creado es hora de armar la estructura de datos. Para ellos vamos a crear un grupo de campos personalizados como siempre lo hemos hecho con ACF.

Vamos a utilizar el campo «Title» para el encabezado de la sección y luego tenemos un campo «Repeater» que tiene otro conjunto de campo personalizados para cada «Ponencia»:

• Speaker avatar: campo para dar de alta la imagen del ponente.
• Speaker name: campo de texto para el nombre del ponente.
• Talk title: campo de texto para el título de la ponencia.
• Talk description: campo textarea para la descripción de la ponencia.
• Twitter account: campo de texto para el nombre de usuario de Twitter del ponente.

👉🏻Prestad atención a la estructura de nombres que asigno tanto al repetidor como a los campos hijos. De esta manera tenemos una nomenclatura simple y clara que agradeceremos cuando tengamos que implementar el frontend.

Una vez que tenemos todos los campos solo nos resta definir dónde queremos que se muestren dentro de todo el ecosistema de WordPress. Para ello elegiremos desde la sección «Ubicación» el tipo «Bloque» y luego seleccionamos el bloque «Talk» que hemos creado en el punto anterior.

Exportar los campos a JSON y PHP

Este es un paso opcional ya que no afecta al desarrollo como tal del bloque, pero lo aconsejo ya que nos permite:

• tener la estructura de los campos en control de versiones (como GIT o BitBucket).
• evitar consultas extras a base de datos.
• facilitar el desarrollo web entre un equipo de programadores.

Para exportar los campos debemos seguis los siguientes pasos:

1. Ir al menu Campos Personalizados » Herramientas
2. Marcar el checkbox del campo que queremos exportar
3. Hacer click en «Export File» (que nos descargará un fichero .json)
4. Hacer click en «Generate PHP«. Nos redireccionará a una nueva página con el código PHP.
5. El código PHP debemos incluirlo en alguna carpeta de nuestro proyecto y llamarlo desde el tema o plugin que estemos desarrolando.
6. El fichero .json también debemos incluirlo en alguna carpeta del proyecto para posibles cambios a futuro.

Crear el mockup para el bloque (HTML & CSS)

Con el bloque y el conjunto de campos personalizados creados es hora de que pasemos al Frontend para «pintar» toda esta solución.

Solo debemos crear el HTML y el CSS en conjunto con las funciones habituales de ACF para mostrar los campos (get_field, the_field, get_sub_field, the_sub_field, etc).

Resumo parte del HTML para que el ejemplo no se haga muy engorroso, aunque sigue siendo igual de válido para explicar la idea:

<?php
/**
* Esta es la función que renderiza el bloque.
* Es la misma que declaramos cuando registramos el bloque de Gutenberg
* en el primer paso.
*/
function talks_block_render_callback( $block ) {
	// Recorrro en bucle todas las charlas dadas de alta en el backend.
	while ( have_rows('wcz_gb_talks') ) : the_row(); ?>
		<div class="talk">
			<div class="talk__meta">
				<h3 class="talk__h"><?php the_sub_field( 'wcz_gb_talk_title' ); ?></h3>
				<p class="talk__b"><?php the_sub_field( 'wcz_gb_talk_description' ); ?></p>
				<div class="talk__speaker">
					<p class="talk__speaker__h">Speaker:</p> <span><?php the_sub_field( 'wcz_gb_talk_speaker' ); ?></span><br>
				</div>
			</div><!-- END .talk__meta -->
		</div><!-- END .talk -->
	<?php endwhile; ?>
}

Resultado final

Si todo ha salido bien tendremos un nuevo bloque de Gutenberg en el editor al cual podemos asignar valores con campos personalizados y con estructura y estilos propios ¿Ha sido fácil, no?

Bola extra

Si lo prefieres puedes ver el vídeo con mi ponencia en la WordCamp Zaragoza 2019 donde explico el mismo proceso detallado en el artículo.