Cómo utilizar variaciones de bloques en WordPress

WordPress 5.4 se lanzó no hace mucho y, junto con otras mejoras y correcciones de errores, introdujo una función llamada Block Variations. Tuve la oportunidad de usarlo en uno de mis proyectos recientes y estoy gratamente sorprendido con lo inteligente que es esta característica. De hecho, creo que no ha recibido la atención que merece, por eso decidí escribir este artículo.

¿Qué es una variación de bloque?

Las variaciones de bloques permiten a los desarrolladores definir instancias de bloques existentes. Un ejemplo que verá a continuación es un bloque de cotizaciones. Quizás su sitio tenga tres variaciones de cómo mostrar una cotización en su sitio. Se puede crear una variación de bloque para cada uno para que todos tengan un estilo diferente. Esto suena tremendamente familiar a cómo funcionan los estilos de bloque, pero el concepto de variaciones va un poco más allá, como veremos.

¿En qué se diferencian las variaciones de bloque de los estilos de bloque?

Buena pregunta. Las variaciones de bloques aparecen en el insertador como bloques separados con nombres únicos y (opcionalmente) íconos y pueden tener atributos personalizados precargados y bloques internos.

Los estilos de bloque están diseñados para alterar el aspecto del bloque. De hecho, un estilo de bloque es una forma elegante de agregar una clase personalizada a un bloque usando las opciones de bloque en el editor de publicaciones.

La diferencia es clara cuando consideras cómo se usa cada uno en el editor de publicaciones. Digamos que registramos un nuevo estilo de bloque llamado “Cita elegante”. Lo hacemos ampliando el bloque principal “Cita” como en este ejemplo del Manual del editor de bloques:

wp.blocks.registerBlockStyle(  'core/quote',  {    name: 'fancy-quote',    label: 'Fancy Quote'  },);

Esto agrega una .is-style-fancy-quoteclase a la configuración del bloque de cotizaciones en el editor de publicaciones.

Aunque parezca que haría lo mismo (lo que técnicamente puede hacer), se puede usar una variación de bloque para completar previamente atributos personalizados (incluidas clases personalizadas) y bloques internos. En realidad, están registrados como bloques separados.

Echemos un vistazo más de cerca a la API y lo que pueden hacer las variaciones de bloques.

Crear una variación de bloque

La API para registrar variaciones de bloque es muy similar a la del estilo de bloque que acabamos de ver:

wp.blocks.registerBlockVariation(  'core/quote',  {    name: 'fancy-quote',    title: 'Fancy Quote',  },);

La registerBlockVariationfunción acepta el nombre del bloque (en nuestro caso es núcleo/cita) y un objeto (o una matriz de objetos) que describe las variaciones.

El código anterior no tiene mucha forma predeterminada, pero agrega “Cita elegante” a la lista de bloques disponibles.

Para aprovechar al máximo la variación. Necesitamos proporcionar más detalles en el objeto que lo describe. La lista se trata en la publicación Crear WordPress, pero la compartirá aquí y proporcionará comentarios adicionales.

• name– El nombre único y legible por máquina de la variación. Siguiendo los ejemplos en Github y Make post, es seguro asumir que la mejor práctica es usar kebab-case para nombrar variaciones.
• title– Un título de variación legible por humanos. Esto es lo que aparece debajo del icono en el Insertador.
• description– Una descripción detallada de la variación. También aparece en el Inserter. Si está vacío, se utilizará la descripción de bloque predeterminada. (Opcional)
• icon– Un icono para la variación. Puede ser una barra de Dashicons, un SVG o un objeto. Sigue el mismo patrón de declaración que en registerBlockType. (Opcional)
• isDefault– Indica si la variación actual es la predeterminada. El valor predeterminado es false. En el caso de nuestro ejemplo, si lo configuramos en true, el bloque Cita elegante será el único bloque de Cita disponible en el insertador. (Opcional)
• attributes– Valores que anulan los atributos del bloque. Estos son específicos de cada bloque. Puede configurar el levelbloque Encabezado o heightel Espaciador, por ejemplo.
• innerBlocks– Configuración inicial de bloques anidados. Solo se aplica a bloques que permiten bloques internos en primer lugar, como Columnas, Portada o Grupo. Cubriremos esto en uno de los ejemplos. (Opcional)
• example– El ejemplo proporciona datos estructurados para la vista previa del bloque. Puede configurarlo undefinedpara deshabilitar la vista previa que se muestra para el tipo de bloque. Este es el mismo que el campo de ejemplo en registerBlockType. (Opcional) Hay más información disponible sobre este parámetro.
• scope– La lista de ámbitos donde es aplicable la variación. Cuando no se proporciona, asuma todos los ámbitos disponibles. Las opciones disponibles son blocky inserter. Cubriremos esto en detalle en uno de los ejemplos.

