Nesta parte vamos escrever Javascript para registrar e configurar nosso bloco personalizado. Ao final vamos registrar o script com PHP e fazer o código PHP necessário para que o WordPress o reconheça como um novo bloco.
Primeiro uma nota rápida sobre como acessar as funções e componentes do WordPress Gutenberg.
O pacote global wpe a desestruturação
Quando estamos em um arquivo Javascript enfileirado no editor Gutenberg, temos acesso a um objeto/pacote global: wp. Este é um objeto Javascript muito grande e variado e contém um monte de componentes e funções úteis que usaremos para criar blocos. Ao escrever Javascript para blocos personalizados, você se referirá wpbastante.
Por isso é comum, tanto no Javascript moderno quanto no React, desestruturar o que queremos usar dele. Basicamente, significa apenas que definimos variáveis locais a partir de partes de uma estrutura maior. Por exemplo, a primeira função que usaremos é registerBlockType()aquela que existe dentro do wp.blocks. Poderíamos invocar a função assim:
wp.blocks.registerBlockType();Mas é mais fácil desestruturar assim:
const { registerBlockType } = wp.blocks;
registerBlockType();Agora você pode fazer referência à função diretamente sem prefixá-la com sua estrutura. Fica muito mais útil quando nos referimos a funções ou componentes que repetiremos com frequência.
Faremos a reestruturação nesta série e, à medida que avançamos no tutorial, veremos o quanto nosso código fica mais legível e curto.
Cadastrando um novo bloco
A função para registrar um novo bloco personalizado está registerBlockType()disponível no wp.blockspacote. Aceita dois parâmetros; primeiro uma string com o namespace e o nome do bloco e, em segundo lugar, um objeto com a configuração do bloco completo.
Gutenberg espera que todos os blocos tenham um namespace e um nome, definidos com uma barra entre eles. O namespace é para garantir que o nome do seu bloco não entre em conflito com nenhum outro bloco que possa usar o mesmo nome. Todos os blocos no WordPress usam o namespace core. Por exemplo, o bloco de parágrafo padrão no WordPress tem o nome core/paragraph. Se você escolher outro namespace, também poderá criar um bloco chamado parágrafo sem causar problemas.
Decida um namespace de versão de slug que seja exclusivo para você. Vou usar o namespace awp(versão curta de A White Pixel) nesta série.
Abra o arquivo de origem que criamos na última etapa; src/block-awhitepixel-myfirstblock.js, em um editor. Primeiro vamos chamar registerBlockTypede destructured wp.blocks, com o nome awp/firstblock. Ajuste seu nome e namespace à medida que avança.
const { registerBlockType } = wp.blocks;
registerBlockType('awp/firstblock', {
// Your block configuration and code here
});No segundo parâmetro, o objeto de configuração do bloco, precisamos definir algumas propriedades para que ele seja registrado com sucesso. Lembre-se que a configuração do bloco é um objeto, o que significa que você precisa escrever tudo como pares chave + valor, separados por vírgula. Existem algumas propriedades de configuração possíveis, então vamos passar por elas e veremos o código final no final.
Requerido: título
A primeira propriedade necessária é title. Este é o nome que aparecerá quando você selecionar entre os blocos. Defina esta propriedade como qualquer nome que você queira em uma string.
Adicionaremos o seguinte como título:
title: 'My first block',PS: Revisitaremos como escrevemos todas as strings em nosso bloco para garantir que elas possam ser traduzidas na parte 8. Mas, por enquanto, vamos simplificar e simplesmente escrever strings.
Obrigatório: categoria
A propriedade categorydefine em qual categoria de bloco seu bloco aparecerá quando você selecionar blocos para inserção no editor. Os valores possíveis são common, formatting, layout, widgets, embed.
Vamos colocá-lo em common, a primeira categoria de bloco.
category: 'common',Opcional: ícone
Se você já usou o Gutenberg, provavelmente notou que todos os blocos têm ícones. Você pode adicionar um ícone ao seu bloco com uma string que se refere a qualquer um dos Dashicons do WordPress ou pode fornecer um svgelemento personalizado.
Vou escolher apenas um dos dashicons do WordPress, o smiley – mas você pode escolher o que quiser. Observe que você pula a inclusão de "dashicons-" no nome da classe do ícone.
icon: 'smiley',Opcional: descrição
Você pode fornecer uma descrição que será exibida na barra lateral Configurações (no lado direito) quando o bloco estiver ativo.
Vou apenas adicionar um texto rápido como exemplo:
description: 'Learning in progress',Opcional: palavras-chave
O Gutenberg suporta uma funcionalidade de pesquisa ao escolher os tipos de bloco. Você pode fornecer uma matriz de possíveis correspondências na propriedade keywords. Sem keywordsvocê só encontraria seu bloco procurando pelo nome dele.
Vou adicionar examplee test, para que possamos encontrar facilmente nosso bloco personalizado ao começar a digitar uma dessas palavras-chave.
keywords: ['example', 'test'],Opcional: atributos
A propriedade attributesé uma propriedade muito importante que revisitaremos com bastante frequência nesta série de tutoriais. É aqui que você armazena seus dados estruturados e informações de entrada do usuário para o seu bloco. Você pode imaginá-lo como variáveis. Não vamos adicioná-lo por enquanto, mas definitivamente voltaremos a isso em breve.
(Tipo de) obrigatório: editar e opcional: salvar
Dentro das propriedades edite saveé onde você adicionará todo o seu código tanto para a saída do editor quanto para a renderização do front-end. Ambas as propriedades esperam uma função que deve retornar alguma saída.
A propriedade editdescreve a estrutura do seu bloco dentro do editor. A savepropriedade lida basicamente com duas coisas; a saída do seu bloco no frontend, mas também a estrutura de como seu bloco é salvo no banco de dados. Você trabalhará principalmente, editpois é aqui que você adiciona entradas para inserir ou escolher coisas e atualizar os dados do bloco. A savefunção não deve atualizar ou editar os dados de forma alguma, deve apenas produzir.
Gutenberg precisa ser capaz de reconstruir seu bloco com todas as suas configurações no editor a partir do que é gerado na savefunção (e atributos). Se Gutenberg abrir um post onde a saída do bloco salvo anteriormente difere (mesmo que um pouco) do que está definido em salvar, seu bloco se tornará inválido.
Posso garantir que você encontrará muito isso ao desenvolver blocos personalizados. Quando isso acontece, você precisa remover o bloco (dos pontos na barra de ferramentas) e adicioná-lo novamente. Eu recomendo também fazer uma atualização do navegador (F5 ou CTRL+R).
O WordPress tem uma página de documentação dedicada para as funções de edição e salvamento do bloco, se você quiser saber mais.
Quanto ao nosso primeiro bloco, vamos produzir algo básico. Retornaremos o mesmo para ambos edite save; um “:)" envolto em <div>. Afinal, o ícone do bloco é um smiley.
Outras propriedades
Existem propriedades mais opcionais para registerBlockType; parent, supports, transforms, examplee styles. Vamos ignorá-los por enquanto, pois a maioria é para construção de blocos mais avançada ou personalizada. Se você estiver interessado em ler mais sobre isso, dê uma olhada na documentação do WordPress.
Código do bloco de registro final
Nosso código agora se parece com isso.
Com isso temos o suficiente para que nosso bloco seja registrado com sucesso como um bloco personalizado. Vamos ver na prática dentro do editor Gutenberg.
Você se lembrou de compilar seu Javascript? Na etapa anterior aprendemos que não podemos carregar este arquivo Javascript no Gutenberg; precisamos da versão compilada. Você normalmente desenvolveria com a npm run startexecução em segundo plano, ou você pode apenas executar npm run builduma vez agora. Isso deve compilar nosso Javascript de origem e colocá-lo onde quer que você o tenha definido para ser colocado e nomeado em seu arquivo webpack.config.js.
A parte PHP de registrar um bloco
Para cada bloco você precisa registrar o arquivo Javascript e isso é o mesmo que você registraria qualquer outro script no WordPress – usando [wp_register_script](https://developer.wordpress.org/reference/functions/wp_register_script/)(). Observe que registramos o script, não o enfileiramos. Isso ocorre porque também precisamos chamar uma função PHP para registrar cada bloco personalizado, e essa função é responsável por enfileirar o script quando necessário.
Eu prefiro manter o código relacionado ao Gutenberg em um arquivo separado em meus temas. Mas você pode, e iremos neste tutorial, simplesmente escrever todo o código PHP diretamente dentro do tema functions.phppara simplificar.
Eu recomendo usar o initgancho para sua função, e não enqueue_block_assets. Podemos colocar ambos registrando o script e registrando o bloco juntos.
A função PHP que usaremos para registrar um novo bloco é [register_block_type](https://developer.wordpress.org/reference/functions/register_block_type/)(). Da mesma forma que o Javascript registerBlockType()aceita dois parâmetros; o namespace e o nome do bloco e um array com argumentos. Certifique-se de fornecer exatamente o mesmo namespace e nome em PHP e em Javascript.
No segundo argumento existem alguns argumentos possíveis (alguns dos quais voltaremos mais tarde nesta série). Mas o mais importante é editor_scriptonde você fornece o handle (primeiro parâmetro de wp_register_script()) do script registrado.
E é isso!
Nosso bloco no editor Gutenberg
Agora, quando você atualizar seu editor em algum post, você deve encontrar nosso bloco – abrindo a categoria Comum ou pesquisando qualquer uma das palavras-chave ou nome que você forneceu.
Nosso bloco renderiza um simples “:)” tanto no editor quanto no frontend. A partir de agora você não pode editar nada no bloco, mas é isso que vamos aprender nos próximos passos!