Como adicionar campos meta de postagem à barra lateral do documento Gutenberg

Neste post, veremos como adicionar configurações meta personalizadas de postagem à barra lateral do Gutenberg, na guia "Documento", em vez de depender da adição de meta caixas da maneira tradicional (e honestamente muito mais manual).

Se você trabalhou com o WordPress um tempo antes de Gutenberg ser uma coisa, você provavelmente está familiarizado com a adição de meta de postagem personalizada com [add_meta_box](https://developer.wordpress.org/reference/functions/add_meta_box/)(). Esta função permite que você adicione uma meta box com seu conteúdo personalizado na parte inferior ou lateral ao editar uma postagem. Este método ainda funciona, também no editor Gutenberg!

No entanto, parece um pouco estranho em comparação com o resto do conteúdo da barra lateral do Gutenberg. E para não mencionar, você precisaria escrever manualmente o código de entrada (caixa de seleção, entradas de texto etc.) com PHP e também escrever código adicional para salvá-los quando a postagem for atualizada. E se você quisesse que suas configurações de meta de postagem fossem dinâmicas (digamos que você quisesse ocultar um campo, a menos que algum outro campo fosse ativado), então você teria que enfileirar manualmente um script e sim, você adivinhou, manipular manualmente a lógica dinâmica de esconder e mostrar. Tudo isso agora está desatualizado e facilitado com o novo editor Gutenberg baseado em Javascript. Podemos facilmente fazer algo assim:

O processo

O processo é como se segue:

• Registramos cada meta-chave de postagem personalizada que queremos adicionar no PHP usando [register_post_meta](https://developer.wordpress.org/reference/functions/register_post_meta/)()e definimos como disponível na API REST do WP. Este é um passo necessário para disponibilizar a meta do post no editor Gutenberg.
• Criamos um arquivo Javascript e o enfileiramos especificamente para o editor (somente).
• Dentro do arquivo Javascript nós registramos um plugin [registerPlugin](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-plugins/#registerPlugin)()dizendo para ele renderizar nosso componente.
• Dentro desse componente podemos produzir o que precisarmos. Podemos usar os componentes internos do WordPress para renderizar facilmente diferentes tipos de configurações. E usando o pacote de dados do WordPress, podemos buscar e atualizar os meta-valores do post imediatamente à medida que eles são alterados.

Vamos direto ao assunto, começando com a parte do PHP; registrando a meta do post.

Registrando meta de postagem

Para cada meta de postagem que você deseja adicionar à barra lateral do Gutenberg, você precisará se registrar usando [register_post_meta](https://developer.wordpress.org/reference/functions/register_post_meta/)(). Isso é necessário para disponibilizá-los através da WP REST API (que Gutenberg usa) e, portanto, disponíveis em nosso Javascript.

No arquivo do seu tema functions.phpou em algum outro arquivo PHP ativo, adicione uma função ligada ao initgancho ‘ ‘. Dentro da função, você repete a register_post_meta()para cada meta de postagem personalizada que deseja adicionar. A função recebe três argumentos; O primeiro parâmetro é o tipo de postagem para o qual você deseja registrar o meta (definido como string vazia para todos os tipos de postagem). O segundo parâmetro é o nome da meta-chave para sua meta. E o terceiro é uma série de configurações. É aqui que definimos que essa meta deve ser acessível na WP REST API definindo ‘ show_in_rest‘ como true.

Por exemplo, digamos que eu queira adicionar uma ativação/desativação e uma entrada de texto na barra lateral do editor. Isso significa que eu chamo register_post_meta()de um tipo de valor booleano e de string, respectivamente. Eu também quero limitar esses post meta para postar apenas tipo ‘post’. Isso seria algo como:

Agora eu tenho uma meta-chave post _my_custom_boole _my_custom_textpronta e disponível em Gutenberg. Eu recomendo que você os renomeie para algo que faça sentido para você.

Registrando nosso plugin Javascript

Para nossa próxima etapa, adicionaremos um arquivo Javascript e nos certificaremos de enfileirar usando PHP.

Tenha em mente que eu escrevo o código Javascript na sintaxe ES6. Isso significa que eu configurei uma configuração webpack/Babel para compilar meu arquivo em um arquivo Javascript legível separado para o navegador.

Eu tenho um guia sobre como configurar isso se você não tiver certeza de como isso funciona:

Precisamos ter certeza de que o WordPress carrega nosso script no editor. Fazemos isso conectando uma função enqueue_block_editor_assetse chamando [wp_enqueue_script](https://developer.wordpress.org/reference/functions/wp_enqueue_script/)():

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

Suponho que você esteja familiarizado com como enfileirar scripts e seja capaz de substituir os valores pelos seus próprios. Como segundo parâmetro, forneço o caminho para o arquivo de compilação (não o arquivo de origem). Para garantir que nosso script não seja carregado muito cedo, defino ‘ wp-edit-post‘ como uma dependência. Esse é o pacote que precisamos para lidar com o post meta.

Agora vamos passar para a parte Javascript.

Primeiro precisamos chamar [registerPlugin](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-plugins/#registerPlugin)()e passar nosso componente para renderizar o painel na barra lateral do Documento Gutenberg. Essa função está disponível no wp.pluginspacote, então eu a destruo no topo. Gosto de manter meus arquivos organizados, então crio outro arquivo; “awp-custom-postmeta-fields.js" para conter o componente renderizado e importá-lo.

Escrevendo nosso componente

Vamos começar a criar um componente básico que não faz nada além de apenas sentar no lugar correto, então vamos tirar isso do caminho primeiro. Para renderizar um componente na barra lateral Documento do Gutenberg, usamos o [PluginDocumentSettingPanel](https://developer.wordpress.org/block-editor/reference-guides/slotfills/plugin-document-setting-panel/)componente. Podemos definir atributos como a titlee. E o que estiver dentro será renderizado na barra lateral do Documento. Por enquanto, estou apenas enviando algum texto "Olá".icon``className

Com o código acima (compilado), obtemos isso:

Incrível. No entanto, queremos adicionar algumas entradas. Mas para conectar essas entradas com nosso meta de postagem personalizado, precisamos compor nosso componente com os componentes de ordem superior withSelect(para buscar os valores meta do post) e withDispatch(para atualizar os valores meta do post). Pode parecer um pouco complexo se você não trabalhou com componentes de ordem superior antes, mas depois de entender, é bem simples.

Precisamos primeiro mudar nossa exportdeclaração. Em vez de apenas retornar nosso componente sozinho, precisamos compô-lo com withSelecte withDispatch, ambos no wp.datapacote.

Dentro withSelect()temos acesso à poderosa select()função. Usando select()podemos buscar os meta-valores da postagem atual. Também podemos buscar o tipo de postagem atual, se quisermos. Como mencionei anteriormente ao registrar meta de postagem, podemos limitar as metas de postagem a um tipo de postagem específico. Se buscarmos o tipo de postagem da postagem atual, podemos em nosso componente certificar-nos de apenas renderizar nosso código se estivermos no tipo de postagem correto. Mais sobre isso mais tarde.

Em withDispatch()podemos definir funções que podemos executar em nosso componente. Fazemos uma função que vai usar dispatch()para atualizar o post meta.

Vamos mudar a exportdeclaração para isso:

Também precisamos desestruturar estes dos seguintes pacotes no topo do arquivo:

const { compose } = wp.compose;
const { withSelect, withDispatch } = wp.data;

Com isso nosso AWP_Custom_Plugincomponente tem acesso a três novos adereços; postMetaque contém todos os meta-valores de postagem para a postagem atual; postTypeque contém o tipo de postagem da postagem atual; e por fim a função setPostMeta()que fizemos na withDispatch()qual atualizará a meta do post.

Assim, em nossa definição de componente, podemos desestruturar esses três novos adereços;

E agora podemos adicionar algumas entradas à nossa renderização, garantindo que elas exibam o valor atual e que atualizem a meta do post no evento on change. Eu registrei um booleano e uma string, então como exemplo vou adicionar um ToggleControlpara alternância e um simples TextControlpara entrada de texto.

Se você não tiver certeza sobre os componentes embutidos no WordPress, eu tenho um e-book totalmente gratuito que cobre praticamente a maioria dos componentes disponíveis no Gutenberg – incluindo quais adereços podemos definir para cada um.

Aqui está um exemplo de como nosso componente pode ficar:

Na linha #9-10e #16-17encontramos as partes críticas. Definimos o valor atual das entradas para postMeta.<your meta key here>e em seu evento onChange executamos a função setPostMeta( { <your meta key here>: ... } )para o novo valor atualizado.

Finalmente, uma palavra sobre como limitar seu componente a um tipo de postagem específico. No nosso withSelect()estamos passando o tipo de postagem do post atual no prop postType. Tudo o que precisamos fazer em nosso componente é comparar esse valor com um tipo de postagem e retornar null se não corresponder:

E é isso! Nosso código deve estar funcionando agora. O resultado final deve ser algo como:

Código final

Registrando o post meta e enfileirando o arquivo Javascript:

Os dois arquivos Javascript: