Já se viu na situação em que deseja adicionar suas configurações personalizadas aos blocos Gutenberg do WordPress? Neste post vamos detalhar como fazer isso. Você encontrará dois códigos de exemplo de casos de uso da vida real para adicionar configurações personalizadas aos blocos do WordPress.

Tenha em mente que, como os blocos do Gutenberg são Javascript, modificá-los requer que você escreva o código em Javascript. Assim como o código PHP do WordPress tem ganchos e filtros que permitem que desenvolvedores de temas ou plugins modifiquem seu código, também existem filtros no código Javascript do WordPress. Da mesma forma que a função do PHP [add_filter](https://developer.wordpress.org/reference/functions/add_filter/)(), temos a função Javascript [addFilter](https://developer.wordpress.org/block-editor/packages/packages-hooks/#api-usage)().

Estarei escrevendo o código na sintaxe Javascript ES6, que requer um compilador para transformá-lo. Você pode escrever na sintaxe ES5, mas eu recomendo ir para ES6/ESNext. Eu tenho um post que explica como configurar um transformador para ES6/ESNext. Eu também suponho que você tenha alguma familiaridade com React/JSX, possivelmente alguma experiência em como criar seus próprios blocos Gutenberg personalizados.

O que você pode filtrar em blocos Gutenberg

Não há muita documentação em ganchos e filtros Gutenberg disponíveis. Mas com o propósito de adicionar configurações personalizadas e de alguma forma aplicá-las em blocos existentes; isso é o que eu encontrei até agora. Concentrei-me em adicionar configurações simples – não em operações que exigem mudanças drásticas de componentes ou comportamento complexo.

Há três etapas para adicionar configurações personalizadas a blocos existentes:

[registerBlockType](https://developer.wordpress.org/block-editor/developers/block-api/block-registration/#registerblocktype)Adicionamos um filtro no array de configurações do bloco existente. Isso nos permite adicionar novos atributos ao attributesarray, permitindo assim salvar informações adicionais no bloco. Precisamos salvar nossa configuração personalizada em algum lugar.
Conecte-se ao componente do bloco edit(o componente responsável por renderizar o bloco no editor). Neste gancho, podemos nos conectar ao Inspetor (a barra lateral) e adicionar nossos próprios componentes. Podemos adicionar uma nova seção/painel, ou podemos nos conectar à seção "Avançado" que está sempre presente em todos os blocos. Então cabe a nós renderizar as entradas de configuração, como entradas de texto, caixas de seleção ou outros enfeites.
saveFiltre os adereços do bloco. Podemos ajustar as props para save, que é responsável tanto por salvar o bloco quanto renderizá-lo no frontend (fora do editor). No nosso caso, queremos adicionar uma classe ou estilo embutido.

Podemos segmentar blocos específicos ou segmentar todos. Sempre temos acesso ao tipo de bloco em que estamos.

Em outras palavras: adicionamos algumas configurações personalizadas no Inspector e as salvamos em atributos personalizados que adicionamos ao bloco. Podemos então influenciar o nome da classe do bloco ou o estilo inline (em alguns casos), dependendo dos atributos salvos. Com os nomes de classe personalizados, podemos facilmente adicionar CSS personalizado que visualmente dá um efeito às nossas configurações.

O que não podemos fazer (por enquanto?)

Infelizmente, existem algumas coisas que não podemos acessar com filtros em blocos existentes. No que diz respeito à adição de configurações personalizadas simples aos blocos, essas são coisas comuns que não podemos afetar.

Sem acesso ao estilo embutido do bloco dentro do editor

Em casos de configurações que afetam o design de um bloco, precisamos adicionar estilo inline no nó de encapsulamento do bloco. Apenas o nome da classe não serve. Por exemplo, se você adicionar uma configuração de cor personalizada e o usuário selecionar uma cor personalizada (do colorpicker), você não poderá resolver isso adicionando uma classe – você precisa de um estilo embutido.

Infelizmente, parece que os blocos padrão do WordPress lidam com o estilo inline no editor de forma totalmente independente, sem opção de filtragem ou “ligação". Mostrarei uma maneira de contornar isso no último exemplo abaixo, mas não é ideal em todos os casos.

Por que se importar que o bloco pareça diferente no editor versus no frontend, você pode perguntar? O objetivo de Gutenberg é implementar uma maneira visual de editar conteúdo onde o que vemos é realmente o que obtemos. Queremos alcançar a mesma aparência visual tanto no editor quanto no frontend.

Alguns blocos não incluem o nome da classe no editor

Como mencionado acima, podemos filtrar o nome da classe de encapsulamento do bloco, pois este é um prop que é passado para todos os blocos do Gutenberg. Mas, infelizmente, existem alguns blocos que não aplicam a classe do bloco em edit. Um exemplo é o bloco Cover. Eu brinquei muito usando blocos Cover como “seções” para frontpages e continuo tendo problemas porque o bloco Cover constrói sua própria classe dentro do edit. Ele pula completamente a classe “global” do bloco (que é a que temos acesso por meio de filtros).

Mas pelo menos podemos ter certeza de que os nomes das classes filtradas são sempre aplicados em save(frontend). Isso acontece automaticamente fora do código específico de cada bloco.

Se eu estiver errado sobre qualquer um dos itens acima, por favor, deixe-me saber nos comentários abaixo! Estou continuamente aprendendo Gutenberg e, ao mesmo tempo, Gutenberg evolui também. Espero que em algum momento o acima seja possível em algum momento ou que seja possível, mas estou perdendo algumas informações cruciais!

Com isso fora do caminho, vamos começar a analisar algum código.

Exemplo 1: adicionar um campo de alternância para ocultar um bloco de capa no celular

Vamos supor que estamos desenvolvendo um tema onde os blocos de capa serão usados para “seções” na primeira página. E queremos fornecer ao usuário a possibilidade de ocultar uma determinada seção do celular. Para resolver isso, podemos adicionar um campo de alternância na seção “Avançado” no Inspetor do bloco de capa. Se o campo estiver ativado, o bloco Cover obterá uma classe personalizada adicional que podemos direcionar com CSS e consultas de mídia.

A propósito: Este é um caso em que o problema do bloco de capa não aplicar nossos nomes de classe personalizados no editor é realmente um benefício! Imagine se tivesse; então seria impossível para o usuário editar o bloco no editor se ele tiver uma tela pequena!

Como mencionado anteriormente, há três etapas para as quais precisamos codificar. Também precisamos adicionar algum PHP para enfileirar nosso arquivo Javascript no editor. Vamos fazer isso primeiro.

Adicionando nosso script ao editor

Conectamos uma função à ação [enqueue_block_editor_assets](https://developer.wordpress.org/reference/hooks/enqueue_block_editor_assets/). Dentro de nossa função nós enfileiramos um script, assim como normalmente faríamos no 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']);
});

Lembre-se de ajustar o caminho para onde seu script está! Nota: Se você estiver escrevendo em ES6 com webpack compilando seu Javascript, lembre-se de definir o caminho para a construção do seu script, não a fonte.

Eu gosto de adicionar ‘ wp-edit-post‘ como uma dependência ao script para garantir que ele carregue tarde o suficiente.

Isso é todo o PHP que precisamos fazer. O resto está escrito em nosso arquivo Javascript.

Adicionar um atributo personalizado

O primeiro filtro que usaremos é qual o objeto de configurações dos blocks.registerBlockTypefiltros .registerBlockType

Mas primeiro, um pouco sobre como adicionar filtros em Javascript. Como não encontrei nenhuma documentação boa para isso, vou explicar um pouco aqui. A função addFilterestá no wp.hooksnamespace e aceita quatro argumentos.

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

O primeiro parâmetro, ‘hookName’, é o nome do filtro ao qual queremos nos conectar. Este é o equivalente ao primeiro parâmetro ao usar PHP’s add_filter(). O segundo parâmetro, ‘namespace’, é um nome de namespace personalizado para seu código. Isso é apenas para evitar a colisão de nomes. Você pode definir o que quiser aqui, apenas não use o namespace do WordPress (‘wp’). Use uma forma abreviada de seu nome ou nome do projeto. O terceiro parâmetro, ‘functionName’, é a função hooked – que é o mesmo que o add_filter()segundo argumento do PHP. E, finalmente, o quarto parâmetro, ‘prioridade’, é opcional. Novamente, isso é o mesmo que o add_filter()terceiro argumento do PHP.

O processo para filtros em Javascript é o mesmo que em PHP. Definimos uma função que precisa retornar a variável filtrada. Às vezes, a variável é uma string, um objeto ou um componente. Dentro da função, modificamos a variável conforme acharmos adequado.

No nosso caso queremos adicionar um novo atributo ao attributeobjeto do bloco. Chamaremos o novo atributo hideOnMobilee definiremos seu tipo como boolean. Isso é feito assim:


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

Na linha #3, certificamo-nos de segmentar apenas blocos do tipo ‘ core/cover‘. O segundo argumento para blocks.registerBlockTypefiltrar é convenientemente o nome do bloco. Em seguida, adicionamos um novo item de objeto ao settings.attributesobjeto. Por fim, certificamo-nos de retornar a variável filtrada, settings.

Neste ponto, visualmente, nada é alterado em Gutenberg. Mas todos os blocos Cover agora têm um atributo adicional que podemos usar para armazenar nossa configuração.

Adicionar configuração ao Inspetor (painel Avançado)

O segundo filtro é chamado editor.BlockEdite filtra o componente do bloco edit. Este filtro recebe o componente do bloco original BlockEdite retorna um novo componente encapsulado. Precisamos usar wp.compose.createHigherOrderComponentpara retornar o componente encapsulado.

Dentro do nosso componente, certificamo-nos de renderizar o componente encapsulado BlockEdit, independentemente. Mas se o bloco for do tipo Cover, também conectamos ao componente InspectorAdvancedControls(que é o painel “Avançado” no Inspector) e adicionamos um arquivo ToggleControl. Escrevemos o ToggleControlpara mostrar o valor e atualizar o atributo personalizado que adicionamos anteriormente, hideOnMobile.

Não se esqueça de devolver sempre o original BlockEdit, o que fazemos na linha #9. Na linha #10 verificamos se o tipo do bloco é Cover e renderizamos o InspectorAdvancedControlscomponente. Dentro daqui adicionamos um ToggleControl, que é um controle de entrada que é exibido como uma alternância entre true ou false. Definimos um rótulo e conectamos seu valor ao hideOnMobileatributo. Se você adicionou configurações ao Inspetor antes, isso deve ser bastante simples para você.

Com o código acima, agora devemos obter isso dentro do painel “Avançado” nos blocos Inspector on Cover:

A entrada agora atualizará nosso atributo personalizado hideOnMobile. O último passo é fazer algo dependendo do valor deste atributo. A partir de agora, o atributo é salvo, mas na verdade não afeta nada.

Adicionar uma classe personalizada

A etapa final é adicionar uma classe personalizada à classe do bloco. Fazemos isso com o filtro blocks.getSaveContent.extraProps. saveEste filtro afeta os adereços do componente do bloco. Um deles é o prop className, que sempre será aplicado no frontend. Simplesmente anexamos nossa classe personalizada depois dela se o atributo for true, e depois a retornamos. Decidi adicionar uma classe ‘ hide-on-mobile‘, mas você pode chamá-la como quiser.

Este código é bastante autoexplicativo. Na linha #4verificamos se o atributo hideOnMobileexiste e é true. Nesse caso, anexamos uma classe personalizada à classNamestring.

Com todos os três filtros acima, agora devemos obter uma classe personalizada ‘hide-on-mobile’ aplicada ao nosso bloco Cover sempre que a configuração for ativada.

Tudo o que resta é adicionar um pouco de CSS à folha de estilo do frontend do seu tema. Algo assim;


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

Exemplo 2: Adicionar painel Inspetor com configuração de cor de fundo personalizada para bloco Espaçador

Para o segundo caso de uso, queremos adicionar configurações de cores personalizadas ao bloco Espaçador. Por padrão, o bloco Espaçador não possui outras configurações além de sua altura. Vamos supor que queremos adicionar uma cor de fundo que colora a altura total do bloco Espaçador. Isso permite que o usuário adicione “faixas” vazias e coloridas dentro de seu conteúdo. Nesse caso, queremos adicionar as configurações de cores em seu próprio painel separado no Inspetor, conforme o comportamento normal esperado para as configurações de cores.

Nota: O manuseio de cores é um pouco mais complicado, pois precisamos usar um (outro) componente de ordem superior withColors. Porque já precisamos implementar um componente de ordem superior no editor.BlockEditque precisamos para composevários componentes. Além disso, precisamos adicionar dois atributos para cada configuração de cor. Um conterá o slug da paleta de cores e o outro conterá o código de cor hexadecimal – somente se o usuário tiver optado por uma cor personalizada (usado o colorpicker). Esse é um comportamento comum ao trabalhar com withColors. Eu tenho um <a href="https://wordpress.mediadoma.com/pt-pt/como-adicionar-configuracoes-de-cores-ao-seu-bloco-gutenberg-personalizado/" title="post que explica como adicionar configurações de cores e withColorsem detalhes” >post que explica como adicionar configurações de cores e withColorsem detalhes se você ficar confuso.

Em segundo lugar, neste caso, nos depararemos com a questão explicada acima; onde não podemos adicionar o estilo inline apropriado ao editor. A solução que optei neste caso é envolver o bloco Spacer dentro de a divno editor e aplicar as classes apropriadas e o estilo inline ao wrapper div. Isso torna a cor selecionada visível no editor quando o bloco é desmarcado. Ao selecionar o bloco, no entanto, o WordPress adiciona seu próprio plano de fundo cinza claro personalizado ao bloco, cobrindo nossa cor de plano de fundo personalizada. Um CSS para o editor corrigirá isso. Vou explicar mais no final.

Os passos são os mesmos do exemplo acima. Enfileiramos nosso script para o editor em PHP primeiro. Então em Javascript filtramos o attributesobjeto, o editcomponente do Espaçador e finalmente o savecomponente do Espaçador.

Adicionando nosso script ao 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']);
});