Muchos de ustedes se preguntarán por qué necesitamos esta capa adicional de abstracción. Permítanme intentar responder eso con algunos casos de uso (uno de mi proyecto reciente).

Caso de uso: Botones con diferentes anchos

Digamos que tienes un sistema de diseño con dos tipos de botones: Relleno y Contorno.

Tienes suerte, porque estos son los estilos predeterminados para los botones en WordPress. No es necesario registrar ningún estilo nuevo ni piratear el editor. Todo lo que tienes que hacer es escribir algo de CSS para cada estilo y dar por terminado el día. La vida es buena y todos son felices.

Pero luego vuelves a mirar las especificaciones de diseño y notas que hay un pequeño giro. Los botones vienen en tres anchos: Regular, Ancho y Completo.

¡Maldita sea! Estás un poco molesto porque ahora tienes dos opciones:

1. Escriba dos clases adicionales para los nuevos tamaños de botones (por ejemplo, .is-widey .is-full), luego enseñe al cliente a usar el panel Avanzado en el editor para agregar esas clases y escriba un manual donde explique lo que hace cada clase. O…
2. Registre cuatro (!) estilos nuevos que van en las opciones de Bloque: Relleno ancho, Relleno completo, Contorno ancho y Contorno completo.

Ninguna de esas opciones es exactamente elegante. (Por cierto, ¿qué es exactamente Fill Full? ¡Un bocado bastante desafortunado!)

Hay dos opciones más que no incluí en la lista:

• Filtre el bloque de botones y agréguele un control de ancho personalizado
• Crea un bloque personalizado desde cero.

Obviamente, se sienten como cargas pesadas para una tarea tan simple.

¡Ingrese las variaciones de bloques! Al agregar solo dos variaciones, Completa y Ancha, podemos mantener las cosas limpias y simples:

wp.blocks.registerBlockVariation(  'core/buttons',  [    {      name: 'wide',      title: 'Wide Buttons',      attributes: {        className: 'is-wide'      },  },  {      name: 'full',      title: 'Full Buttons',      attributes: {        className: 'is-full'      },    }  ]);

Esto es lo mismo que agregar una clase personalizada al bloque de Botones, pero de una manera ordenada y elegante que se puede colocar directamente en una publicación desde Block Inserter:

¡La vida es buena y todos son felices otra vez! Entonces, ¿qué aprendimos de este ejemplo?

• Muestra que las variaciones de bloque no están diseñadas para reemplazar los estilos de bloque. De hecho, pueden funcionar bastante bien juntos incluso si la variación simplemente agrega una clase a un bloque.
• Muestra cómo registrar múltiples variaciones en una sola declaración.

Caso de uso: repetir diseños de columnas

Digamos que es diseñador y tiene un sitio web de cartera con estudios de casos. Cada estudio de caso tiene una sección de introducción con el nombre del proyecto, información del cliente y una descripción de su función en el proyecto. Podría verse algo como esto:

El problema es que es un poco tedioso crear esta parte del diseño cada vez que crea un nuevo estudio de caso de cartera, especialmente porque los encabezados Cliente y Mi función nunca cambian. Sólo estás editando el título principal y dos párrafos.

Con Variaciones de bloque, puede crear una variación de un bloque de Columnas principal llamado Introducción al proyecto que tendrá las columnas y los bloques internos ya definidos. Este ejemplo es un poco más complicado, por lo que lo desarrollaremos paso a paso.

Comencemos registrando la variación:

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

Estamos llevando este ejemplo un poco más allá que el primero, entonces, ¿por qué no agregar un ícono de cartera personalizado de la biblioteca Dashicons integrada directamente en WordPress? Eso lo hacemos con la iconpropiedad.

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

Esto hará que el bloque esté disponible en el menú de bloques con nuestro ícono:

Lo siguiente importante sucede en dónde agregamos bloques internos:

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

Pero esto sólo nos da tres columnas vacías. Agreguemos contenido inicial y bloques internos a cada uno de ellos. Podemos usar el mismo patrón que usamos para declarar una plantilla de bloque en el InnerBlockscomponente. Podemos agregar un objeto con atributos de bloque como segundo elemento en la matriz que describe el bloque y una matriz de bloques internos como tercer elemento.

