Blog personal de IT, viajes y otros hobbies

Etiqueta: gutenberg

1001 formas de crear bloques de Gutenberg

Este artículo lo escribí básicamente para poner un poco de orden en mi cabeza ya que hay muchas formas y situaciones específicas para crear bloques de Gutenberg.

Veamos a continuación el diagrama de flujo de datos que he creado y en qué situación nos deja cada situación:

¿Debo usar bloques de Gutenberg? De ser así, ¿cuál es la solución adecuada?

Zona de principiantes

Bloques por defecto y reutilizables.

A día de hoy WordPress tiene por defecto una gran cantidad de bloques de Gutenberg que pueden ayudarte con tus múltiples necesidades para tu Web.

Algunos de los bloques por defecto de Gutenberg

Si uno o varios de estos bloques por defecto pueden servirte para dar solución a tu necesidad utilízalos directamente.

Ten en cuenta que también podrías generar un «bloque reutilizable» para reutilizar (valga la redundancia) este bloque o conjunto de ellos en el mismo o cualquier otro post.

Ten en cuenta que cualquier cambio que realices a un bloque reutilizable se modificará en todas sus instancias.

Aquí te dejo un ejemplo de cómo puedes crear un bloque reutilizable del foro en español de WordPress.

Directorio de patrones o plugins

En caso de que WordPress no tengo bloques por defecto que puedan servirte, bien puedes buscar en el Directorio de patrones (recientemente añadido a la Web de WordPress).

Directorio de patrones de Gutenberg

En este directorio solo tendrás que buscar si alguno de los patrones te sirve, para después copiarlo, pegarlo directamente en tu contenido y luego hacer los ajustes que sean necesarios.

Si aún no encuentras lo que estás buscando, lo ideal sería que instales un plugin que implemente lo que estás necesitando para tu Web.

No tengo mucha experiencia en este sector, pero estos son algunos de los más utilizados:

También puedes buscar en el directorio de plugins con la palabra clave «Gutenberg».

Resultados de plugins con la palabra clave «Gutenberg»

Zona de PHP

Si quieres desarrollar tu bloque en forma personalizada y sin mojarte las manos en Javascript, entonces tendrás que buscar alguna solución con PHP.

Crear bloques con Advanced Custom Field

Este plugin me salvó las papas durante mis 6 años de Freelance en España y afortunadamente no se ha quedado atrás desde Gutenberg irrumpió en el ecosistema de WordPress.

Sigue siendo muy fácil de diseñar, programar, ajustar y utilizar. Para ello debes simplemente seguir las instrucciones de su tutorial oficial y en nada tendrás tu bloque de Gutenberg personalizado.

Demo de bloque de Gutenberg desarrollado con ACF

¿Conoces alguna otra librería o plugin con el que puedas realizar bloques de Gutenberg solamente con PHP? Déjame un comentario así luego lo investigo.

Zona de Javascript

Si por narices te toca realizar el bloque de Gutenberg con Javascript, que sepas que aún así hay varias formas de implementarlo.

Variaciones

Utiliza variaciones si necesitas implementar un bloque por defecto de Gutenberg con ciertos valores de configuración predeterminado.

Ten en cuenta que creará un nuevo icono en el listado de bloques de Gutenberg.

Ejemplo de una variación del bloque «Columns» donde añade por defecto un icono y 3 columnas vacías.

wp.blocks.registerBlockVariation(
  'core/columns', {
    name: 'project-intro',
    title: 'Project Intro',
    icon: 'portfolio',
    scope: ['inserter'],
    innerBlocks: [
      ['core/column'],
      ['core/column'],
      ['core/column'],
    ],
  }
);

Link a la documentación oficial.

Estilos

Registrar un estilo hará que tu bloque tenga una clase CSS única que puedes utilizar para dar solución a tu necesidad.

A diferencia de las «variaciones», los estilos no crearán un icono nuevo en el listado de bloques. En su lugar mostrará un estilo nuevo en el sidebar del bloque en cuestión.

wp.blocks.registerBlockStyle( 'core/quote', {
    name: 'fancy-quote',
    label: 'Fancy Quote',
} );
Ejemplo de «estilos» para el bloque de imágenes.

Patrones

Registrando un patrón puedes crear una plantilla con bloques por defecto o personalizados. Una vez que se selecciona desde el listado de bloques solo nos queda modificar sus valores.

También puede especificarse en su código si el usuario puede seguir añadiendo bloques al patrón o bien editar sus valores.

