En este artículo vamos a conocer un poco más de cerca una de las herramientas del nuevo editor de WordPress, conocido como Gutenberg y disponible a partir de WordPress 5.x. Se tratan de los bloques, que permiten insertar unidades de contenido de un tipo específico, dentro de páginas o posts de WordPress, sustituyendo a los tradicionales shortcodes, como explicábamos recientemente. En este tutorial, vamos crear nuestro primer bloque personalizado, de modo que podamos reutilizar unidades de contenido a lo largo de diversos post o páginas en un sitio WordPress.
Los bloques te permiten crear todo tipo de contenidos y personalizar diversas características, las que sean necesarias para la unidad de contenido con la que trabajan. Cada bloque se trata de manera separada al editar un post.
Intentaremos mantener las cosas simples y, por tanto, en esta ocasión vamos a construir un bloque que únicamente muestra un contenido estático con un estilo determinado. A partir de esa base, ya podremos complicarnos tanto como queremos
Definición del bloque a través de un plugin
WordPress viene con una buena colección de bloques ya listos para ser usados dentro de su editor. Para crear crear a continuación nuevos bloques personalizados lo ideal sería trabajar dentro del contexto de un plugin.
En anteriores artículos ya hemos explicado cómo crear plugins en WordPress, por lo que vamos a partir sobre el conocimiento de ese artículo anterior.
Para comenzar, podemos ver la estructura de carpetas de nuestro plugin.
Como puedes comprobar en la imagen, vamos a tener dos partes fundamentales en este primer bloque:
- PHP: archivo my-first-block.php. Este archivo se ejecuta cuando el plugin está activo. En él colocaremos el registro del nuevo bloque dentro del editor de WordPress.
- JavaScript: my-first-block.js. Este archivo contiene cómo se va a comportar el bloque: dónde se debe mostrar en el editor y cómo se muestra una vez se esté usando, etc.
Registro del bloque en el plugin
Veamos ahora cómo crear el plugin de nuestro primer bloque, en el archivo my-first-block.php. Eeste plugin se debe definir con los mecanismos habituales de desarrollo los plugins, básicamente indicando una función y el momento en el que se va a enganchar su ejecución.
<?php
/*
Plugin Name: My First Block Arsys
Description: Un plugin para crear un nuevo bloque en Gutenberg
Author: Arsys Internet
Author URI: https://www.arsys.es/
Version: 0.0.0
*/
function my_first_block() {
wp_enqueue_script(
'my_first_block-js',
plugins_url('my-first-block/js/my-first-block.js', dirname(__FILE__))
);
}
add_action('enqueue_block_editor_assets', 'my_first_block');
- Los primeros comentarios definen los metadatos del plugin, título, descripción, autores y otros.
- La función my_first_block() encola un script, necesario para definir el bloque personalizado que vamos a crear. Para hacer esta acción necesitamos como mínimo un nombre para el script y la ruta donde se encuentra el código.
- La función add_action() se encarga de enganchar la función my_first_block(), para su ejecución en el momento adecuado, con el hook ‘enqueue_block_editor_assets’, que se ejecuta después de que los assets del sistema de bloques de Gutenberg se hayan preparado para la interfaz del editor.
Definición del bloque con JavaScript
Toda la parte de definición del comportamiento de los bloques se realiza mediante JavaScript. Para nuestro bloque, que únicamente muestra un contenido estático, no es necesario tener unos conocimientos muy grandes de JavaScript, ni siquiera de React, la librería con la que Gutenberg se ha construido y que ha protagonizado numerosos artículos prácticos en este blog.
Enseguida lo comentamos todo, pero antes queremos mostrar el código completo de nuestro bloque:
var blockStyle = {
backgroundColor: 'azure',
color: '#666',
padding: '15px'
}
wp.blocks.registerBlockType('my-first-block/my-block', {
title: 'Mi primer bloque',
icon: 'media-spreadsheet',
category: 'layout',
edit: function() {
return wp.element.createElement( 'h2', { style: blockStyle }, 'Este es tu nuevo bloque!!' );
},
save: function() {
return wp.element.createElement( 'h2', { style: blockStyle }, 'Este es el contenido que se salva!!' );
}
}
)
- Comenzamos definiendo una variable de tipo objeto para almacenar unos cuantos estilos, que luego vamos a usar sobre nuestro bloque.
- Usamos el método del API JavaScript de WordPress llamado wp.blocks.registerBlockType() para registrar un nuevo tipo de bloque. Esta función necesita dos parámetros:
- El nombre del bloque nuevo que estamos creando
- Un objeto, que puede llegar a ser bastante complejo, con el detalle de propiedades y funcionalidades de configuración del bloque. Luego vamos a comentar este objeto por separado.
Con este sencillo paso podríamos ver ya nuestro bloque, dentro del editor de WordPress, y lo podríamos usar perfectamente, una vez activado el plugin, claro está.
Objeto de configuración del bloque
Nos queda por ver la parte de la configuración del bloque, que se entrega como segundo parámetro al método wp.blocks.registerBlockType() del API de WordPress. Esta parte puede llegar a ser muy compleja a medida que nuestro bloque sea más sofisticado, pero de momento sus propiedades son bastante sencillas de entender.
Veamos primero el objeto al que hacemos referencia para luego comentar sus distintas propiedades y métodos.
{
title: 'Mi primer bloque',
icon: 'media-spreadsheet',
category: 'layout',
edit: function() {
return wp.element.createElement( 'h2', { style: blockStyle }, 'Este es tu nuevo bloque!!' );
},
save: function() {
return wp.element.createElement( 'h2', { style: blockStyle }, 'Este es el contenido que se salva!!' );
}
}
- Con la propiedad title indicamos el título del bloque, que aparecerá en el editor de WordPress para que lo podamos identificar y usar.
- La propiedad icon sirve para indicarle un icono para representar este bloque. Podemos usar uno de los iconos ya definidos para el administrador de WordPress de la biblioteca Dashicons.
- La propiedad category indica en qué sección se va a mostrar este bloque. Pues al crear un nuevo bloque encontrarás que éstos están organizados en diversas categorías.
- El método edit() es uno de los más importantes. Indica qué es lo que va a mostrar el editor Gutenberg cuando este bloque haya sido usado.
- El método save(), otro fundamental, indica qué tiene que mostrar la página al representar el bloque.
Métodos edit y save de la definición del bloque
Te darás cuenta de que el método edit() y el método save() son realmente muy parecidos. El primero indica cómo se representa el bloque al editar la página o post, dentro del administrador de WordPress. El segundo indica cómo ese bloque se mostrará realmente cuando los usuarios consulten la página o post que se está editando.
Dentro de los métodos edit() y save() estamos usando de nuevo el API de WordPress para generar un elemento, con el método wp.element.createElement(). Este método crea un contenido HTML, configurado mediante diversos parámetros:
- h2 indica la etiqueta que se usará para este elemento.
- { style: blockStyle } es la declaración de estilos CSS que se va a aplicar a este elemento.
- El tercer parámetro es el cuerpo del elemento que se está creando, que es un texto plano.
Como puedes ver, los métodos edit() y save() realmente son calcados para este caso particular, pues el bloque se mostrará prácticamente igual al editar la página que al visualizarla. La única diferencia es el cuerpo de la etiqueta H2, que tendrá un texto distinto al visualizarse dentro del editor y al salvarse para mostrarse como contenido en la página.
Al verse este bloque dentro del editor, lucirá de la siguiente manera:
Sin embargo, cuando la página se salva, el bloque genera un contenido ligeramente distinto, como podemos ver en la siguiente imagen, que es la vista de página.
¡Ya hemos creado un primer bloque personalizado para WordPress! Quizás no ha sido demasiado complejo, pero hemos podido conocer el flujo de trabajo para que puedas crear tus propios bloques en adelante.