Adicione uma barra lateral do inspetor personalizado no WordPress Gutenberg com o Post Meta

Neste tutorial, veremos como adicionar uma barra lateral personalizada ao Inspetor (barra lateral direita) no WordPress Gutenberg. Dentro vamos implementar um campo conectado a um post meta. Tudo é implementado com Javascript, dentro do editor Gutenberg, e é uma alternativa para adicionar metaboxes da maneira tradicional.

Atenção!

Este é um tutorial sobre como criar sua própria barra lateral personalizada. Mas se você estiver interessado em apenas adicionar meta/configurações à barra lateral padrão do Inspetor (guia "Documento"), tenho um tutorial exatamente para isso:

O que vamos criar

O WordPress Gutenberg permite que os desenvolvedores criem barras laterais personalizadas usando a criação do chamado plug-in Javascript. (Não confundir com plugins tradicionais do WordPress). Usando um plugin Javascript podemos criar uma nova barra lateral, e também plugar no menu “Ferramentas e Opções".

Adicionaremos um novo item de menu em “Ferramentas” que abrirá nossa barra lateral personalizada. O conteúdo da barra lateral depende inteiramente de você, mas vou passar por alguns exemplos, incluindo como conectar um metacampo de postagem dentro dele.

Configurando seu Javascript

Para este tutorial, escreverei ES6/ESNext Javascript com JSX, o que significa que precisamos configurar um compilador. Se você quiser acompanhar e não escrever Javascript ES5, você precisará configurar um ambiente de desenvolvimento que compila seu Javascript à medida que avança. Se você não estiver familiarizado com isso, siga meu post explicando como configurar isso e depois volte aqui.

Eu configurei meu webpack.config.jspara compilar meu arquivo Javascript de origem no arquivo /assets/js/sidebar-plugin.js. Este arquivo compilado é o que precisamos para enfileirar no editor Gutenberg. Enquanto escrevo este código, iniciei o compilador de tempo de execução que recompila o Javascript toda vez que salvo alterações no código-fonte (npm run start). Tudo isso é explicado em profundidade no tutorial mencionado anteriormente.

Estou escrevendo isso em um tema, mas funciona da mesma forma em um plugin. Apenas lembre-se de ajustar os caminhos ao adicionar o script ao editor.

Adicionando o script ao editor

Para adicionar nosso script ao editor Gutenberg, precisamos escrever um pouco de PHP. Se você estiver em um tema, functions.phpé um bom lugar para começar, ou em algum lugar em seus arquivos de plugin. Observe que precisamos adicionar o script compilado final, não o código-fonte. No meu exemplo, o Javascript compilado está localizado na pasta do meu tema /assets/js/sidebar-plugin.js.

