La guía completa de patrones de bloques de Gutenberg (II)

Esta publicación es la segunda parte de la Guía completa sobre patrones de bloques de Gutenberg, que incluye los siguientes puntos:

1. Introducción a los patrones de bloques
2. Insertar un patrón en una página
3. Patrones predefinidos y otros disponibles en directorios
4. Agregue patrones disponibles en directorios a su sitio
5. Cómo crear un patrón desde cero
6. Cómo crear un patrón si no eres desarrollador
7. Cómo convertir bloques reutilizables en patrones de bloques
8. Temas que usan patrones de bloques
9. Documentación oficial.

En la primera parte vimos los primeros 4 puntos de todos los temas tratados en la guía: qué es un patrón de bloque, cómo insertar patrones predefinidos 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 no se almacenará en nuestra biblioteca de patrones para uso futuro.

Si queremos añadir un nuevo patrón a nuestra biblioteca de patrones de Gutenberg, debemos crear y registrar dicho patrón. Es bastante sencillo, aunque necesitas algunas habilidades básicas de codificación. Si este no es su caso, no se preocupe, ya que más adelante aprenderemos cómo lograr el mismo resultado sin necesidad de codificación.

5. Crea un nuevo patrón

Para crear un patrón de bloques, debe usar la API de patrones de bloques. Específicamente, la función PHP register_block_pattern() . Veamos brevemente los diferentes pasos que debemos seguir con un ejemplo sencillo.

Pero antes de comenzar, permítanme agregar una nota al margen. Al personalizar WordPress usando fragmentos de código, siempre debe preguntarse dónde debe escribir dicho fragmento. La mayoría de los tutoriales recomiendan el archivo functions.php de su tema activo, ya que es la solución más fácil para hacer el trabajo, pero David escribió esta publicación sobre cómo crear un complemento para realizar un seguimiento de todas sus personalizaciones y argumentó que esta era una mejor solución. .

Ahora, ¿qué pasa con los patrones de bloques? Puede agregar la definición de un nuevo patrón de bloque en su tema (algunos temas, como Twenty Twenty-One, ya incluyen el suyo propio), o puede agregarlo en un complemento personalizado. Seguro que encontrarás defensores y detractores de ambas soluciones, así que elige la que mejor se adapte a tus necesidades.

#1 Diseñe los bloques que formarán su patrón

Como ya mencioné en la publicación anterior, un patrón es un conjunto de bloques agrupados como quieras. Supongamos que quiero crear un patrón de bloques que pueda usar para crear una sección que describa las características básicas de un producto.

Para hacer esto, en una página que titulé "Creación de un patrón", comienzo creando un bloque de título, "Sección de 6 funciones", y luego inserto un bloque de 3 columnas.

En el primer bloque agrego una imagen y, debajo de ella, el título y la descripción de la función.

Copio la imagen, el título y la descripción en los siguientes dos bloques. Y finalmente, duplico esta fila para tener una sección que incluirá la descripción de las seis características.

Por supuesto, solo tiene sentido crear un patrón de bloques si cree que lo va a usar más de una vez.

#2 Copia el contenido de los bloques

Una vez que hemos definido el conjunto de bloques, solo tenemos que seleccionarlos con el ratón y en la barra de herramientas pulsar en Copiar .

#3 Escape del contenido HTML copiado

Para evitar problemas, necesitamos escapar del texto que acabamos de copiar, para que la computadora pueda entender caracteres especiales como saltos de línea, tabuladores, etc. Puedes escapar fácilmente un texto usando herramientas en línea como onlinestringtools.com o JSON Escape/Unescape: simplemente pega el código que habías copiado previamente y obtendrás un texto escapado correctamente.

#4 Registre el patrón

En este punto, lo único que queda es usar la función register_block_pattern() . Esta función recibe dos argumentos: el nombre del patrón y una matriz de propiedades. Al final de este post te doy más detalles sobre las propiedades que puedes definir en un patrón, pero primero veamos los pasos necesarios para crear uno.

Este es 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 puede ver en el fragmento anterior, primero especificamos un nombre único para identificar nuestro patrón ( ruth-gutenberg-blocks-patterns/section-with-six-features ), y luego especificamos una matriz con un par de propiedades: el title ("Sección con 6 funciones") que verá un usuario del patrón y el content en sí. El content es el texto del que escapamos en el paso anterior.

#5 Crea un complemento con el patrón registrado

Para tener el patrón registrado en nuestro editor, podemos crear un complemento o podemos ponerlo en nuestro tema activo. Si crea un complemento, esto es lo que necesita:

 <?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 listo! Si ahora actualizamos nuestro editor (suponiendo que haya activado el complemento, por supuesto), verá el nuevo patrón:

pero, desafortunadamente, aparece en Sin clasificar . Esto se debe a que no hemos indicado si nuestro bloque pertenece a alguna de las categorías existentes o a una nueva.

#6 Agregue una nueva categoría de patrones

Puede agregar nuevos patrones de bloques en categorías existentes o crear una categoría completamente nueva usando la función register_block_pattern_category . Esta función también toma dos argumentos: el nombre de la categoría y una serie de opciones. ¿Suena familiar?

Aquí hay un ejemplo:

 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' );

Una vez que la nueva categoría esté lista, no olvides actualizar tu patrón de bloque para que especifique explícitamente que debe incluirse en esta nueva categoría:

 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 ahí lo tienes:

Ahora podemos añadirlo a cualquier página nueva que creemos y luego hacer las modificaciones que creamos oportunas, como puedes ver en la sección creada en una página nueva para el lanzamiento de nuestro nuevo producto:

Propiedades del patrón de bloques

En nuestro ejemplo, hemos definido las propiedades de title , content y categories de un patrón de bloque, pero hay más. Encontrará detalles en la documentación que describe la función register_block_pattern , pero aquí hay un resumen:

• title (obligatorio): el título del patrón.
• content (obligatorio): el contenido del patrón.
• description : un texto visualmente oculto que se utiliza para describir el patrón en el insertador. La descripción es opcional, pero se recomienda enfáticamente cuando el título no describe completamente lo que hace el patrón.
• categories : una serie de categorías de patrones que se utilizan para agrupar patrones de bloques. Los patrones de bloques se pueden mostrar en varias categorías.
• keywords : un conjunto de alias o palabras clave que ayudan 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ía, solo tenemos que definir una propiedad de label , ya que no hay más accesorios.

Hoy hemos visto que crear un patrón de bloques para que siempre lo tengas disponible en tu web es bastante fácil. En el próximo post veremos cómo podemos crear patrones sin saber nada de código. ¡No te lo pierdas!

Imagen destacada de John Cameron en Unsplash.