Cómo agregar estilos de bloque personalizados a los bloques de Gutenberg de WordPress

Una característica algo menos conocida de Gutenberg es la opción de configurar diferentes estilos para los bloques. Puede registrar tantos estilos diferentes en cualquier tipo de bloque para dar al mismo bloque diseños diferentes. Los estilos posibles para los bloques se muestran como una sección en el lado derecho del editor. Cada estilo tiene su propia vista previa. Si está manejando estilos correctamente, cambiar entre estilos debería actualizar inmediatamente el diseño dentro del editor, así como en la interfaz.

La documentación de WordPress para esta función actualmente no es tan completa e informativa como podría ser. Entonces, en esta publicación, veremos en detalle cómo puede agregar sus estilos de bloque personalizados y cómo debe manejar el estilo para ellos.

La forma en que funciona esta característica es que cada vez que Gutenberg detecta que un tipo de bloque tiene registrado como mínimo un estilo, el cuadro "Estilos" aparecerá automáticamente en el lado derecho del editor. Dentro de él, el editor puede elegir entre el estilo predeterminado o cualquier otro. estilo de bloque que se ha agregado.

En versiones anteriores (al menos antes de WordPress 5.3), registrar un estilo personalizado requería que también registrara el estilo predeterminado ("sin estilo"). Afortunadamente, esto se solucionó en las versiones más recientes de WordPress, por lo que ahora solo necesita registrar sus estilos personalizados, y WordPress agregará el estilo predeterminado automáticamente.

Puede registrar estilos de bloques personalizados de dos maneras; con PHP o con Javascript. Echaremos un vistazo a ambos. Pero primero algunos a-ha’s con respecto al manejo de sus estilos.

Una nota sobre la puesta en cola de estilos para Gutenberg

Puede haber cierta confusión sobre cómo y dónde agregar sus estilos (archivos CSS); solo al editor, al frontend o a una hoja de estilo para ambos. Uno de los propósitos principales del editor de Gutenberg es asegurarse de que pueda obtener una vista previa adecuada de cómo se verá el contenido de su publicación dentro del editor. Por lo tanto, se recomienda que se asegure de que sus estilos personalizados se apliquen tanto en el editor como en la interfaz.

La forma en que maneja esto realmente depende de su proyecto y la configuración de la hoja de estilo existente. Si está desarrollando un tema completo, probablemente ya incluya estilo de bloque dentro de su hoja de estilo de interfaz. Podría considerar agregar una hoja de estilo separada que pondrá en cola solo para el editor. Pero esto puede ser difícil de mantener si agrega muchos estilos diferentes. Tendría que actualizar sus estilos en dos lugares y asegurarse de que sus resultados sean los mismos. La solución para eso sería mantener una hoja de estilo que ponga en cola tanto para el editor como para la interfaz. Pero entonces su interfaz necesitaría cargar al menos dos hojas de estilo separadas y eso podría no ser ideal.

Otra solución es usar, por ejemplo, SCSS o LESS y configurarlo @importsde tal manera que solo necesite escribir sus estilos de bloque una vez, y se aplica tanto al editor como al frontend. Como verá a continuación cuando use PHP para registrar estilos de bloque personalizados, tiene otra opción más; para agregar estilos en línea. Estos estilos se aplicarán tanto en el editor como en la interfaz. En la interfaz, WordPress los agregará como una línea personalizada <style type="text/css">...</style>dentro del encabezado.

Independientemente de cómo elija resolverlo, sepa que hay un par de ganchos nuevos para estilos de registro (y scripts) para Gutenberg. Si desea poner en cola una hoja de estilo tanto para la interfaz como para el editor, use el gancho enqueue_block_assets. Si desea agregar una hoja de estilo solo para el editor, colóquela dentro del enlace enqueue_block_editor_assets.

Cómo aplicar estilo a los estilos de bloque personalizados

Los estilos de bloque personalizados se agregarán como una clase de un determinado patrón en la etiqueta HTML más externa del bloque.

La clase CSS para los estilos de bloque se agrega en forma de " is-style-<stylename>". Si, por ejemplo, nombra su estilo " outline", el bloque obtendrá la clase " is-style-outline".

Sin embargo, puede experimentar que el editor de Gutenberg en algunos casos anulará su estilo. Recomiendo anteponer el estilo de su editor con el selector editor-styles-wrapperpara asegurarse de que sus estilos "ganen". Tenga en cuenta que esta clase no existe en la interfaz, por lo que, para estar seguro, es posible que deba agregar dos selectores, así (si está utilizando la misma hoja de estilo para el editor y la interfaz):

.is-style-colored-bottom-border, 
.editor-styles-wrapper .is-style-colored-bottom-border { 
    border-bottom: 2px solid purple;
}

Agregar estilos de bloque personalizados con PHP