register_block_pattern(
    'my-plugin/my-awesome-pattern',
    array(
        'title'       => __( 'Two buttons', 'my-plugin' ),
        'description' => _x( 'Two horizontal buttons, the left button is filled in, and the right button is outlined.', 'Block pattern description', 'my-plugin' ),
        'content'     => "<!-- wp:buttons {\"align\":\"center\"} -->\n<div class=\"wp-block-buttons aligncenter\"><!-- wp:button {\"backgroundColor\":\"very-dark-gray\",\"borderRadius\":0} -->\n<div class=\"wp-block-button\"><a class=\"wp-block-button__link has-background has-very-dark-gray-background-color no-border-radius\">" . esc_html__( 'Button One', 'my-plugin' ) . "</a></div>\n<!-- /wp:button -->\n\n<!-- wp:button {\"textColor\":\"very-dark-gray\",\"borderRadius\":0,\"className\":\"is-style-outline\"} -->\n<div class=\"wp-block-button is-style-outline\"><a class=\"wp-block-button__link has-text-color has-very-dark-gray-color no-border-radius\">" . esc_html__( 'Button Two', 'my-plugin' ) . "</a></div>\n<!-- /wp:button --></div>\n<!-- /wp:buttons -->",
    )
);

Enlace a la documentación oficial de los patrones.

Bloques con renderizado en el servidor

Si tu bloque es muy complejo para implementar todo el código en el editor o su almacenamiento, puedes optar por capturar solamente los valores y luego enviarlos a una plantilla de PHP para su posterior renderizado.

Con esta opción ganarás en facilidad de implementación pero como punto negativo no podrás ver la actualización en tiempo real en el editor.

Enlace a la documentación oficial.

Creación personalizada

Si todos los puntos anteriores no te han valido, entonces no queda más que crear el bloque en forma totalmente personalizada, registrando todos los valores a guardar, indicando cómo se mostrará en el editor y también su posterior almacenamiento y renderizado en el Frontend.

Por mi parte, aprendí a programar esos bloques siguiendo el curso de Javascripforwp.com (no hay enlace de afiliado ocutlo, solo lo recomiendo por el valor que aporta).

Mi charla en WordCamp Pontevedra

Te dejo también este vídeo con la charla sobre las «1001 formas de crear bloques de Gutenberg» que di en la WordCamp de Pontevedra.

El get_post_meta de Gutenberg se llama getEditedPostAttribute(‘meta’)

Si como yo estás iniciándote en el mundo del desarrollo personalizado de bloques de Gutenberg, seguramente llegarás al momento donde necesitarás implementar valores del post meta tal como hacíamos en PHP con la función get_post_meta.

Bueno, la función equivalente en el mundo Javascript se llama getEditedPostAttribute( 'meta' ) aunque hay que tener algunos puntos en consideración que te explicaré a continuación.

const meta = wp.data.select( 'core/editor' ).getEditedPostAttribute( 'meta' );

Si el posta meta fue previamente registrado y configurado para su uso con la API ya solo te queda obtener el valor de la variable meta:

const meta = wp.data.select( 'core/editor' ).getEditedPostAttribute( 'meta' );
const metaExample = meta[ 'mi_valor_meta' ];

Cómo registrar el post meta

Para asegurarte que el post meta esté disponible en Gutenberg tiene que estar registrado y con el atributo show_in_rest con el valor true.

function mg_registrar_post_meta() {
	register_post_meta(
		'post',
		'mi_valor_meta',
		[
			'show_in_rest' => true,
			'single' => true,
			'type' => 'string',
		]
	);
}
add_action( 'init', 'mg_registrar_post_meta');

Cómo obtener el meta de otro post

Si quieres obtener el post meta de otro post, puedes usar la función Javascript getEntityRecord, y pasarle el ID del post que quieres obtener:

const { meta } = wp.data.select( 'core' ).getEntityRecord( 'postType', 'post', 36 );

La función javascript getEntityRecord es el equivalente al get_post que utilizamos en PHP.

Crear bloques de gutenberg con ACF

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):

Diseño bloque personalizado de Gutenberg con ACF
Diseño del bloque personalizado de Gutenberg con ACF

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.

campos personalizados acf para bloque de gutenberg

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»:

detalles de campo repeater acf para bloque gutenberg
  • 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.

WordCamp Sofia 2017 Mauricio Gelves ponencia Gutenberg

Mi ponencia sobre Gutenberg en la WordCamp Sofía 2017 (Bulgaria)

Segunda ponencia internacional y nada menos que en la WordCamp Sofía 2017 (Bulgaria), ciudad que albergó la segunda edición de la WordCamp Europe. Allí tuve la oportunidad de hablar sobre el proyecto del nuevo editor de contenidos Gutenberg.

WordCampWordCamp Sofia 2017
Título: The Gutenberg Project: pros and cons for this big change in WordPress
Descripción: Gutenberg is the name of the new content editor you will be using in the version 5.0 of WordPress. After a lot of years using TinyMCE, WordPress will introduce a new editor in its administrator interface that will allow us to create and edit content in a more efficient and simple way. Join Mauricio Gelves in his talk to see the different pros and cons of this big change in the WordPress history.

Galería de fotos

Funciona con WordPress & Tema de Anders Norén