Esta entrada es la segunda parte de la Guía completa sobre los patrones de bloques de Gutenberg y que incluye los siguientes puntos:
- Introducción a los patrones de bloques
- Insertar un patrón en una página
- Patrones pre-definidos y otros disponibles en directorios
- Añadir patrones disponibles en directorios a tu sitio
- Cómo crear un patrón desde cero
- Cómo crear un patrón si no eres desarrollador
- Cómo convertir bloques reusables en patrones de bloques
- Temas que usan patrones de bloques
- Documentación oficial.
En la primera parte vimos los 4 primeros puntos de todos los temas tratados en la guía: qué es un patrón de bloques, cómo insertar patrones pre-definidos en tus páginas y dónde encontrar y cómo copiar patrones que están disponibles en algunos directorios. Allí vimos que podemos pegar un patrón en la página que estamos editando, pero este no quedará almacenado en nuestra librería de patrones para poder reusarlo en el futuro.
Si queremos añadir un nuevo patrón a nuestra librería de patrones de Gutenberg, debemos crear y registrar dicho patrón. Es bastante sencillo, aunque necesitas algún conocimiento básico de desarrollo. Si no es tu caso, tranquilo que más adelante también veremos cómo crear patrones sin necesidad de tocar nada de código.
5. Crear un nuevo patrón
Para crear un patrón de bloques usando código debes usar la API Block Pattern. Específicamente, la función PHP register_block_pattern(). Veamos brevemente los distintos pasos que debemos seguir con un sencillo ejemplo.
Pero antes de empezar, permíteme hacer un pequeño apunte. Siempre que escribas código para personalizar tu WordPress te asaltará la misma duda: ¿dónde meto este código? Normalmente se suele recomendar el fichero functions.php del tema que tengas activo, aunque en esta entrada David explicaba cómo crear un plugin para agrupar tus personalizaciones y defendía que se trataba de una mejor solución.
Esta misma duda es aún más evidente en el caso que nos ocupa: puedes añadir la definición de un nuevo patrón de bloques en tu tema (como ya hace por defecto el tema Twenty Twenty-one, por ejemplo) o en un plugin. Y seguramente encontrarás defensores y detractores de ambas soluciones. Yo te explicaré cómo meterlo en un plugin, pero escoge la opción que mejor se adapte a tus necesidades.
#1 Diseña los bloques que formarán tu patrón
Como ya comenté en la entrada anterior, un patrón es un conjunto de bloques agrupados como quieras. Supón que quiero crear un patrón de bloques que me sirva para crear una sección describiendo las funcionalidades básicas de un producto.
Para ello, en una página que he titulado «Creating a Pattern» empiezo creando un bloque de tipo título, «6 Features Section», y a continuación inserto un bloque de 3 columnas.
En el primer bloque añado una imagen y debajo, el título y la descripción de la funcionalidad.
Copio la imagen, el título y la descripción en los dos bloques siguientes. Y finalmente, duplico esta fila para que me quede una sección que incluirá la descripción de las seis funcionalidades.
Por supuesto, sólo tiene sentido que crees un patrón de bloques si crees que lo vas a usar más de una vez.
Nelio Forms
Un plugin de contacto fantástico que usa el editor de bloques. En su simplicidad está la potencia del plugin. Me encanta, es muy versátil y funciona de maravilla para mí.
Wajari Velasquez
#2 Copia el contenido de los bloques
Una vez ya tenemos definido el conjunto de bloques, sólo tenemos que seleccionarlos con el ratón y en la barra de herramientas hacer clic en Copiar.
#3 Escapa el contenido HTML copiado
Para evitar problemas con los caracteres especiales del código copiado, necesitamos escaparlo (es decir, que se añada una barra invertida \ a aquellos caracteres como caracteres de tabulación o salto de línea, comillas simples y dobles, etc). Para ello hay varios muchos editores y herramientas online que pueden ayudarte, como onlinestringtools.com o JSON Escape/Unescape. Sólo debes pegar el código que habías copiado anteriormente y obtendrás un texto correctamente escapado y listo para usarlo en el siguiente paso.
#4 Registra el patrón
Llegado a este punto, lo único que nos queda es utilizar la función register_block_pattern() que te he mencionado anteriormente para registralo. Esta función recibe el nombre del patrón como primer parámetro y un array con las propiedades del mismo como segundo. Al final de esta entrada te doy más detalles sobre las propiedades que puedes definir del patrón, pero primero veamos los pasos que debemos seguir para crearlo.
Veamos nuestro ejemplo:
register_block_pattern(
'ruth-gutenberg-blocks-patterns/section-with-six-features',
array(
'title' => __( 'Section with 6 features', 'nelio' ),
'content' => "<!-- wp:heading {\"textAlign\":\"center\"} -->\n<h2 class=\"has-text-align-center\">6 Features Section</h2>\n<!-- /wp:heading -->\n\n<!-- wp:columns {\"verticalAlignment\":\"center\"} -->\n<div class=\"wp-block-columns are-vertically-aligned-center\"><!-- wp:column {\"verticalAlignment\":\"center\"} -->\n<div class=\"wp-block-column is-vertically-aligned-center\"><!-- wp:image {\"align\":\"center\",\"id\":44,\"sizeSlug\":\"large\",\"linkDestination\":\"none\"} -->\n<div class=\"wp-block-image\"><figure class=\"aligncenter size-large\"><img src=\"http://testsite.local/wp-content/uploads/2020/12/wordpress.png\" alt=\"\" class=\"wp-image-44\"/></figure></div>\n<!-- /wp:image -->\n\n<!-- wp:heading {\"textAlign\":\"center\",\"level\":3} -->\n<h3 class=\"has-text-align-center\">Feature Heading</h3>\n<!-- /wp:heading -->\n\n<!-- wp:paragraph {\"align\":\"center\"} -->\n<p class=\"has-text-align-center\">Feature description</p>\n<!-- /wp:paragraph --></div>\n<!-- /wp:column -->\n\n<!-- wp:column {\"verticalAlignment\":\"center\"} -->\n<div class=\"wp-block-column is-vertically-aligned-center\"><!-- wp:image {\"align\":\"center\",\"id\":44,\"sizeSlug\":\"large\",\"linkDestination\":\"none\"} -->\n<div class=\"wp-block-image\"><figure class=\"aligncenter size-large\"><img src=\"http://testsite.local/wp-content/uploads/2020/12/wordpress.png\" alt=\"\" class=\"wp-image-44\"/></figure></div>\n<!-- /wp:image -->\n\n<!-- wp:heading {\"textAlign\":\"center\",\"level\":3} -->\n<h3 class=\"has-text-align-center\">Feature Heading</h3>\n<!-- /wp:heading -->\n\n<!-- wp:paragraph {\"align\":\"center\"} -->\n<p class=\"has-text-align-center\">Feature description</p>\n<!-- /wp:paragraph --></div>\n<!-- /wp:column -->\n\n<!-- wp:column {\"verticalAlignment\":\"center\"} -->\n<div class=\"wp-block-column is-vertically-aligned-center\"><!-- wp:image {\"align\":\"center\",\"id\":44,\"sizeSlug\":\"large\",\"linkDestination\":\"none\"} -->\n<div class=\"wp-block-image\"><figure class=\"aligncenter size-large\"><img src=\"http://testsite.local/wp-content/uploads/2020/12/wordpress.png\" alt=\"\" class=\"wp-image-44\"/></figure></div>\n<!-- /wp:image -->\n\n<!-- wp:heading {\"textAlign\":\"center\",\"level\":3} -->\n<h3 class=\"has-text-align-center\">Feature Heading</h3>\n<!-- /wp:heading -->\n\n<!-- wp:paragraph {\"align\":\"center\"} -->\n<p class=\"has-text-align-center\">Feature description</p>\n<!-- /wp:paragraph --></div>\n<!-- /wp:column --></div>\n<!-- /wp:columns -->\n\n<!-- wp:columns {\"verticalAlignment\":\"center\"} -->\n<div class=\"wp-block-columns are-vertically-aligned-center\"><!-- wp:column {\"verticalAlignment\":\"center\"} -->\n<div class=\"wp-block-column is-vertically-aligned-center\"><!-- wp:image {\"align\":\"center\",\"id\":44,\"sizeSlug\":\"large\",\"linkDestination\":\"none\"} -->\n<div class=\"wp-block-image\"><figure class=\"aligncenter size-large\"><img src=\"http://testsite.local/wp-content/uploads/2020/12/wordpress.png\" alt=\"\" class=\"wp-image-44\"/></figure></div>\n<!-- /wp:image -->\n\n<!-- wp:heading {\"textAlign\":\"center\",\"level\":3} -->\n<h3 class=\"has-text-align-center\">Feature Heading</h3>\n<!-- /wp:heading -->\n\n<!-- wp:paragraph {\"align\":\"center\"} -->\n<p class=\"has-text-align-center\">Feature description</p>\n<!-- /wp:paragraph --></div>\n<!-- /wp:column -->\n\n<!-- wp:column {\"verticalAlignment\":\"center\"} -->\n<div class=\"wp-block-column is-vertically-aligned-center\"><!-- wp:image {\"align\":\"center\",\"id\":44,\"sizeSlug\":\"large\",\"linkDestination\":\"none\"} -->\n<div class=\"wp-block-image\"><figure class=\"aligncenter size-large\"><img src=\"http://testsite.local/wp-content/uploads/2020/12/wordpress.png\" alt=\"\" class=\"wp-image-44\"/></figure></div>\n<!-- /wp:image -->\n\n<!-- wp:heading {\"textAlign\":\"center\",\"level\":3} -->\n<h3 class=\"has-text-align-center\">Feature Heading</h3>\n<!-- /wp:heading -->\n\n<!-- wp:paragraph {\"align\":\"center\"} -->\n<p class=\"has-text-align-center\">Feature description</p>\n<!-- /wp:paragraph --></div>\n<!-- /wp:column -->\n\n<!-- wp:column {\"verticalAlignment\":\"center\"} -->\n<div class=\"wp-block-column is-vertically-aligned-center\"><!-- wp:image {\"align\":\"center\",\"id\":44,\"sizeSlug\":\"large\",\"linkDestination\":\"none\"} -->\n<div class=\"wp-block-image\"><figure class=\"aligncenter size-large\"><img src=\"http://testsite.local/wp-content/uploads/2020/12/wordpress.png\" alt=\"\" class=\"wp-image-44\"/></figure></div>\n<!-- /wp:image -->\n\n<!-- wp:heading {\"textAlign\":\"center\",\"level\":3} -->\n<h3 class=\"has-text-align-center\">Feature Heading</h3>\n<!-- /wp:heading -->\n\n<!-- wp:paragraph {\"align\":\"center\"} -->\n<p class=\"has-text-align-center\">Feature description</p>\n<!-- /wp:paragraph --></div>\n<!-- /wp:column --></div>\n<!-- /wp:columns -->",
)
);Como ves en el código anterior, el primer parámetro es el nombre único que identifica a nuestro patrón (ruth-gutenberg-blocks-patterns/section-with-six-features), y el segundo es un array con su title «Section with 6 features») y el propio contenido content. Es en content donde debemos pegar el contenido escapado del punto previo.
#5 Crea un pluguin con el patrón registrado
Para disponer del patrón registrado en nuestro editor, podemos crear un plugin o podríamos meterlo en nuestro tema activo. El código para crear un plugin es tan sencillo como esto:
<?php
/**
* Plugin Name: Ruth’s Block Patterns
* Description: My personal block patterns
* Version: 1.0.0
*/
defined( 'ABSPATH' ) or die();
function ruth_patterns_register_block_patterns() {
if ( ! class_exists( 'WP_Block_Patterns_Registry' ) ) {
return;
}
register_block_pattern(
'ruth-gutenberg-blocks-patterns/section-with-six-features',
array(
'title' => __( 'Section with 6 features', 'nelio' ),
'content' => "…",
)
);
}
add_action( 'init', 'ruth_patterns_register_block_patterns' );Y voilà!, si ahora refescamos nuestro editor, ya tenemos nuestro patrón creado y disponible en el editor de bloques.
Si prestas atención a la imagen anterior, verás que el bloque aparece en una categoría indefinida. Esto es porque no hemos indicado si nuestro bloque pertenece a alguna de las categorías existentes o a una nueva.
#6 Añadir una nueva categoría de patrones
Si consideramos que nuestro patrón encaja mejor en una nueva categoría, tienes la opción de registrarla. Para ello, debes usar la función register_block_pattern_category en el que también se le pasan dos parámetros, el nombre y un array con su descripción. Añade el siguiente fragmento de código al plugin que has creado:
function ruth_patterns_register_block_pattern_category() {
if ( ! class_exists( 'WP_Block_Patterns_Registry') ) {
return;
}
register_block_pattern_category (
'ruth-features',
array(
'label' => _x( 'Features', 'Block pattern category', 'nelio' )
)
);
}
add_action( 'init', 'ruth_patterns_register_block_pattern_category' );Y no olvides añadir dicha categoría a la definición de tu patrón:
function ruth_patterns_register_block_patterns() {
if ( ! class_exists( 'WP_Block_Patterns_Registry' ) ) {
return;
}
register_block_pattern(
'ruth-gutenberg-blocks-patterns/section-with-six-features',
array(
'title' => __( 'Section with 6 features', 'nelio' ),
'content' => "…",
'categories' => [ 'ruth-features' ],
)
);
}
add_action( 'init', 'ruth_patterns_register_block_patterns' );Y ahora sí que ya se nos muestra en nuestro editor en la categoría indicada.
Ya podemos añadirlo a cualquier nueva página que creemos y luego hacer las modificaciones que nos parezcan pertinentes, tal y como puedes ver en la sección creada en una nueva página para el lanzamiento de nuestro nuevo producto.
Propiedades del patrón de bloques
En nuestro ejemplo hemos definido las propiedades title, content y categories, pero hay más. Los detalles los encontrarás en la documentación que describe la función register_block_pattern, pero aquí te dejo un resumen:
title(requerida): el título del patrón.content(requerido): el contenido del patrón.description: un texto oculto visualmente usado para describir el patrón en el insertador. La descripción es opcional, pero se recomienda encarecidamente cuando el título no describe completamente lo que hace el patrón.categories: una serie de categorías de patrones utilizadas para agrupar los patrones de bloques. Los patrones de bloques pueden mostrarse en múltiples categorías.keywords: un conjunto de alias o palabras clave que ayuden a los usuarios a descubrir el patrón durante la búsqueda.viewportWidth: un entero que especifica el ancho del patrón en el insertador.
En el caso del registro de categorías, sólo tenemos que definir la propiedad label, ya que no tenemos propiedades adicionales.
Hoy hemos visto que crear un patrón de bloques para que lo tengas siempre disponible en tu web es bastante fácil. Alternativamente, en la próxima entrada veremos cómo podemos crear patrones sin saber nada de código. ¡No te la pierdas!
Imagen destacada de John Cameron en Unsplash.
Deja una respuesta