¿Alguna vez se encontró en la situación en la que desea agregar su configuración personalizada a los bloques de Gutenberg de WordPress? En esta publicación entraremos en detalles sobre cómo hacerlo. Encontrará dos códigos de ejemplo de casos de uso de la vida real para agregar configuraciones personalizadas a los bloques de WordPress.

Tenga en cuenta que debido a que los bloques de Gutenberg son Javascript, modificarlos requiere que escriba el código en Javascript. Al igual que el código PHP de WordPress tiene ganchos y filtros que permiten a los desarrolladores de temas o complementos modificar su código, también hay filtros en el código Javascript de WordPress. De manera similar a la función de PHP [add_filter](https://developer.wordpress.org/reference/functions/add_filter/)(), tenemos la función de Javascript [addFilter](https://developer.wordpress.org/block-editor/packages/packages-hooks/#api-usage)().

Escribiré el código en la sintaxis de Javascript ES6, que requiere un compilador para transformarlo. Puede escribir en la sintaxis de ES5, pero recomiendo ir a ES6/ESNext. Tengo una publicación que explica cómo configurar un transformador para ES6/ESNext. También asumo que tiene cierta familiaridad con React/JSX, posiblemente alguna experiencia en cómo crear sus propios bloques de Gutenberg personalizados.

Qué puedes filtrar en los bloques de Gutenberg

No hay mucha documentación en los ganchos y filtros de Gutenberg disponibles. Pero con el propósito de agregar configuraciones personalizadas y aplicarlas de alguna manera a los bloques existentes; esto es lo que he encontrado hasta ahora. Me he centrado en agregar configuraciones simples, no operaciones que requieren cambios drásticos en los componentes o un comportamiento complejo.

Hay tres pasos para agregar configuraciones personalizadas a los bloques existentes:

Agregamos un filtro en la [registerBlockType](https://developer.wordpress.org/block-editor/developers/block-api/block-registration/#registerblocktype)matriz de configuración del bloque existente. Esto nos permite agregar nuevos atributos a la attributesmatriz, lo que nos permite guardar información adicional en el bloque. Necesitamos guardar nuestra configuración personalizada en algún lugar.
Engánchese al componente del bloque edit(el componente responsable de representar el bloque en el editor). En este gancho podemos conectarnos al Inspector (la barra lateral) y agregar nuestros propios componentes. Podemos agregar una nueva sección/panel, o podemos conectarnos a la sección "Avanzada" que siempre está presente en todos los bloques. Luego, depende de nosotros representar las entradas de configuración, como entradas de texto, casillas de verificación o lo que sea.
saveFiltra los accesorios del bloque. Podemos ajustar los accesorios para guardar, que es responsable tanto de guardar el bloque como de mostrarlo en la interfaz (fuera del editor). En nuestro caso, queremos agregar una clase o un estilo en línea.

Podemos apuntar a bloques específicos o apuntar a todos. Siempre tenemos acceso al tipo de bloque en el que estamos.

Para decirlo en otras palabras: agregamos algunas configuraciones personalizadas en Inspector y las guardamos en atributos personalizados que hemos agregado al bloque. Luego podemos influir en el nombre de la clase del bloque o en el estilo en línea (en algunos casos), según los atributos guardados. Con los nombres de clase personalizados, podemos agregar fácilmente CSS personalizado que le da un efecto visual a nuestra configuración.

Lo que no podemos hacer (¿por ahora?)

Desafortunadamente, hay algunas cosas a las que no podemos acceder con filtros en bloques existentes. En lo que respecta a agregar configuraciones personalizadas simples a los bloques, estas son cosas comunes que no podemos afectar.

Sin acceso al estilo en línea del bloque dentro del editor

En casos de configuraciones que afectan el diseño de un bloque, necesitamos agregar un estilo en línea en el nodo de ajuste del bloque. Solo el nombre de la clase no servirá. Por ejemplo, si agrega una configuración de color personalizada y el usuario selecciona un color personalizado (del selector de colores), no puede resolver esto agregando una clase; necesita un estilo en línea.

Desafortunadamente, parece que los bloques predeterminados de WordPress manejan el estilo en línea en el editor de forma completamente independiente sin opción de filtrado o "enganche". Mostraré una forma de evitar esto en el último ejemplo a continuación, pero no es ideal en todos los casos.

¿Por qué le importa que el bloque se vea diferente en el editor que en la interfaz? El objetivo de Gutenberg es implementar una forma visual de editar contenido donde lo que vemos es en realidad lo que obtenemos. Queremos lograr el mismo aspecto visual tanto en el editor como en la interfaz.

Algunos bloques no incluyen el nombre de la clase en el editor

Como se mencionó anteriormente, podemos filtrar el nombre de la clase de ajuste del bloque, ya que se trata de un accesorio que se pasa a todos los bloques de Gutenberg. Pero, desafortunadamente, hay algunos bloques que no aplican la clase del bloque en absoluto en edit. Un ejemplo es el bloque Cover. He jugado mucho con los bloques de portada como "secciones" para las portadas, y sigo teniendo problemas porque el bloque de portada crea su propia clase dentro de edit. Se salta por completo incluir la clase “global" del bloque (que es a la que tenemos acceso a través de filtros).

Pero al menos podemos estar seguros de que los nombres de clase filtrados siempre se aplican en save(frontend). Esto sucede automáticamente fuera del código específico de cada bloque.

Si me equivoco acerca de cualquiera de los anteriores, ¡POR FAVOR hágamelo saber en los comentarios a continuación! Estoy continuamente aprendiendo Gutenberg y, al mismo tiempo, Gutenberg también evoluciona. Espero que en algún momento lo anterior sea posible en algún momento o que sea posible, ¡pero solo me falta información crucial!

Con eso fuera del camino, comencemos a buscar algo de código.

Ejemplo 1: agregue un campo de alternancia para ocultar un bloque de portada en un dispositivo móvil

Supongamos que estamos desarrollando un tema en el que los bloques de portada se utilizarán para las "secciones" en la página principal. Y queremos brindarle al usuario la posibilidad de ocultar una determinada sección del dispositivo móvil. Para resolver esto, podemos agregar un campo de alternancia en la sección "Avanzado" en el Inspector del bloque Portada. Si el campo está activado, el bloque Portada obtendrá una clase personalizada adicional a la que podemos apuntar con CSS y consultas de medios.

Por cierto: ¡este es un caso en el que el problema de que el bloque de portada no aplica nuestros nombres de clase personalizados en el editor es realmente un beneficio! Imagínese si lo hiciera; ¡entonces sería imposible para el usuario editar el bloque en el editor si tiene una pantalla pequeña!

Como se mencionó anteriormente, hay tres pasos que debemos codificar. También necesitamos agregar algo de PHP para poner en cola nuestro archivo Javascript en el editor. Hagamos eso primero.

Agregando nuestro script al editor

Enganchamos una función a la acción [enqueue_block_editor_assets](https://developer.wordpress.org/reference/hooks/enqueue_block_editor_assets/). Dentro de nuestra función, ponemos en cola un script, tal como lo haríamos normalmente en wp_enqueue_scriptsHook.


add_action('enqueue_block_editor_assets', function() {
    wp_enqueue_script('awp-gutenberg-filters', get_template_directory_uri(). '/assets/js/gutenberg-filters.js', ['wp-edit-post']);
});

¡Recuerde ajustar la ruta a donde está su secuencia de comandos! Nota: si está escribiendo en ES6 con un paquete web compilando su Javascript, recuerde establecer la ruta a la compilación de su secuencia de comandos, no la fuente.

Me gusta agregar ‘ wp-edit-post‘ como una dependencia al script para asegurar que se cargue lo suficientemente tarde.

Eso es todo el PHP que necesitamos hacer. El resto está escrito en nuestro archivo Javascript.

Agregar un atributo personalizado

El primer filtro que usaremos es el objeto de configuración de los blocks.registerBlockTypefiltros .registerBlockType

Pero primero, un poco sobre agregar filtros en Javascript. Como no he encontrado ninguna buena documentación para esto, lo explicaré un poco aquí. La función addFilterestá en el espacio de wp.hooksnombres y acepta cuatro argumentos.

addFilter('hookName', 'namespace', 'functionName', 'priority');

El primer parámetro, ‘hookName’, es el nombre del filtro al que queremos engancharnos. Este es el equivalente al primer parámetro cuando se usa PHP add_filter(). El segundo parámetro, ‘espacio de nombres’, es un nombre de espacio de nombres personalizado para su código. Esto es solo para evitar la colisión de nombres. Puede configurar prácticamente cualquier cosa que desee aquí, simplemente no use el espacio de nombres de WordPress (‘wp’). Utilice una forma abreviada de su nombre o nombre del proyecto. El tercer parámetro, ‘functionName’, es la función enganchada, que es lo mismo que el add_filter()segundo argumento de PHP. Y finalmente el cuarto parámetro, ‘prioridad’, es opcional. Nuevamente, esto es lo mismo que el add_filter()tercer argumento de PHP.

El proceso de filtros en Javascript es el mismo que en PHP. Definimos una función que necesita devolver la variable filtrada. A veces, la variable es una cadena, un objeto o un componente. Dentro de la función modificamos la variable como mejor nos parezca.

En nuestro caso, queremos agregar un nuevo atributo al attributeobjeto del bloque. Llamaremos al nuevo atributo hideOnMobiley estableceremos su tipo en boolean. Esto se hace así:


function addCoverAttribute(settings, name) {
    if (typeof settings.attributes !== 'undefined') {
        if (name == 'core/cover') {
            settings.attributes = Object.assign(settings.attributes, {
                hideOnMobile: {
                    type: 'boolean',
                }
            });
        }
    }
    return settings;
}
 
wp.hooks.addFilter(
    'blocks.registerBlockType',
    'awp/cover-custom-attribute',
    addCoverAttribute
);

En la línea #3, nos aseguramos de apuntar solo a bloques de tipo ‘ core/cover‘. El segundo argumento para blocks.registerBlockTypefiltrar es convenientemente el nombre del bloque. Luego agregamos un nuevo elemento de objeto al settings.attributesobjeto. Finalmente nos aseguramos de devolver la variable filtrada, settings.

En este punto visualmente nada ha cambiado en Gutenberg. Pero todos los bloques Cover ahora tienen un atributo adicional que podemos usar para almacenar nuestra configuración.

Agregar configuración a Inspector (panel Avanzado)

El segundo filtro se llama y filtra el componente editor.BlockEditdel bloque. editEste filtro recibe el componente del bloque original BlockEdity devuelve un nuevo componente envuelto. Necesitamos usar wp.compose.createHigherOrderComponentpara devolver el componente envuelto.

Dentro de nuestro componente, nos aseguramos de representar el componente envuelto BlockEdit, independientemente. Pero si el bloque es de tipo Cover, también enganchamos el componente InspectorAdvancedControls(que es el panel "Avanzado" en Inspector) y agregamos un archivo ToggleControl. Escribimos ToggleControlpara mostrar el valor y actualizar el atributo personalizado que agregamos anteriormente, hideOnMobile.

No olvides devolver siempre el original BlockEdit, cosa que hacemos en line #9. En la línea #10 verificamos si el tipo de bloque es Cover y renderizamos el InspectorAdvancedControlscomponente. Dentro de aquí agregamos un ToggleControl, que es un control de entrada que se muestra como un interruptor entre verdadero o falso. Establecemos una etiqueta y conectamos su valor al hideOnMobileatributo. Si ha agregado configuraciones a Inspector anteriormente, esto debería ser bastante sencillo para usted.

Con el código anterior, ahora deberíamos obtener esto dentro del panel "Avanzado" en los bloques Inspector on Cover:

La entrada ahora actualizará nuestro atributo personalizado hideOnMobile. El último paso es hacer algo dependiendo del valor de este atributo. A partir de ahora, el atributo se guarda, pero en realidad no afecta nada.

Agregar una clase personalizada

El paso final es agregar una clase personalizada a la clase del bloque. Esto lo hacemos con el filtro blocks.getSaveContent.extraProps. Este filtro afecta a los accesorios del savecomponente del bloque. Uno de ellos es el prop className, que siempre se aplicará al frontend. Simplemente agregamos nuestra clase personalizada después si el atributo era true, y luego lo devolvemos. He decidido agregar una clase ‘ hide-on-mobile‘, pero puedes llamarla como quieras.

Este código es bastante autoexplicativo. En línea #4comprobamos si el atributo hideOnMobileexiste y es true. Si es así, agregamos una clase personalizada a la classNamecadena.

Con los tres filtros anteriores, ahora deberíamos aplicar una clase personalizada ‘ocultar en el móvil’ a nuestro bloque de portada siempre que la configuración esté activada.

Todo lo que queda es agregar algo de CSS a la hoja de estilo de la interfaz de usuario de su tema. Algo como esto;


.wp-block-cover.hide-on-mobile { display: none; }
@media (min-width: 480px) {
    .wp-block-cover.hide-on-mobile { display: block; }
}

Ejemplo 2: agregue el panel Inspector con una configuración de color de fondo personalizada para el bloque espaciador

Para el segundo caso de uso, queremos agregar configuraciones de color personalizadas al bloque espaciador. Por defecto, el bloque espaciador no tiene otras configuraciones además de su altura. Supongamos que queremos agregar un color de fondo que coloree la altura completa del bloque espaciador. Eso permite al usuario agregar "rayas" vacías y de colores dentro de su contenido. En este caso, queremos agregar la configuración de color en su propio panel separado en Inspector, según el comportamiento habitual esperado para la configuración de color.

Nota: el manejo de los colores es un poco más complicado ya que necesitamos usar un (otro) componente de orden superior withColors. Debido a que ya necesitamos implementar un componente de orden superior en el editor.BlockEditque necesitamos composemúltiples componentes. Además, necesitamos agregar dos atributos para cada configuración de color. Uno contendrá el slug de la paleta de colores y el otro contendrá el código de color hexadecimal, solo si el usuario ha optado por un color personalizado (usó el selector de color). Todo esto es un comportamiento común cuando se trabaja con withColors. Tengo una <a href="https://wordpress.mediadoma.com/es/como-agregar-configuraciones-de-color-a-su-bloque-de-gutenberg-personalizado/" title="publicación que explica cómo agregar configuraciones de color y withColorsen detalle” >publicación que explica cómo agregar configuraciones de color y withColorsen detalle si te confundes.

En segundo lugar, en este caso nos encontraremos con el problema explicado anteriormente; donde no podemos agregar el estilo en línea apropiado al editor. La solución por la que he optado en este caso es envolver el bloque espaciador dentro de un diven el editor y aplicar las clases adecuadas y el estilo en línea al envoltorio div. Esto hace que el color seleccionado sea visible en el editor cuando el bloque no está seleccionado. Sin embargo, al seleccionar el bloque, WordPress agrega su propio fondo gris claro personalizado al bloque, cubriendo nuestro color de fondo personalizado. Un CSS al editor arreglará esto. Explicaré más al final.

Los pasos son los mismos que en el ejemplo anterior. Encolamos nuestro script al editor en PHP primero. Luego en Javascript filtramos el attributesobjeto, el editcomponente de Spacer y finalmente el savecomponente de Spacer.

Agregando nuestro script al editor


add_action('enqueue_block_editor_assets', function() {
    wp_enqueue_script('awp-gutenberg-filters', get_template_directory_uri(). '/assets/js/gutenberg-filters.js', ['wp-edit-post']);
});

Recuerde ajustar la ruta a su script. Me gusta agregar ‘ wp-edit-post‘ como una dependencia al script para asegurar que se cargue lo suficientemente tarde.

Eso es todo el PHP que necesitamos hacer. El resto está escrito en nuestro archivo Javascript.

Agregar atributos personalizados

Como en el ejemplo anterior, agregamos un filtro blocks.registerBlockTypepara agregar elementos de objetos adicionales al objeto del bloque attributes.

Cuando trabajamos con withColorsnecesitamos agregar dos atributos para cada color. El nombre de nuestro atributo de color de fondo es backgroundColor, lo que significa que el segundo atributo debe tener el nombre customBackgroundColor. Todo esto se explica en mi publicación sobre el manejo de la configuración de color en Gutenberg. Ambos deben ser de tipo string, y solo aplicados a bloques de tipo Spacer.


function addSpacerAttributes(settings, name) {
    if (typeof settings.attributes !== 'undefined') {
        if (name == 'core/spacer') {
            settings.attributes = Object.assign(settings.attributes, {
                backgroundColor: {
                    type: 'string',
                },
                customBackgroundColor: {
                    type: 'string'
                }
            });
        }
    }
    return settings;
}
 
wp.hooks.addFilter(
    'blocks.registerBlockType',
    'awp/spacer-background-attribute',
    addSpacerAttributes
);

Agregue el panel ColorSettings al Inspector

El segundo paso es agregar un panel de configuración de color al Inspector para el bloque espaciador filtrando editor.BlockEdit.

Necesitamos usar composepara combinar el componente de orden superior devuelto por este filtro y withColors. En otras palabras, simplemente envolvemos el componente devuelto en withColors. Como parámetro withColorsproporcionamos nuestro atributo backgroundColor.

Dentro del componente envuelto nos aseguramos de regresar siempre BlockEdit(línea #9y #39para bloques espaciadores). Para el bloque de tipo espaciador, también enganchamos InspectorControlspara agregar un PanelColorSettingspara nuestra elección de color. Este es el procedimiento estándar para agregar configuraciones de color.

En línea #17 - 34generamos manualmente la clase necesaria y/o el estilo en línea. Luego, en la línea #38, agregamos un div envolvente BlockEditcon esas clases y estilos en línea.

El resultado es un nuevo panel de configuración de color en Inspector para bloques espaciadores, totalmente funcional.

La elección de un color de paleta o un color personalizado se verá afectado en el div de envoltura dentro del editor. ¡Pero solo puede verlo cuando anula la selección del bloque espaciador!

Esto sucede porque WordPress aplica su propio estilo al seleccionar un bloque espaciador. Lo arreglaremos al final, primero solo necesitamos aplicar la misma clase y/o estilo en línea también en la interfaz.

Agregue una clase personalizada y un estilo en línea para guardar

Finalmente, debemos filtrar blocks.getSaveContent.extraPropsy aplicar la clase necesaria y/o el estilo en línea para la interfaz. Nuevamente, esto es muy similar a lo que hicimos en el ejemplo 1 anterior. Si se eligió un color de paleta, debemos agregar un nombre de clase que siga los estándares de WordPress para la configuración de color (" has-<PALETTESLUG>-background-color"). Si se eligió un color personalizado, debemos agregar un estilo en línea con el color hexadecimal.

Nota: si necesita manejar mucho los nombres de clase, le recomiendo importar la classnamesbiblioteca. Esto se utiliza mucho en Gutenberg porque simplifica mucho la configuración de los nombres de clase adecuados. El siguiente código asume que no lo ha hecho y compone el nombre de la clase manualmente.


function applySpacerBackground(props, blockType, attributes) {
    if (blockType.name == 'core/spacer') {
        const { backgroundColor, customBackgroundColor } = attributes;
 
        // For improved class name handling, use classnames library. Or do it manually like..
        let className = (props.className != undefined)? props.className: '';
        if (backgroundColor != undefined) {
            className += ' has-' + backgroundColor + '-background-color';
        }
        props.className = className;
        if (customBackgroundColor != undefined) {
            Object.assign(props, { style: { ...props.style, backgroundColor: customBackgroundColor }});
        }
    }
    return props;
}
 
wp.hooks.addFilter(
    'blocks.getSaveContent.extraProps',
    'awp/spacer-apply-class',
    applySpacerBackground
);

¡Con el código anterior, la interfaz ahora representará perfectamente los bloques espaciadores con nuestra elección de color personalizada!

La solución final (opcional) es agregar algo de CSS al editor. Deberá agregar CSS en línea o una hoja de estilo del editor. Por ejemplo, podría poner en cola una hoja de estilo en el mismo gancho de PHP que usamos para poner en cola nuestro archivo Javascript. No entraré en detalles sobre cómo hacer esto; pero el CSS que necesitará es algo como el siguiente. Todo lo que hace es establecer el espaciador background-coloren el color heredado (se heredará de nuestro div de envoltura) cuando se selecciona el bloque:


.block-library-spacer__resize-container.is-selected { 
    background-color: inherit; 
}

PD: Tenga en cuenta que esto está sujeto a cambios en el futuro. Gutenberg todavía está en gran evolución.

Conclusión

En esta publicación, hemos aprendido dos métodos para implementar configuraciones personalizadas en los bloques existentes de WordPress Gutenberg. Es totalmente posible para configuraciones simples que quizás solo requieran una clase o un estilo en línea. ¡Hemos analizado las advertencias, que espero que se solucionen en versiones posteriores de Gutenberg!

Fuente de grabación: awhitepixel.com