Como adicionar um botão ao editor Gutenberg usando @wordpress/scripts

Há quase um ano e meio, Antonio escreveu este post no blog explicando uma das dificuldades que enfrentamos ao adaptar nossos plugins ao novo editor de blocos do WordPress. O resultado de seu tutorial ficou mais ou menos assim:

Felizmente ou infelizmente, Gutenberg mudou muito neste ano e meio. A pilha de desenvolvimento vem se expandindo e melhorando e os desenvolvedores de plugins e temas tiveram que abraçar e adaptar as novas tecnologias. E aqueles de nós que também escrevem sobre nossa experiência e compartilham o que aprendemos agora são “forçados” a atualizar nossos tutoriais para que você possa se manter atualizado. Mas estamos felizes com isso!

Há algumas semanas, Ivan, um de nossos leitores, nos deixou um comentário no tutorial de Antonio pedindo ajuda. Aparentemente ele não conseguiu implementar o plugin do Antonio. E, para ser honesto, isso não me surpreende, porque as coisas mudaram muito recentemente. Então, para ajudar Ivan e todos vocês que nos lêem e querem continuar aprendendo sobre o WordPress, vamos recriar o tutorial de como adicionar um botão ao editor de blocos Gutenberg aproveitando todas as novas ferramentas que o WordPress nos oferece!

Criar um plug-in

A primeira coisa que devemos fazer é criar um plugin WordPress. Isso é bastante direto. Basicamente, tudo o que precisamos fazer é criar uma pasta em wp-content/plugins com o nome que queremos dar ao nosso plugin (por exemplo, gutenberg-button ) e, dentro dela, criar um arquivo com o mesmo nome e uma extensão .php extensão .php . Em seguida, digite o seguinte código em seu arquivo de plug-in:

Agora, vamos dar uma olhada no que o snippet anterior faz:

• Primeiro abrimos uma tag <?php . Sem surpresas aqui.
• Em seguida, neste arquivo principal, adicionamos um comentário de várias linhas. O comentário inclui várias linhas com pares “Chave/Valor”. Por exemplo, vemos como especificamos o nome do plugin ( Plugin Name ), sua versão ( Version ) ou o nome do autor ( Author ). Todas essas informações ficarão visíveis na seção Plugins do WordPress.
• Por fim, adicionamos algum código clichê:
  • especificamos um namespace (falamos sobre namespaces aqui),
  • garantimos que, se o arquivo for executado, ele será executado como parte do WordPress e
  • definimos algumas constantes sobre o plugin (que serão úteis mais adiante).

Depois de fazer tudo isso, se formos à tela Plugins do nosso WordPress, veremos que o botão Gutenberg está lá:

nós o ativamos e… voila! Claro, não vai fazer nada, mas já está lá.

Desenvolvimento de plugins JavaScript

Hoje em dia, os desenvolvedores do WordPress precisam ser proficientes em JavaScript. Essa é uma das consequências de Gutenberg estar no núcleo, eu acho. E este tutorial não é exceção.

Preparando o ambiente

Se quisermos adicionar um novo botão à interface do Gutenberg, devemos codificar esse recurso em JavaScript. Então vamos preparar o ambiente de desenvolvimento JavaScript em nosso plugin. Para fazer isso, basta executar o seguinte comando na linha de comando (certifique-se de estar em wp-content/plugins/gutenberg-button ao fazer isso):

 npm init

e siga as instruções:

 This utility will walk you through creating a package.json file. It only covers the most common items, and tries to guess sensible defaults. See `npm help json` for definitive documentation on these fields and exactly what they do. Use `npm install <pkg>` afterwards to install a package and save it as a dependency in the package.json file. Press ^C at any time to quit. package name: (gutenberg-button) version: (1.0.0) description: Adding a formatting button in Gutenberg. entry point: (index.js) ...

O resultado desse processo é um arquivo package.json . Como você verá em alguns momentos, este arquivo será extremamente útil no futuro.

Como já revelei no título deste post, usaremos @wordpress/scripts para criar nosso plugin. Então, vamos adicioná-lo como uma dependência executando o seguinte comando:

 npm install --save-dev @wordpress/scripts

Este comando fará o download de um monte de dependências dentro do nosso plugin (em node_modules ) e modificará nosso package.json para que fique claro que @wordpress/scripts agora é uma dependência de desenvolvimento.

Se você der uma olhada na documentação deste pacote, verá que ele inclui muitos scripts para construir, validar sintaxe, formatar código, etc:

 { "scripts": { "build": "wp-scripts build", "check-engines": "wp-scripts check-engines", "check-licenses": "wp-scripts check-licenses", "format:js": "wp-scripts format-js", "lint:css": "wp-scripts lint-style", "lint:js": "wp-scripts lint-js", "lint:md:docs": "wp-scripts lint-md-docs", "lint:md:js": "wp-scripts lint-md-js", "lint:pkg-json": "wp-scripts lint-pkg-json", "packages-update": "wp-scripts packages-update", "start": "wp-scripts start", "test:e2e": "wp-scripts test-e2e", "test:unit": "wp-scripts test-unit-js" } }