Criamos uma função ligada ao enqueue_block_editor_assets. No interior fazemos o habitual [wp_enqueue_script](https://developer.wordpress.org/reference/functions/wp_enqueue_script/)(). Como dependências ao script adicionamos duas; wp-plugins, e wp-edit-post. Esses dois pacotes devem ser carregados antes do nosso script, pois usamos funções deles.

add_action('enqueue_block_editor_assets', function() {
    wp_enqueue_script('awp-sidebar-plugin', get_stylesheet_directory_uri(). '/assets/js/sidebar-plugin.js', ['wp-plugins', 'wp-edit-post']);
});

Como enfileiramos o script no gancho enqueue_block_editor_assets, nosso script só será carregado quando o editor Gutenberg estiver ativo. Excelente! Agora tudo está pronto para escrever nosso plugin Javascript.

Registrar um plug-in Javascript

O primeiro passo é registrar um plugin. Fazemos isso com a [registerPlugin](https://github.com/WordPress/gutenberg/tree/master/packages/plugins#registerPlugin)função em wp.plugins de dentro do wp.pluginspacote.

Como parâmetro para o registerPlugin, fornecemos um nome (certifique-se de que é único) e um objeto com configurações. No mínimo, você precisa fornecer um componente para a propriedade de renderização. Você também pode adicionar opcionalmente um ícone dos dashicons do WordPress. Lembre-se de que, se você não especificar um ícone, ele retornará ao ícone do plug-in. Para fins de demonstração, estou usando o 'carrot'ícone.

Quanto ao componente, começamos definindo um componente básico que retorna um div simples com algum texto aleatório nele. E antes de todo o código desestruturamos as funções dos pacotes que queremos usar.

Se nada acontecer (nem mesmo erros) quando você atualizar o Gutenberg, estamos prontos. Não vemos nosso componente porque não dissemos ao WordPress onde renderizá-lo. O próximo passo é se conectar ao menu personalizado da barra lateral e aos componentes do menu de ferramentas para renderizar nossas coisas.

Registrar uma barra lateral personalizada

Mas primeiro uma explicação de como Gutenberg lida com barras laterais personalizadas e por que precisamos fazer o que faremos. Quando registramos com sucesso uma barra lateral personalizada, uma coisa acontecerá automaticamente inicialmente. O Gutenberg adicionará um atalho à nossa barra lateral na barra de ferramentas superior, ao lado do menu Ferramentas. Isso acontece porque nossa barra lateral fica automaticamente “fixada”.

O problema de apenas adicionar uma barra lateral personalizada é que qualquer usuário pode “desafixar” esse atalho. Quando eles fazem isso, não há ponto de acesso para abrir a barra lateral novamente! É por isso que precisamos também adicionar um item de menu ao menu Ferramentas.

O registro de uma barra lateral personalizada é feito com o componente PluginSidebardo wp.editPostpacote. Adicionar um item de menu ao menu Ferramentas é feito com o componente apropriadamente nomeado PluginSidebarMoreMenuItem(também no wp.editPostpacote).

Para o PluginSidebarcomponente, precisamos fornecer alguns adereços. Você deve fornecer no mínimo namee title. O prop titleé autoexplicativo, esse é o nome que aparecerá no topo da barra lateral. No prop namefornecer uma lesma única. Quando você adiciona o item de menu, você precisa se referir a este slug.

Adicionar um PluginSidebarMoreMenuItemcomponente (menu de ferramentas) requer no mínimo um prop; target. Aqui você fornece o mesmo nome que você deu na nameprop da barra lateral. Como conteúdo do componente você escreve o texto que será exibido como item de menu. Normalmente, isso seria o mesmo que o da barra lateral title.

Como o React requer um único nó de encapsulamento em torno do retorno do componente, encapsulamos tudo dentro de um Fragmentcomponente (do wp.elementpacote). Também estou envolvendo minhas strings __()do wp.i18npacote para permitir a tradução.

Com o código acima, teremos as seguintes duas (provavelmente três) coisas acontecendo. Você receberá um atalho de ícone de cenoura na barra de ferramentas (se ainda não o liberou). Clicar nele abrirá a barra lateral. Você também terá um novo item de menu na barra lateral do Menu Ferramentas, sob o título “Plugins”.

Adicionando conteúdo à barra lateral

O conteúdo real da barra lateral depende inteiramente de você. Você só precisa adicionar HTML ou componentes dentro do PluginSidebarcomponente com o que quiser (no lugar do texto “Hello there.”).

Você pode notar que o conteúdo da barra lateral está sem preenchimento. Isso é intencional porque a ideia é que você crie painéis dentro dessa barra lateral. Painéis são as seções recolhíveis na barra lateral normal do Gutenberg. Esses são componentes que você pode adicionar facilmente dentro de sua barra lateral personalizada. Você pode adicionar quantos painéis quiser e eles são ótimos para agrupar coisas diferentes.

Adicionando painéis em nossa barra lateral

Vamos ver rapidamente como podemos adicionar painéis à nossa barra lateral. Se você criou seus próprios tipos de blocos personalizados, talvez esteja familiarizado com esses componentes. Usamos PanelBodye opcionalmente PanelRowdo wp.componentspacote.

Para um PanelBodycomponente, você fornece no mínimo o prop title. Você pode opcionalmente fornecer true ou false para o initialOpenprop para decidir se o painel deve ser expandido como padrão ou não. Como conteúdo dentro do componente é tudo dentro do painel.

Dentro de um PanelBodyvocê pode opcionalmente usar PanelRowcomponentes. Eles não são realmente necessários, mas podem ajudá-lo a obter um bom estilo para o conteúdo do seu painel.

Por exemplo, vamos adicionar dois painéis à nossa barra lateral personalizada.

Com este código, nossa barra lateral personalizada começa a realmente parecer que pertence ao Gutenberg!

Adicionando meta campos de postagem à barra lateral personalizada

Agora estamos realmente entrando no cerne das coisas úteis para uma barra lateral personalizada; adicionando configurações e armazenando seus valores. Mas primeiro precisamos entender como.

É muito fácil adicionar campos de configuração (entradas, caixas de seleção, campos de alternância, etc) na barra lateral usando os componentes prontos para uso nos pacotes do WordPress. No entanto, precisamos considerar como armazenar os valores. A opção óbvia é armazená-los como post meta. Mas conectar uma configuração a um meta campo de postagem requer algum código extra. Mais especificamente, precisamos usar os chamados componentes de ordem superior para buscar e atualizar o post meta dentro do Javascript. Também precisamos registrar cada meta post usando PHP e disponibilizá-los para a API REST.

Para encerrar este tutorial, demonstrarei como adicionar um post meta com chave awp_my_custom_metaque deve ser armazenada como true ou false. Na barra lateral, ele será exibido como um campo de alternância (um componente verdadeiro/falso).

Registrar meta de postagem para API REST

O primeiro passo para adicionar post meta em nosso arquivo Javascript é registrá-los e defini-los como acessíveis na API REST. Para fazer isso, voltamos ao PHP novamente.

Dentro de uma função ligada à initação usamos a [register_meta](https://developer.wordpress.org/reference/functions/register_meta/)()função. Como parâmetros, precisamos definir o tipo de objeto como ‘ post‘ porque o estamos usando como meta de postagem (não exclui, por exemplo, tipo de postagem de página). Fornecemos a meta-chave e, em seguida, uma matriz de argumentos. A coisa crítica a adicionar na matriz de argumentos é definir ‘ show_in_rest‘ como true. Post meta é comumente usado como ‘ single‘ (pense em como você usa get_post_meta()). Também definimos o type. Quanto ao nosso caso, definimos como ‘ boolean‘.

Com este código o awp_my_custom_metacampo ” post meta é acessível a partir do Gutenberg. Você precisa repetir a register_meta()meta para cada postagem que deseja adicionar em sua barra lateral.

Agora vamos voltar ao nosso Javascript.

Adicionando uma configuração à nossa barra lateral

Vamos começar com a parte fácil: Adicionando a entrada à nossa barra lateral. Mais tarde, adicionaremos mais código para realmente conectar o campo de configuração para postar meta. Devido à maneira como precisamos fazer isso, definimos um novo componente separado para nossa configuração. Portanto, dentro do painel que você deseja adicionar suas configurações, basta chamar esse novo componente.

Vamos chamar o componente CustomSidebarMetaComponent(você pode chamá-lo de algo relevante para o seu projeto). Dentro deste componente queremos renderizar um campo de alternância. Para fazer isso, usamos o ToggleControlcomponente do wp.componentspacote. Como adereços para o ToggleControl, fornecemos uma etiqueta de ajuste no titleprop. Um ToggleControl também precisa dos adereços onChangepara atualizar o valor e checkedpara o valor atual. Vamos omitir esses dois por enquanto até a próxima etapa.

Com o código acima, você deve obter um campo de alternância na barra lateral. Está desmarcado e nada acontece quando você clica nele. Esse é o próximo passo: conectá-lo ao nosso post meta.

Acessando meta de postagem com withSelect e withDispatch

Para acessar e atualizar um meta valor de postagem, precisamos usar componentes de ordem superior (HOC) para acessar a versão das lojas do WordPress (semelhante ao Redux). O WordPress nos fornece alguns HOC úteis com funções que podemos usar no wp.datapacote.

O componente de ordem superior [withSelect](https://developer.wordpress.org/block-editor/packages/packages-data/#withSelect)é fornecer ao nosso componente adereços que são, no nosso caso, buscados no post meta. Usamos isso para obter o valor do nosso post meta. Dentro withSelectpodemos usar select('core/editor').getEditedPostAttribute('meta')para buscar o meta do post atual.

Por outro lado, [withDispatch](https://developer.wordpress.org/block-editor/packages/packages-data/#withDispatch)é um componente de ordem superior que pode realizar ações. No nosso caso, queremos atualizar a meta do post quando a configuração do campo correspondente for alterada em nossa barra lateral. Dentro deste componente usamos dispatch('core/editor').editPost()para informar o WordPress para despachar uma ação. Dentro do objeto que fornecemos, informamos ao WordPress que é meta que queremos atualizar.

Finalmente, precisamos combinar withSelecte withDispatchcom nosso componente que trata o metacampo post (CustomSidebarMetaComponent). Para fazer isso, usamos o WordPress’ composedo wp.composepacote. A ideia é isso withSelecte fornecer adereços ao withDispatchnosso componente. fornece o valor do post meta como prop e fornece uma função que podemos chamar para atualizar o valor como prop. Definimos esses adereços para nosso ToggleField e, correspondentemente.CustomSidebarMetaComponent``withSelect``withDispatch``checked``onChange

Isso é muita explicação. Vejamos o código real:

Vamos começar no início. Que está no fundo. Na linha #36, alteramos o componente que renderizamos em nossa barra lateral para o componente com o qual criamos compose(na linha #15). O CustomSidebarMetacomponente combinará os componentes withSelecte withDispatche retornará o CustomSidebarMetaComponent.

O CustomSidebarMetaComponentterá acesso ao customPostMetaValueprop do withSelect, e o setCustomPostMetaprop deste withDispatchdois que usamos para o checkede onChangeprops no ToggleField.

Observe que, em linha #5, adicionamos propsparâmetros aos componentes para tornar os adereços acessíveis no componente.

Conclusão e palavras finais

Espero que este tutorial tenha sido de alguma utilidade para você. Isto é o que eu consegui compreender sobre o tema durante muita tentativa e erro. Não há quase nenhuma documentação sobre este tópico por aí ainda. Ainda estou lutando com isso, especialmente quando se trata de lidar eficientemente com vários meta-posts. Se eu conseguir aprender alguns bons truques, atualizarei este tutorial com certeza!

Espero que, seguindo este tutorial, você tenha um código que adicione com sucesso uma nova barra lateral personalizada ao editor WordPress Gutenberg e, esperançosamente, com algum conteúdo e configurações significativos. Aqui está o código final para a barra lateral personalizada com o meta campo de postagem.