Antes de ver cómo crear un bloque personalizado con el editor Gutenberg de WordPress, recordamos que el editor Gutenberg, o editor de bloques de WordPress, es un creador de páginas que está incluido en el CMS desde la versión 5.0. Lo que hace es agregar bloques de contenido para ayudar, de forma visual, a maquetar nuestras páginas.
De este modo, Gutenberg reemplaza el editor clásico de WordPress, que usaba TinyMCE (WYSIWYG), como editor predeterminado tanto en las publicaciones como en las páginas. Aunque si lo preferimos, podemos volver sin problema al editor anterior.
Por tanto, el objetivo de Gutenberg es ayudar a los usuarios a crear publicaciones y páginas con más flexibilidad, ya que los nuevos bloques incluyen muchas cosas: desde párrafos, encabezados o listas, hasta imágenes, galerías, incrustaciones y mucho más.
Nuestro primer bloque personalizado con Gutenberg
En nuestro primer ejemplo crearemos un nuevo tipo de bloque, que muestre un mensaje con estilo y sin que permita la edición por parte del usuario. Los bloques con contenido estático se programan con Javascript utilizando la función registerBlockType, que es la que se encarga de especificar el plano de un bloque.
Poner en cola los scripts
Lo primero que tenemos que hacer es registrar el bloque del lado del servidor y así, asegurarnos de que el script esté en cola cuando cargue el editor. Para ello, registraremos los scripts y estilos usando wp_register_script y wp_register_style. A continuación, los asignaremos como identificadores asociados con nuestro bloque usando script, style, editor_script y editor_style.
Los archivos editor_script y editor_style solo se pondrán en cola en el editor, mientras que los script y style lo harán tanto en el editor como al ver una publicación.
Veamos un ejemplo:
<?php
/*
Ejemplo Gutenberg
*/
function gutenberg_examples_01_register_block() {
// Carga automáticamente dependencias y version
$asset_file = include( plugin_dir_path( __FILE__ ) . 'build/index.asset.php');
wp_register_script(
'gutenberg-examples-01-esnext',
plugins_url( 'build/index.js', __FILE__ ),
$asset_file['dependencies'],
$asset_file['version']
);
register_block_type( 'gutenberg-examples/example-01-basic-esnext', array(
'api_version' => 2,
'editor_script' => 'gutenberg-examples-01-esnext',
) );
}
add_action( 'init', 'gutenberg_examples_01_register_block' );
Tendremos en cuenta que en el ejemplo se usa la compilación que establece automáticamente las dependencias y las versiones del fichero. Si estuviéramos utilizando el código ES5, podríamos especificar array (‘wp-blocks’, ‘wp-element’) como matriz de dependencia.
- wp-blocks incluye el registro de tipo de bloque y las funciones relacionadas
- wp-element incluye la “abstracción del elemento de WordPress” para describir la estructura de nuestros bloques
Registrando el bloque
En ESNext:
import { registerBlockType } from '@wordpress/blocks';
import { useBlockProps } from '@wordpress/block-editor';
const blockStyle = {
backgroundColor: '#900',
color: '#fff',
padding: '20px',
};
registerBlockType( 'gutenberg-examples/example-01-basic-esnext', {
apiVersion: 2,
title: 'Ejemplo en ESNext',
icon: 'universal-access-alt',
category: 'design',
example: {},
edit() {
const blockProps = useBlockProps( { style: blockStyle } );
return (
<div { ...blockProps }>Hola mundo (desde el editor).</div>
);
},
save() {
const blockProps = useBlockProps.save( { style: blockStyle } );
return (
<div { ...blockProps }>
Hola mundo (desde el frontend).
</div>
);
},
} );
En ES5:
( function ( blocks, element, blockEditor ) {
var el = element.createElement;
var useBlockProps = blockEditor.useBlockProps;
var blockStyle = {
backgroundColor: '#900',
color: '#fff',
padding: '20px',
};
blocks.registerBlockType( 'gutenberg-examples/example-01-basic', {
apiVersion: 2,
title: 'Ejemplo en ES5',
icon: 'universal-access-alt',
category: 'design',
example: {},
edit: function () {
var blockProps = useBlockProps( { style: blockStyle } );
return el(
'p',
blockProps,
'Hola mundo (desde el editor).'
);
},
save: function () {
var blockProps = useBlockProps.save( { style: blockStyle } );
return el(
'p',
blockProps,
'Hola mundo (desde el frontend).'
);
},
} );
} )( window.wp.blocks, window.wp.element, window.wp.blockEditor );
El ejemplo debería mostrar la frase “Hola mundo (desde el editor)” en la zona de administración y “Hola mundo (desde el frontend)” desde la zona de la interfaz. Una vez registrado el bloque, lo veremos disponible como una opción de edición, utilizando los valores de título, icono y categoría. Podremos elegir un icono de los que vienen incluidos en Dashicons o un elemento svg personalizado.
Los nombres de bloque comienzan siempre con una letra y únicamente pueden incluir caracteres alfanuméricos en minúscula o guiones. Ejemplo: mi-plugin/mi-bloque-personalizado. Además, deben contener un prefijo específico para nuestro plugin, lo que evitará conflictos cuando varios plugin registren un bloque con el mismo nombre. En nuestro ejemplo el prefijo es gutenberg-examples.
Por su parte, la función edit describe la estructura de nuestro bloque en el editor, mientras que save hace referencia al contenido de guardado.
Conclusión
Aunque existen plugins que podrían facilitarnos la tarea, crear un bloque personalizado con Gutenberg en WordPress desde código, permite construir nuestras propias soluciones y adaptarlas a nuestras necesidades de uso