Cómo usar variaciones de bloque en WordPress | Programar Plus

0

WordPress 5.4 se lanzó no hace mucho tiempo y, junto con otras mejoras y correcciones de errores, introdujo una característica llamada Variaciones de bloque. Tuve la oportunidad de usarlo en uno de mis proyectos recientes y estoy gratamente sorprendido de 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 comillas. 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 de modo que todos tengan un estilo diferente. Esto suena terriblemente familiar con 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 bloque aparecen en el insertador como bloques separados con nombres únicos e iconos (opcionalmente) y pueden tener atributos personalizados precargados y bloques internos.

Los estilos de bloque están diseñados para modificar 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 “Fancy Quote”. Lo hacemos ampliando el bloque central “Cita” como este ejemplo del Manual del editor de bloques:

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

Esto agrega un .is-style-fancy-quote class a la configuración del bloque Quote en el editor de publicaciones.

Captura de pantalla de las opciones de bloque en el editor de publicaciones de WordPress que resalta las opciones para un bloque de citas. Una opción de "Cita elegante" aparece en Estilos y el nombre de la clase personalizada está en un campo Clases CSS adicionales.Ahora tenemos una opción de cotización elegante en las opciones de bloque en “Estilos” y la clase se completó para nosotros.

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

Echemos un vistazo más de cerca a la API y qué pueden hacer las variaciones de bloque.

Creación de 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',
  },
);

El registerBlockVariation La función acepta el nombre del bloque (en nuestro caso es core/quote) y un objeto (o una matriz de objetos) que describe la(s) variación(es).

El código anterior no hace mucho por defecto, pero agrega “Fancy Quote” a la lista de bloques disponibles.

Mostrando la variación Fancy Quote en WordPress Block Inserter.Ahora tenemos dos bloques de “citas” diferentes disponibles para colocar en la publicación.

Para aprovechar al máximo la variación. necesitamos proporcionar más detalles en el objeto que lo describe. La lista está cubierta en la publicación Make 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 ícono en el Insertador.
  • description – Una descripción detallada de la variación. También aparece en el insertador. Si está vacío, se utilizará la descripción de bloque predeterminada. (Opcional)
  • icon – Un icono para la variación. Puede ser un slug 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. Predeterminado a false. En el caso de nuestro ejemplo, si lo configuramos en true, el bloque Fancy Quote será el único bloque Quote disponible en el insertador. (Opcional)
  • attributes – Valores que invalidan atributos de bloque. Estos son específicos de bloque. Puede configurar el level para el bloque de encabezado o height para 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. Puedes configurarlo para undefined para deshabilitar la vista previa que se muestra para el tipo de bloque. Esto es lo mismo que el campo de ejemplo en registerBlockType. (Opcional) Hay más información disponible sobre este parámetro.
  • scope – La lista de ámbitos en los que es aplicable la variación. Cuando no se proporciona, asume todos los ámbitos disponibles. Las opciones disponibles son block y 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 tiene un sistema de diseño con dos tipos de botones: Relleno y Contorno.

Dos botones, uno con relleno verde y otro con un borde verde. Ambos dicen Más información.Estilos de botones de relleno y contorno en el sistema de diseño

Qué suerte, porque estos son los estilos predeterminados para los botones en WordPress. No es necesario registrar nuevos estilos ni piratear el editor. Todo lo que tienes que hacer es escribir algo de CSS para cada estilo y terminar. La vida es buena y todo el mundo es feliz.

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

Los mismos botones verdes pero con variaciones adicionales en dos anchos diferentes para un total de seis botones.Estilos de botones de relleno y contorno con diferentes variaciones de ancho

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

  1. Escriba dos clases adicionales para los nuevos tamaños de botón (digamos, .is-wide y .is-full), luego enséñele 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 (!) nuevos estilos 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 Fill Full exactamente? ¡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
  • Cree un bloque personalizado desde cero.

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

¡Ingrese variaciones de bloque! Al agregar solo dos variaciones, Full y Wide, 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 Botones, pero de una manera ordenada y elegante que se puede colocar directamente en una publicación desde el Insertador de bloques:

Mostrando las variaciones de los botones Ancho y Completo en el insertador de bloques de WordPress.Variaciones de botones en el insertador

¡La vida es buena y todos son felices de nuevo! 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 solo agrega una clase a un bloque.
  • Demuestra cómo registrar múltiples variaciones en una sola declaración.

Caso de uso: Repetir diseños de columnas

Supongamos 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:

Mostrando tres columnas, una que dice Diseño de sitios web, otra que dice Clientes y otra que dice Rol. Cada uno representa una columna que queremos en la página.El tipo de trabajo (izquierda), para quién era (centro) y tu papel en él (derecha)

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

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

Empecemos por registrar 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 que está integrada directamente en WordPress? Hacemos eso con el icon propiedad.

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 icono:

Variación con un icono personalizado en el Block Inserter.

La siguiente cosa importante sucede cuando 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 solo 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 InnerBlocks componente. 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. De acuerdo, son unos pocos clics, pero aún más rápido que sin usar 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 icono personalizado para una variación.

Caso de uso: diseño de cuatro columnas

Ya sabe 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 construirlo. Pero esto también introduce un nuevo concepto: el alcance en el contexto de las variaciones de bloque.

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

Mostrando el bloque de columnas insertado con 5 opciones de diseño diferentes para mostrar hasta 3 columnas en diferentes anchos.Variaciones de ámbito de bloque

Supongamos que usa un diseño de cuatro columnas en su sitio web con la misma frecuencia que usa uno de dos columnas. Eso es desafortunado, 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:

Mostrando el control deslizante para cambiar el número de columnas en la configuración del bloque.

Entonces, ¿qué puedes hacer para mejorar este flujo de trabajo? Correcto, puede 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 columna.

Eso es exactamente para lo que es la opción de alcance. Si lo configuras en [block], la variación no aparecerá en el Insertador de bloques sino en las variaciones una vez 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'],
    ],
  }
);

Variación de diseño de cuatro columnas en el ámbito del bloque.¡Oye, ahora tenemos una opción de cuatro columnas!

¿No es dulce?

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

Para resumir 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 de ámbito 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:

Variación de bloque de cuatro columnas en el insertador de bloque.Tenga en cuenta que los tamaños de los íconos para las variaciones dentro del bloque y el tamaño de los íconos del bloque son diferentes. El ícono personalizado para las columnas estaba diseñado para el alcance del bloque, por eso se ve un poco fuera de lugar en este ejemplo.

Entonces, ¿qué aprendimos de este ejemplo?

  • Explica la diferencia entre el bloque y el insertador para la variación.
  • Aprendimos a usar SVG para el ícono de variación.

Ese’¡sentarse!

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

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

  • Usar Estilos de bloque si necesita alterar la apariencia del bloque y agregar una clase CSS es suficiente para eso.
  • Usar 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é buscando filtrar el bloque o crear uno nuevo desde cero.

Si tuviste la oportunidad de jugar con Block Variation, ¡déjame saber lo que piensas de ellos en los comentarios!

Recursos

  • Hacer una publicación de WordPress
  • Solicitud de extracción de GitHub #20068