Para agregar un tipo de bloque personalizado usando PHP usamos la función [register_block_style](https://developer.wordpress.org/reference/functions/register_block_style/)(). Desafortunadamente, la documentación carece de información sobre qué gancho debemos usar, pero he tenido suerte con el gancho init.

Debe conocer el nombre del espacio de nombres de Gutenberg de su tipo de bloque para agregarle un estilo personalizado. Todos los bloques estándar de WordPress tienen el espacio de nombres ” core" seguido de una /versión slug de su nombre. Por ejemplo, el nombre de Gutenberg para el bloque de párrafo estándar es core/paragraph.

El registro de un estilo de bloque personalizado se realiza en su forma más simple como esta:

El código anterior agrega un estilo de bloque personalizado al tipo de bloque de encabezado, lo que daría como resultado la clase is-style-colored-bottom-borderen cualquier encabezado que haya elegido este estilo.

Esta función le proporciona dos métodos para agregar su CSS (si no lo ha agregado de alguna otra manera); ya sea proporcionando CSS en línea como una cadena, o proporcionando un identificador de hoja de estilo registrado que WordPress pondrá en cola si es necesario.

Si desea agregar un estilo en línea (recuerde, esto afectará tanto al editor como a la interfaz), agregue el elemento ‘ inline_style‘ a la llamada de función y escriba el CSS completo como una cadena como su valor:

Si prefiere hacer que la función ponga en cola una hoja de estilo, proporcione su identificador al elemento ‘ style_handle‘.

Ajuste la ubicación de su hoja de estilo para que se ajuste a su proyecto. La hoja de estilo se aplicará tanto al editor como a la interfaz, pero esta vez la interfaz hará una solicitud por separado para incluir esta hoja de estilo. No se recomienda este método si agrega varios estilos de bloque. La interfaz se ralentizará significativamente al solicitar un montón de hojas de estilo separadas.

Agregar estilos de bloque personalizados con Javascript

Si prefiere agregar sus estilos de bloque usando Javascript, esto es tan fácil como con PHP.

Deberá poner en cola un archivo Javascript en el enlace del editor: enqueue_block_editor_assets. Su secuencia de comandos probablemente no necesitará ninguna dependencia, pero prefiero agregar al menos ‘ wp-blocks‘ como dependencia.

add_action('enqueue_block_editor_assets', function() {
    wp_enqueue_script(
        'myguten-script', 
        get_template_directory_uri(). '/assets/js/myguten.js', 
        ['wp-blocks']
    );
});

Ajuste el nombre de archivo y la ubicación para que se ajusten a su proyecto.

En su archivo Javascript, usa la función registerBlockStyle()dentro del wp.blocksobjeto para registrar estilos de bloque personalizados. Agregar el mismo estilo de bloque que hicimos en PHP anterior se vería así:

wp.blocks.registerBlockStyle('core/heading', {
    name: 'colored-bottom-border',
    label: 'Colored bottom border'
});

¡Y eso es! Pan comido.

Anular el registro de estilos de bloque

Así como puede registrar un estilo de bloque, también se puede anular el registro de un estilo de bloque. ¿Quizás quieras eliminar algunos de los estilos de bloque predeterminados de WordPress? Al igual que con el registro de estilos de bloque, también puede anular el registro de estilos de bloque con PHP o Javascript. Pero la elección entre esos dos métodos ya no es una elección de preferencia.

No puedes desregistrar un bloque con PHP si fue registrado con Javascript y viceversa. Por lo tanto, debe averiguar cómo se registró el estilo que desea eliminar y combinarlo con PHP o Javascript. Creo que todos los estilos de bloque de WordPress se agregan con Javascript (¡no me cites en esto!). Entonces, si desea eliminar algunos de ellos, deberá seguir la ruta de Javascript.

La cancelación del registro de un estilo de bloque con PHP se realiza llamando a la función unregister_block_style(), proporcionando el tipo de bloque y el nombre del estilo que desea eliminar. Por ejemplo, anular el registro del estilo agregado anteriormente en esta publicación (suponiendo que se haya registrado con PHP) se vería así:

add_action('init', function() {
    unregister_block_style('core/heading', 'colored-bottom-border');
});

La cancelación del registro de un estilo de bloque con Javascript se realiza de manera similar con la función unregisterBlockStyle()dentro del wp.blocksobjeto. Sin embargo, con Javascript hay una cuestión de qué secuencia de comandos se ejecuta primero, y es posible que encuentre problemas cuando su secuencia de comandos se ejecuta antes del registro. Para resolver esto, usamos el equivalente de Gutenberg al "documento listo" de jQuery (jQuery(document).ready(function() { ... });), y también agregamos otra dependencia a su secuencia de comandos.

Comencemos agregando una nueva dependencia de secuencia de comandos en su archivo Javascript en la cola de ‘ wp-edit-post‘:

add_action('enqueue_block_editor_assets', function() {
    wp_enqueue_script(
        'myguten-script', 
        get_template_directory_uri(). '/assets/js/myguten.js', 
        ['wp-blocks', 'wp-edit-post']
    );
});

Y dentro de su archivo Javascript, envuelva su llamada de función de cancelación de registro dentro wp.domReady(function() { ... }), así:

wp.domReady(function() {
    wp.blocks.unregisterBlockStyle('core/quote', 'large');
});

Como muestra el código anterior, con Javascript ahora podemos eliminar el estilo "Grande" de WordPress en el bloque Cita. Si intentara hacer lo mismo con PHP, no funcionaría.

Una nota al margen sobre la anulación del registro de estilos de bloque

Puede notar que, aunque haya eliminado con éxito cualquier estilo de bloque personalizado en un bloque, el cuadro "Estilos" en el editor no desaparecerá. Se queda con solo la opción "Predeterminado" dentro de él. Si desea eliminar por completo el cuadro "Estilos" para no confundir a los editores, también puede anular el registro del estilo predeterminado (p. ej wp.blocks.unregisterBlockStyle('core/quote', 'large')., ). Esto eliminará por completo el cuadro "Estilos" del editor de Gutenberg.