Lembre-se de ajustar o caminho ao seu script. Eu gosto de adicionar ‘ wp-edit-post‘ como uma dependência ao script para garantir que ele carregue tarde o suficiente.

Isso é todo o PHP que precisamos fazer. O resto está escrito em nosso arquivo Javascript.

Adicionar atributos personalizados

Como no exemplo acima, adicionamos um filtro blocks.registerBlockTypepara adicionar itens de objeto adicionais ao objeto do bloco attributes.

Ao trabalhar com withColors, precisamos adicionar dois atributos para cada cor. O nome do nosso atributo de cor de fundo é backgroundColor, o que significa que o segundo atributo deve ser nomeado customBackgroundColor. Tudo isso é explicado no meu post sobre como lidar com configurações de cores em Gutenberg. Ambos devem ser do tipo string, e aplicados apenas a blocos do 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
);

Adicionar painel ColorSettings ao Inspetor

A segunda etapa é adicionar um painel de configurações de cores ao Inspetor para o bloco Espaçador filtrando editor.BlockEdit.

Precisamos usar composepara combinar o componente de ordem superior retornado desse filtro e withColors. Em outras palavras, nós simplesmente envolvemos o componente retornado em withColors. Como parâmetro para withColorsnós fornecemos nosso atributo backgroundColor.