então vamos editar nosso arquivo package.json para que a seção "scripts" contenha todos os comandos recomendados.

Como verificar se tudo funciona…

Vamos criar uma pasta src na raiz do seu projeto e adicionar um arquivo index.js dentro dela. Este será o arquivo JavaScript principal do nosso plugin e conterá todo o seu código (você pode então organizar o código como quiser, desde que o arquivo principal seja src/index.js ).

Vamos testar se as coisas funcionam conforme o esperado adicionando a seguinte instrução index.js :

 console.log( 'Hi!' );

e compilando o projeto usando npm run build . Isso irá transpilar seu código em algo que um navegador pode executar (não era realmente necessário agora, mas será em apenas alguns minutos) e gerará um novo script dentro de uma pasta de build .

Tudo o que precisamos fazer agora é dizer ao WordPress que este script existe para que ele possa carregá-lo. Para isso, basta abrir o arquivo principal do seu plugin ( gutenberg-button.php ) e adicionar as seguintes linhas no final:

 function enqueue_script() { wp_enqueue_script( 'gutenberg-button', GUTENBERG_BUTTON_URL . '/build/index.js', [], GUTENBERG_BUTTON_VERSION ); }//end enqueue_script() add_action( 'enqueue_block_editor_assets', __NAMESPACE__ . '\enqueue_script' );

Se você prestar atenção, verá que estamos simplesmente dizendo ao WordPress para enfileirar nosso novo script /build/index.js como um recurso do editor de blocos. Dessa forma, quando um usuário acessar o editor de blocos, nosso script fará parte dos ativos que o editor incluirá.

Então vamos verificar isso. Vá para o seu painel do WordPress, edite uma postagem e veja o console JavaScript do seu navegador. Se as coisas correrem conforme o esperado, você verá "Oi!" escrito no console:

Replicando nosso tutorial para adicionar um botão ao Gutenberg

Ok, agora que vimos que podemos escrever código JavaScript e npm run build -lo em algo que nossos navegadores entenderão, é hora de replicar o tutorial de Antonio. E isso, caro leitor, é extremamente simples.

Abra o arquivo src/index.js e substitua a instrução console.log anterior pelo seguinte:

Como você pode ver, este é quase o mesmo código que Antonio escreveu alguns meses atrás. A principal diferença é o fato de que não estamos mais usando a variável global wp para acessar as funções e componentes do Gutenberg; em vez disso, agora dependemos de instruções de import . Mas fora isso, é praticamente a mesma coisa.

Depois de ter o código escrito, apenas npm run build it e pronto! Agora você tem o botão em Gutenberg:

Vamos garantir que funcione selecionando algum texto e clicando no botão:

e pronto, vemos o texto aparecer no console novamente!

Uma nota final sobre dependências…

Se você der uma olhada na pasta build , verá que @wordpress/scripts não apenas criou um arquivo index.js , mas também tem um arquivo index.asset.php . Este arquivo define um pequeno objeto com duas propriedades:

• uma lista de dependências (ou seja, scripts WordPress) exigidas pelo nosso plugin
• uma versão de compilação

Podemos (e devemos) usar essas duas propriedades ao enfileirar nosso script no WordPress se quisermos garantir que o script seja executado corretamente. Para fazer isso, basta voltar ao gutenberg-button.php e alterá-lo conforme mostrado abaixo:

 function enqueue_script() { $asset = include GUTENBERG_BUTTON_PATH . '/build/index.asset.php'; wp_enqueue_script( 'gutenberg-button', GUTENBERG_BUTTON_URL . '/build/index.js', $asset['dependencies'], $asset['version'] ); }//end enqueue_script() add_action( 'enqueue_block_editor_assets', __NAMESPACE__ . '\enqueue_script' );

Simplesmente carregue o objeto em index.asset.php usando uma instrução include e substitua a lista de dependências que tínhamos ( [] ) pelas dependências reais e use o número da compilação como a versão do plugin.

Conclusões

Criar plugins WordPress realmente úteis é complicado. Você deve entender bem como o JavaScript funciona e estar familiarizado com todos os recursos que o WordPress possui. Mas graças ao pacote @wordpress/scripts , preparar o ambiente de desenvolvimento JavaScript e construir um plugin JavaScript que possa ser executado no WordPress é mais fácil do que nunca.

Espero que tenham gostado do post de hoje. E, como sempre, se você ficar preso em algum ponto ou tiver dúvidas, deixe um comentário e nós o ajudaremos.

Ah e, a propósito, aqui está um link para o projeto, pronto para ser baixado e testado se assim o desejar. Apenas clone o projeto, npm install todas as dependências, npm run build e experimente!

Imagem em destaque por Ashim D'Silva no Unsplash.