La primera columna se verá así:

['core/column', {}, [  ['core/heading', { level: 2, placeholder: 'Project Title'} ],]]

…y la variación del bloque completo es así:

wp.blocks.registerBlockVariation (  'core/columns', {    name: 'project-intro',    title: 'Project Intro',    icon: 'portfolio',    scope: ['inserter'],    innerBlocks: [      ['core/column', {}, [        ['core/heading', { level: 2, placeholder: 'Project Title' }],      ]],      ['core/column', {}, [        ['core/heading', { level: 3, content: 'Client' }],        ['core/paragraph', { placeholder: 'Enter client info' }],      ]],      ['core/column', {}, [        ['core/heading', { level: 3, content: 'My Role' }],        ['core/paragraph', { placeholder: 'Describe your role' }],      ]],    ],  });

Genial, ahora podemos insertar toda la sección con un solo clic. Vale, son unos pocos clics, pero aún más rápido que sin utilizar las variaciones.

Entonces, ¿qué aprendimos de este ejemplo?

• Y demostraciones de cómo usar los bloques internos dentro de la variación.
• Muestra cómo definir un ícono personalizado para una variación.

Caso de uso: diseño de cuatro columnas

Ya sabes que las columnas son un tipo de bloque predeterminado y que hay varias opciones para diferentes tipos de columnas. Un diseño de cuatro columnas no es uno de ellos, así que podemos crearlo. Pero esto también introduce un nuevo concepto: el alcance en el contexto de variaciones de bloques.

Algunos bloques centrales, como Columnas, ya ofrecen variaciones listas para usar. Puede elegir uno de ellos después de insertar el bloque en la página:

Supongamos que utiliza un diseño de cuatro columnas en su sitio web con tanta frecuencia como uno de dos columnas. Esto es lamentable, porque no hay un botón de acceso directo para crear un diseño de cuatro columnas. Crear uno es un poco molesto porque se necesitan clics adicionales para llegar al control Columnas después de insertar el bloque:

Entonces, ¿qué puedes hacer para mejorar este flujo de trabajo? Bien, puedes agregar una variación de bloque que creará un diseño de cuatro columnas. La única diferencia esta vez, en comparación con los ejemplos anteriores, es que tiene mucho más sentido incluir esta variación dentro del marcador de posición del bloque, junto a todos los demás diseños de columnas.

Para eso es exactamente la opción de alcance. Si lo configura en [block], la variación no aparecerá en el Insertador de bloques sino en las variaciones una vez que se haya insertado el bloque.

wp.blocks.registerBlockVariation(  'core/columns', {    name: 'four-columns',    title: 'Four columns; equal split',    icon: svg ... /,    scope: ['block'], // Highlight    innerBlocks: [      ['core/column'],      ['core/column'],      ['core/column'],      ['core/column'],    ],  });

¡¿No es dulce?!

Omití el código SVG completo para el ícono, pero está disponible si lo necesita.

En resumen scope: si no se declara, la variación aparecerá en el Insertador de bloques y dentro del marcador de posición del bloque, específicamente para los bloques que admiten variaciones con alcance de bloque.

Si tuviéramos que eliminar el parámetro de alcance del ejemplo anterior, así es como aparecería la variación en el insertador:

Entonces, ¿qué aprendimos de este ejemplo?

• Explica la diferencia entre el alcance del bloque y del insertador para la variación.
• Aprendimos a usar SVG para el icono de variación.

¡Eso es todo!

Como puede ver, las variaciones de bloques son bastante poderosas para crear muchas cosas, desde diferentes variaciones de botones hasta diseños de página completos.

Me gustaría concluir esto con un resumen rápido de las diferentes API para personalizaciones de bloques y cuándo usarlas:

• Utilice Estilos de bloque si necesita modificar la apariencia del bloque y agregar una clase CSS es suficiente para eso.
• Utilice variaciones de bloque si necesita especificar los atributos predeterminados para el bloque y/o agregarle bloques internos.
• Si eso no es suficiente y necesita cambiar el marcado del bloque, probablemente esté pensando en filtrar el bloque o crear uno nuevo desde cero.

Si has tenido la oportunidad de jugar con Block Variation, ¡déjame saber qué piensas de ellos en los comentarios!

Recursos

• Hacer una publicación en WordPress
• Solicitud de extracción de GitHub n.° 20068