Dentro do componente encapsulado, sempre retornamos BlockEdit(linha #9e #39para blocos espaçadores). Para blocos do tipo Espaçador, também conectamos InspectorControlspara adicionar um PanelColorSettingspara nossa escolha de cor. Este é o procedimento padrão de adição de configurações de cores.

Na linha #17 - 34geramos manualmente a classe necessária e/ou o estilo inline. Em seguida, na linha #38, adicionamos uma div envolvente BlockEditcom essas classes e estilos embutidos.

O resultado é um novo painel de configurações de cores no Inspector for Spacer blocks, totalmente funcional.

Escolher uma cor de paleta ou uma cor personalizada será realmente afetada na div de encapsulamento dentro do editor. Mas você só pode vê-lo quando desmarcar o bloco Espaçador!

Isso acontece porque o WordPress aplica seu próprio estilo ao selecionar um bloco espaçador. Vamos corrigi-lo no final, primeiro só precisamos aplicar a mesma classe e/ou estilo inline no frontend também.

Adicione classe personalizada e estilo embutido para salvar

Finalmente, precisamos filtrar blocks.getSaveContent.extraPropse aplicar a classe necessária e/ou o estilo inline para o frontend. Novamente, isso é muito semelhante ao que fizemos no exemplo 1 acima. Se uma cor de paleta foi escolhida, precisamos adicionar um nome de classe que siga os padrões do WordPress para configurações de cores (” has-<PALETTESLUG>-background-color“). Se uma cor personalizada foi escolhida, precisamos adicionar um estilo inline com a cor hexadecimal.

Nota: Se você precisar lidar muito com nomes de classes, recomendo importar a classnamesbiblioteca. Isso é muito utilizado no Gutenberg porque simplifica muito a definição dos nomes de classe apropriados. O código abaixo assume que você não o fez e compõe o nome da classe 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
);

Com o código acima, o frontend agora renderizará perfeitamente os blocos Spacer com nossa opção de cor personalizada!

A correção final (opcional) é adicionar algum CSS ao editor. Você precisará adicionar CSS embutido ou uma folha de estilo do editor. Por exemplo, você pode enfileirar uma folha de estilo no mesmo gancho PHP que usamos para enfileirar nosso arquivo Javascript. Não entrarei em detalhes sobre como fazer isso; mas o CSS que você precisa é algo como o abaixo. Tudo o que ele faz é definir o espaçador background-colorpara a cor herdada (ele herdará de nossa div de encapsulamento) quando o bloco for selecionado:


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

PS: Tenha em mente que isso está sujeito a alterações no futuro. Gutenberg ainda está em forte evolução.

Conclusão

Neste post, aprendemos dois métodos de implementação de configurações personalizadas para blocos existentes do WordPress Gutenberg. É totalmente possível para configurações simples que talvez requeiram apenas uma classe ou estilo embutido. Vimos as advertências, que espero que sejam corrigidas em versões posteriores do Gutenberg!

Fonte de gravação: awhitepixel.com