Construindo blocos personalizados do Gutenberg: o tutorial definitivo de desenvolvimento de blocos

Muitas pessoas reclamam dos obstáculos para começar a construir blocos e aplicativos do Gutenberg. A curva de aprendizado é íngreme, principalmente devido à dificuldade de instalação e configuração do ambiente de desenvolvimento. Além disso, um sólido conhecimento de JavaScript, Node.js, React e Redux são ingredientes obrigatórios para esta receita bastante complexa.

O manual oficial do WordPress Block Editor fornece aos desenvolvedores uma enorme quantidade de informações, mas você pode se perder nesse mar de detalhes.

E vale a pena mencionar o que Matias Ventura, arquiteto líder do projeto Gutenberg, relatou em sua entrevista ao WP Tavern:

Embora existam pessoas que podem aprender rapidamente, ainda é uma grande barreira para as pessoas. Acho que há várias camadas para isso; documentação poderia ser uma ordem de magnitude melhor em organização e apresentação. Espero que possamos fazer muito mais lá.

Com isso em mente, decidimos fornecer um tutorial passo a passo destinado a ajudar nossos leitores a começarem a desenvolver blocos do Gutenberg.

Parece interessante? Vamos mergulhar!

Pré-requisitos de desenvolvimento do bloco Gutenberg

Para este tutorial, as únicas habilidades necessárias são um bom conhecimento do desenvolvimento de plugins WordPress e pelo menos um entendimento básico de HTML, CSS, JavaScript e React.

Será um projeto ambicioso? Pode apostar que será!

Não foi fácil encontrar o compromisso certo entre completude e simplicidade ou decidir quais tópicos incluir e quais deixar de fora.

Espero que leitores intermediários e avançados nos perdoem por não nos aprofundarmos em certos conceitos, como estado React, armazenamento Redux, componentes de alta ordem e assim por diante. Esses tópicos requerem espaço e atenção adicionais e provavelmente são muito avançados para o desenvolvimento inicial de blocos (a menos que você seja um desenvolvedor React).

Pela mesma razão, não abordaremos alguns dos tópicos mais avançados relacionados ao desenvolvimento de blocos do Gutenberg, como blocos dinâmicos e caixas meta.

Com o conhecimento que você adquirirá ao final deste artigo, você poderá começar a se divertir e ser produtivo imediatamente.

Depois de começar a construir blocos, você estará pronto para melhorar ainda mais suas habilidades e construir blocos Gutenberg ainda mais avançados por conta própria.

O que é um bloco de Gutenberg?

Desde que foi lançado em dezembro de 2018, o editor de blocos foi muito aprimorado em todos os aspectos: APIs mais poderosas, uma interface de usuário mais avançada, usabilidade aprimorada, uma tonelada de novos blocos, as primeiras implementações de edição completa do site e muito mais .

Em suma, mesmo que o Gutenberg ainda esteja em desenvolvimento pesado, ele percorreu um longo caminho - e hoje, o editor de blocos é um candidato completo como um construtor de sites e páginas confiável e funcional.

Do ponto de vista de um desenvolvedor, o Gutenberg é um aplicativo de página única (SPA) baseado em React que permite que os usuários do WordPress criem, editem e excluam conteúdo no WordPress. No entanto, isso não deve fazer você pensar em uma versão aprimorada do editor de conteúdo tradicional.

Queremos deixar isso claro:

No Gutenberg, o conteúdo é dividido em blocos, que são “tijolos” que os usuários podem usar para criar posts e páginas ou seus sites inteiros.

Mas o que tecnicamente é um bloco?

Gostamos da definição do WordPress:

“Bloco” é o termo abstrato usado para descrever unidades de marcação que, compostas juntas, formam o conteúdo ou layout de uma página da web. A ideia combina conceitos do que hoje alcançamos no WordPress com códigos de acesso, HTML personalizado e descoberta incorporada em uma única API consistente e experiência do usuário.

Títulos, parágrafos, colunas, imagens, galerias e todos os elementos que compõem a interface do editor, desde os painéis da barra lateral até os controles da barra de ferramentas de bloco, são componentes do React.

Então, o que são componentes React? O W3Schools fornece a seguinte definição:

Os componentes são bits de código independentes e reutilizáveis. Eles servem ao mesmo propósito que as funções JavaScript, mas funcionam isoladamente e retornam HTML por meio de uma função render() .

Embora a experiência de edição fornecida pelo Gutenberg seja nova em comparação com o editor clássico do WordPress, a maneira como o WordPress armazena seus conteúdos no banco de dados não muda em nada. Isso porque o Gutenberg é um aplicativo que funciona dentro do WordPress, mas não altera a forma como o CMS funciona em seu núcleo.

Posts (e isso inclui posts, páginas e tipos de post personalizados) criados com Gutenberg ainda são armazenados na tabela wp_posts , exatamente como no editor clássico.

Mas em uma postagem criada com o Gutenberg, você encontrará informações adicionais na tabela que representam uma diferença fundamental entre as postagens criadas por meio do Editor Clássico versus Gutenberg.

Essas informações parecem comentários HTML e têm uma função específica: delimitar blocos:

Os delimitadores de bloco informam ao WordPress qual bloco deve ser renderizado na tela. Eles também fornecem valores para propriedades de bloco em um objeto JSON. Esses adereços ditam a forma como o bloco deve ser renderizado na tela:

Configurando seu ambiente de desenvolvimento WordPress

A configuração de um ambiente de desenvolvimento JavaScript moderno requer um sólido conhecimento de tecnologias avançadas como Webpack, React e JSX, Babel, ESLint, etc.

Intimidado? Não seja! A comunidade WordPress já veio em socorro, fornecendo ferramentas poderosas que permitem evitar um processo de configuração manual confuso.

Para manter as coisas simples, não abordaremos a transpilação neste artigo (com o qual, no entanto, recomendamos que você se familiarize depois de aprender o básico do desenvolvimento de blocos). Em vez disso, apresentaremos duas ferramentas alternativas que você pode usar para configurar de maneira rápida e fácil um ambiente de desenvolvimento JavaScript moderno em poucos minutos. Cabe a você escolher o que achar mais conveniente para o seu projeto.

Configurar um ambiente de desenvolvimento JavaScript para construir blocos Gutenberg é um processo de três etapas:

1. Instale o Node.js e o npm
2. Configure o ambiente de desenvolvimento
3. Configure o plug-in do bloco

Vamos começar.

1. Instale o Node.js e o npm

Antes de instalar seu ambiente de desenvolvimento e registrar seu primeiro bloco, você precisará instalar o Node.js e o gerenciador de pacotes Node (npm).

Você pode instalar o Node.js e o npm de várias maneiras diferentes. Mas primeiro, você pode querer verificar se o software já está instalado em sua máquina.

Para fazer isso, inicie o terminal e execute o seguinte comando:

 node -v

Se o resultado for command not found , o Node.js não está instalado em seu computador e você pode prosseguir com a instalação.

Para este artigo, escolhemos a opção de instalação mais fácil, que é o Node Installer. Tudo o que você precisa fazer é baixar a versão correspondente ao seu sistema operacional e iniciar o assistente de instalação:

Depois de instalar o Node.js, execute o comando node -v em seu terminal novamente. Você também pode executar o comando npm -v para confirmar que tem o pacote npm disponível.

Agora você está equipado com as seguintes ferramentas:

• O executor de pacotes npx Node.js (consulte a documentação). Isso permite que você execute um comando npm sem instalá-lo primeiro.
• O gerenciador de pacotes npm Node.js (consulte a documentação). Isso é usado para instalar dependências e executar scripts.

A próxima etapa é instalar o ambiente de desenvolvimento.

2. Configure seu ambiente de desenvolvimento

Depois de ter as versões mais recentes do Node.js e do npm em sua máquina local, você precisará de um ambiente de desenvolvimento para WordPress.

Você pode usar um ambiente de desenvolvimento local como o DevKinsta ou usar a ferramenta oficial do WordPress. Vamos dar uma olhada em ambas as opções.

Opção 1: Ambiente de Desenvolvimento Local (DevKinsta)

Com apenas alguns cliques, você pode instalar o WordPress localmente usando o DevKinsta, nossa moderna ferramenta de desenvolvimento local do WordPress. Ou você pode optar por uma ferramenta de desenvolvimento local diferente, como MAMP ou XAMPP:

Opção 2: wp-env

Você também pode optar pela ferramenta oficial wp-env , que fornece um ambiente de desenvolvimento local do WordPress que você pode iniciar diretamente a partir da linha de comando. Noah Alen define assim:

Os ambientes locais do WordPress agora são tão simples quanto executar um único comando. wp-env é uma ferramenta de configuração zero para ambientes WordPress locais indolores. Ele fornece decisões sobre opções para que os usuários possam ativar rapidamente o WordPress sem perder tempo. Na verdade, o objetivo é tornar esses ambientes facilmente acessíveis a todos — seja você um desenvolvedor, designer, gerente ou qualquer outra pessoa.

Se você decidir tentar, instalar wp-env requer um esforço mínimo. Basta seguir estes passos:

Etapa 1: confirmar a instalação do Docker e do Node.js

Para atender aos requisitos técnicos, primeiro você precisa ter o Docker e o Node.js instalados em seu computador. Isso porque wp-env cria uma instância do Docker executando um site WordPress. Quaisquer alterações feitas no código são refletidas imediatamente na instância do WordPress.

Etapa 2: instale @wordpress/env a partir da linha de comando

Com o Docker e o Node.js rodando no seu computador, você pode seguir em frente e instalar o ambiente de desenvolvimento do WordPress.

Você pode instalar wp-env globalmente ou localmente. Para fazer isso globalmente, você precisará executar o seguinte comando no diretório de plugins (mais sobre isso na caixa de aviso “Importante” abaixo):

 npm install -g @wordpress/env

Vamos separar isso:

• npm install instala o pacote.
• -g anexado ao comando instala o pacote especificado globalmente.
• @wordpress/env é o pacote que você vai instalar.

Para confirmar que o wp-env foi instalado com sucesso, execute o seguinte comando:

 wp-env --version

Você deve ver a versão atual do wp-env , o que significa que agora você pode iniciar o ambiente usando o seguinte comando da pasta do seu plugin:

 wp-env start

Você pode acessar o painel do WordPress usando o seguinte endereço:

• http://localhost:8888/wp-admin/

As credenciais padrão são as seguintes:

• Nome de usuário: admin
• Senha: password

Configure seu plug-in de bloco

Agora você precisa de um plugin de bloco inicial para construir. Mas, em vez de criar manualmente um plug-in de bloco de desenvolvimento com todos os arquivos e pastas necessários, você pode simplesmente executar uma ferramenta de desenvolvimento que fornece todos os arquivos e configurações necessários para iniciar o desenvolvimento de blocos.

Novamente, você tem algumas opções para escolher. Vamos dar uma olhada em cada um.

Opção 1: Configurando um Plugin de Bloco com @wordpress/create-block

@wordpress/create-block é a ferramenta oficial de configuração zero para criar blocos Gutenberg:

Criar bloco é uma maneira oficialmente suportada de criar blocos para registrar um bloco para um plugin do WordPress. Ele oferece uma configuração de compilação moderna sem configuração. Ele gera código PHP, JS, CSS e tudo o mais que você precisa para iniciar o projeto.

É amplamente inspirado no create-react-app. Grandes elogios para @gaearon, toda a equipe do Facebook e a comunidade React.

Quando seu ambiente local estiver funcionando, você pode configurar um bloco inicial simplesmente executando o npx @wordpress/create-block , e ele fornecerá todos os arquivos e pastas necessários para criar o andaime do plug-in e registrar um novo bloco .

Vamos fazer um teste para ver como funciona.

Na ferramenta de linha de comando, navegue até o diretório /wp-content/plugins/ e execute o seguinte comando:

 npx @wordpress/create-block my-first-block

Quando solicitado a confirmar, digite y para continuar:

O processo leva alguns instantes. Quando estiver concluído, você deverá obter a seguinte resposta:

E é isso!

Agora inicie seu ambiente de desenvolvimento WordPress e vá para a tela Plugins no painel do WordPress. Um novo plugin chamado “My First Block” deve ter sido adicionado à sua lista de plugins:

Ative o plug-in, se necessário, crie uma nova postagem no blog, role o inserter de bloco até a seção Widgets e selecione seu novo bloco:

Agora volte para o terminal e altere o diretório atual para my-first-block :

 cd my-first-block

Em seguida, execute o seguinte comando:

 npm start

Isso permite que você execute o plug-in no modo de desenvolvimento. Para criar o código de produção, você deve usar o seguinte comando:

 npm run build

Opção 2: Configurando um plugin de bloco com create-guten-block

create-guten-block é uma ferramenta de desenvolvimento de terceiros para construir blocos Gutenberg:

create-guten-block é zero configuration dev-toolkit (#0CJS) para desenvolver blocos WordPress Gutenberg em questão de minutos sem configurar React, webpack, ES6/7/8/Next, ESLint, Babel, etc.

Assim como a ferramenta create-block oficial, create-guten-block é baseado em create-react-app e pode ajudá-lo a gerar seu primeiro plugin de bloco sem problemas.

O kit de ferramentas fornece tudo o que você precisa para criar um plugin WordPress moderno, incluindo o seguinte:

• Suporte a sintaxe React, JSX e ES6.
• processo de construção de desenvolvimento/produção do webpack nos bastidores.
• Extras de idioma além do ES6, como o operador de propagação de objetos.
• CSS com prefixo automático, então você não precisa de -webkit ou outros prefixos.
• Um script de compilação para agrupar JS, CSS e imagens para produção com mapas de origem.
• Atualizações sem complicações para as ferramentas acima com scripts cgb de uma única dependência.

Observe a seguinte ressalva:

A desvantagem é que essas ferramentas são pré-configuradas para funcionar de uma maneira específica. Se o seu projeto precisar de mais customização, você pode “ejetar” e customizar, mas aí você precisará manter essa configuração.

Depois de ter um site local do WordPress em mãos, inicie sua ferramenta de linha de comando, navegue até a pasta /wp-content/plugins de sua instalação e execute o seguinte comando:

 npx create-guten-block my-first-block

Você terá que esperar um minuto ou dois enquanto a estrutura do projeto é criada e as dependências baixadas:

Quando o processo estiver concluído, você deverá ver a seguinte tela:

Esta próxima imagem mostra a estrutura do projeto com o terminal em execução no Visual Studio Code:

Agora volte para o seu painel do WordPress. Um novo item deve ser listado na tela Plugins — é o plugin do meu primeiro bloco :

Ative o plugin e volte ao terminal. Altere o diretório atual para my-first-block e execute npm start :

 cd my-first-block npm start

Você deve obter a seguinte resposta:

Novamente, isso permite que você execute o plug-in no modo de desenvolvimento. Para criar o código de produção, você deve usar:

 npm run build

Ative o plugin e crie um novo post ou página, então navegue pelos seus blocos e selecione o seu novo bloco Gutenberg:

Para uma visão mais detalhada ou em caso de erros, consulte a documentação fornecida por Ahmad Awais.

Um passo a passo do andaime do bloco inicial

Qualquer uma das duas ferramentas de desenvolvimento — create-block ou create-guten-block — que você optar, agora você tem um andaime de bloco que pode ser usado como ponto de partida para criar um plug-in de bloco.

Mas o que exatamente é um andaime de bloco?

Block scaffolding é um termo abreviado que descreve a estrutura de diretórios de suporte necessária para o WordPress reconhecer um bloco. Normalmente, esse diretório inclui arquivos como index.php , index.js , style.css e outros — que por sua vez contêm chamadas como register_block_type .

Optamos pela ferramenta de desenvolvimento oficial Create Block , pois ela é usada no Block Editor Handbook. Mas mesmo que você decida usar uma ferramenta de terceiros como create-guten-block , sua experiência não será muito diferente.

Com isso dito, vamos nos aprofundar na ferramenta create-block .

Uma visão mais detalhada da ferramenta Create Block Dev

Como mencionamos acima, Create Block é a ferramenta de linha de comando oficial para criar blocos Gutenberg. A execução @wordpress/create-block em seu terminal gera os arquivos PHP, JS e SCSS e o código necessário para registrar um novo tipo de bloco:

 npx @wordpress/create-block [options] [slug]

• [slug] (opcional) — usado para atribuir o bloco slug e instalar o plugin
• [options] (opcional) — opções disponíveis

Por padrão, um modelo ESNext é atribuído. Isso significa que você obterá a próxima versão do JavaScript, com a adição da sintaxe JSX.

Se você omitir o nome do bloco, o comando é executado em modo interativo, permitindo personalizar várias opções antes de gerar os arquivos:

 npx @wordpress/create-block

A imagem abaixo mostra a estrutura do arquivo de um plugin de bloco criado com a ferramenta oficial Create Block:

Com isso dito, vamos percorrer os principais arquivos e pastas do nosso novo plugin de bloco.

O arquivo de plug-in

Com o arquivo de plugin principal você registra o bloco no servidor:

 /** * Plugin Name: My First Block * Description: Example block written with ESNext standard and JSX support – build step required. * Requires at least: 5.8 * Requires PHP: 7.0 * Version: 0.1.0 * Author: The WordPress Contributors * License: GPL-2.0-or-later * License URI: https://www.gnu.org/licenses/gpl-2.0.html * Text Domain: my-first-block * * @package create-block */ /** * Registers the block using the metadata loaded from the `block.json` file. * Behind the scenes, it registers also all assets so they can be enqueued * through the block editor in the corresponding context. * * @see https://developer.wordpress.org/block-editor/tutorials/block-tutorial/writing-your-first-block-type/ */ function create_block_my_first_block_block_init() { register_block_type( __DIR__ ); } add_action( 'init', 'create_block_my_first_block_block_init' );

A função register_block_type registra um tipo de bloco no servidor usando os metadados armazenados no arquivo block.json .

A função recebe dois parâmetros:

• O nome do tipo de bloco incluindo namespace ou um caminho para a pasta onde o arquivo block.json está localizado ou um objeto WP_Block_Type completo
• Uma matriz de argumentos de tipo de bloco

No código acima, o argumento do tipo de bloco é fornecido pela constante mágica __DIR__ . Isso significa que o arquivo block.json reside na mesma pasta que o arquivo do plugin.

O arquivo package.json

O arquivo package.json define propriedades e scripts JavaScript para seu projeto. É aqui que você pode instalar as dependências do projeto.

Para entender melhor para que serve este arquivo, abra-o com seu editor de código favorito:

 { "name": "my-first-block", "version": "0.1.0", "description": "Example block written with ESNext standard and JSX support – build step required.", "author": "The WordPress Contributors", "license": "GPL-2.0-or-later", "main": "build/index.js", "scripts": { "build": "wp-scripts build", "format": "wp-scripts format", "lint:css": "wp-scripts lint-style", "lint:js": "wp-scripts lint-js", "start": "wp-scripts start", "packages-update": "wp-scripts packages-update" }, "dependencies": { "@wordpress/block-editor": "^7.0.1", "@wordpress/blocks": "^11.0.1", "@wordpress/i18n": "^4.2.1" }, "devDependencies": { "@wordpress/scripts": "^18.0.0" } }

A propriedade scripts é um dicionário contendo comandos que são executados em vários momentos do ciclo de vida de um pacote usando npm run [cmd] .

Neste artigo, usaremos os seguintes comandos:

• npm run build — cria uma compilação de produção (compactada)
• npm run start — cria uma compilação de desenvolvimento (descompactada)

dependencies e devDependencies são dois objetos que mapeiam um nome de pacote para uma versão. dependencies são necessárias em produção, enquanto devDependences são necessárias apenas para desenvolvimento local (leia mais).

A única dependência dev padrão é o pacote @wordpress/scripts , que é definido como “uma coleção de scripts reutilizáveis ​​adaptados para o desenvolvimento do WordPress”.

O arquivo block.json

A partir do WordPress 5.8, o arquivo de metadados block.json é a maneira canônica de registrar tipos de bloco.

Ter um arquivo block.json oferece vários benefícios, incluindo desempenho aprimorado e melhor visibilidade no diretório de plug-ins do WordPress:

Do ponto de vista do desempenho, quando os temas oferecem suporte a ativos de carregamento lento, os blocos registrados com block.json terão seu enfileiramento de ativos otimizado imediatamente. Os ativos CSS e JavaScript de front-end listados nas propriedades de style ou script só serão enfileirados quando o bloco estiver presente na página, resultando em tamanhos de página reduzidos.

A execução do comando @wordpress/create-block gera o seguinte arquivo block.json :

 { "apiVersion": 2, "name": "create-block/my-first-block", "version": "0.1.0", "title": "My First Block", "category": "widgets", "icon": "smiley", "description": "Example block written with ESNext standard and JSX support – build step required.", "supports": { "html": false }, "textdomain": "my-first-block", "editorScript": "file:./build/index.js", "editorStyle": "file:./build/index.css", "style": "file:./build/style-index.css" }

Aqui está a lista completa de propriedades padrão:

• apiVersion — a versão da API usada pelo bloco (a versão atual é 2)
• name — um identificador exclusivo para um bloco, incluindo um namespace
• version — a versão atual de um bloco
• title — um título de exibição para um bloco
• category — uma categoria de bloco
• icon — um slug Dashicon ou um ícone SVG personalizado
• description — uma breve descrição visível no inspetor de blocos
• supports — um conjunto de opções para controlar recursos usados ​​no editor
• textdomain — o plugin textdomain
• editorScript — definição de script do editor
• editorStyle — definição de estilo do editor
• style — fornece estilos alternativos para um bloco

Além das propriedades listadas acima, você pode (e provavelmente irá) definir um objeto de attributes fornecendo informações sobre os dados armazenados pelo seu bloco. Em seu block.json você pode definir qualquer número de atributos em pares chave/valor , onde a chave é o nome do atributo e o valor é a definição do atributo.

Dê uma olhada no seguinte exemplo de definições de atributo:

 "attributes": { "content": { "type": "array", "source": "children", "selector": "p" }, "align": { "type": "string", "default": "none" }, "link": { "type": "string", "default": "https://kinsta.com" } },

Vamos nos aprofundar no arquivo block.json mais adiante neste artigo, mas você também pode consultar o Manual do Editor de Blocos para obter informações mais detalhadas sobre os metadados e atributos do block.json .

A pasta src

A pasta src é onde o desenvolvimento acontece. Nessa pasta, você encontrará os seguintes arquivos:

• index.js
• edit.js
• salvar.js
• editor.scss
• estilo.scss

index.js

O arquivo index.js é seu ponto de partida. Aqui você irá importar dependências e registrar o tipo de bloco no cliente:

 import { registerBlockType } from '@wordpress/blocks'; import './style.scss'; import Edit from './edit'; import save from './save'; registerBlockType('create-block/my-first-block', { edit: Edit, save, });

A primeira instrução importa a função registerBlockType do pacote @wordpress/blocks . As instruções de importação a seguir importam a folha de estilo junto com as funções Edit e save .

A função registerBlockType registra o componente no cliente. A função recebe dois parâmetros: um nome de bloco namespace/block-name (o mesmo registrado no servidor) e um objeto de configuração de bloco.

A função Edit fornece a interface do bloco conforme renderizada no editor de blocos, enquanto a função save fornece a estrutura que será serializada e salva no banco de dados (leia mais).

edit.js

edit.js é onde você construirá a interface de administração do bloco:

 import { __ } from '@wordpress/i18n'; import { useBlockProps } from '@wordpress/block-editor'; import './editor.scss'; export default function Edit() { return ( <p {...useBlockProps()}> {__('My First Block – hello from the editor!', 'my-first-block')} </p> ); }

Primeiro, ele importa a função __ do pacote @wordpress/i18n (este pacote contém uma versão JavaScript das funções de tradução), o gancho useBlockProps React e o arquivo editor.scss .

Em seguida, ele exporta o componente React (leia mais sobre instruções de importação e exportação).

salvar.js

O arquivo save.js é onde construímos a estrutura de blocos a ser salva no banco de dados:

 import { __ } from '@wordpress/i18n'; import { useBlockProps } from '@wordpress/block-editor'; export default function save() { return ( <p {...useBlockProps.save()}> {__( 'My First Block – hello from the saved content!', 'my-first-block' )} </p> ); }

editor.scss e estilo.scss

Além dos scripts, dois arquivos SASS residem nas pastas src . O arquivo editor.scss contém os estilos aplicados ao bloco no contexto do editor, enquanto o arquivo style.scss contém os estilos do bloco para exibição no frontend. Vamos nos aprofundar nesses arquivos na segunda parte deste guia.

Os node_modules e pastas de compilação

A pasta node_modules contém módulos de nós e suas dependências. Não nos aprofundaremos nos pacotes de nós, pois está além do escopo deste artigo, mas você pode ler mais neste artigo sobre onde o npm instala os pacotes.

A pasta de build contém os arquivos JS e CSS resultantes do processo de construção. Você pode se aprofundar no processo de compilação na sintaxe ESNext e nos guias de configuração de compilação JavaScript.

O projeto: construindo seu primeiro bloco Gutenberg

É hora de sujar as mãos. Esta seção ensinará como criar um plug-in fornecendo um bloco de CTA chamado Bloco de Afiliados.

O bloco será composto por duas colunas, com uma imagem à esquerda e um parágrafo de texto à direita. Um botão com um link personalizável será colocado abaixo do texto:

Este é apenas um exemplo simples, mas nos permite cobrir o básico do desenvolvimento de blocos do Gutenberg. Depois de obter uma compreensão clara do básico, você pode ir em frente e criar blocos Gutenberg cada vez mais complexos com a ajuda do Block Editor Handbook e qualquer outro dos vastos recursos disponíveis.

Supondo que você tenha a versão mais recente do WordPress em execução em seu ambiente de desenvolvimento local, aqui está o que você aprenderá daqui em diante:

• Como configurar o plugin Starter Block
• block.json no trabalho
• Usando componentes internos: o componente RichText
• Adicionando controles à barra de ferramentas do bloco
• Personalizando a barra lateral de configurações de bloco
• Adicionando e Personalizando um Link Externo
• Adicionando vários estilos de bloco
• Aninhando blocos com o componente InnerBlocks
• Melhorias adicionais

Pronto... pronto... pronto!

Como configurar o plugin Starter Block

Inicie sua ferramenta de linha de comando e navegue até a pasta /wp-content/plugins :

Agora, execute o seguinte comando:

 npx @wordpress/create-block

Este comando gera os arquivos PHP, SCSS e JS para registrar um bloco no modo interativo, permitindo adicionar facilmente os dados necessários para o seu bloco. Para nosso exemplo, usaremos os seguintes detalhes:

• Bloquear slug : my-affiliate-block
• Namespace interno : my-affiliate-plugin
• Título de exibição do bloco : Bloco de afiliados
• Breve descrição do bloco : Um bloco de exemplo para leitores Kinsta
• Dashicon : dinheiro
• Nome da categoria : projeto
• Autor do plugin : seu nome
• Licença : –
• Link para o texto da licença : –
• Versão atual do plug -in: 0.1.0

A instalação do plugin e de todas as dependências leva alguns minutos. Quando o processo estiver concluído, você verá a seguinte resposta:

Agora, execute o seguinte comando na pasta /wp-content/plugins :

 cd my-affiliate-block

Finalmente, de dentro da pasta do seu plugin ( my-affiliate-block em nosso exemplo), você pode iniciar o desenvolvimento com:

 npm start

Agora abra a tela Plugins para encontrar e ativar o plugin Affiliate Block :

Crie uma nova postagem, abra o bloco de inserção e role para baixo até a categoria Design . Clique para adicionar o Bloco de Afiliados:

block.json no trabalho

Como mencionamos anteriormente, o registro do bloco do lado do servidor ocorre no arquivo .php principal. No entanto, não definiremos as configurações no arquivo .php . Em vez disso, usaremos o arquivo block.json .

Então, abra o block.json novamente e dê uma olhada nas configurações padrão:

 { "apiVersion": 2, "name": "my-affiliate-plugin/my-affiliate-block", "version": "0.1.0", "title": "Affiliate Block", "category": "design", "icon": "money", "description": "An example block for Kinsta readers", "supports": { "html": false }, "textdomain": "my-affiliate-block", "editorScript": "file:./build/index.js", "editorStyle": "file:./build/index.css", "style": "file:./build/style-index.css" }

Scripts e Estilos

editorScript , editorStyle e style fornecem os caminhos relativos para scripts e estilos de front-end e back-end.

Você não precisa registrar manualmente os scripts e estilos definidos aqui porque eles são registrados e enfileirados automaticamente pelo WordPress. Para provar isso, inicie o inspetor do navegador e abra a guia Rede :

Como você pode ver na imagem acima, nosso script index.js que reside na pasta build foi regularmente enfileirado sem a necessidade de adicionar nenhum código PHP .

Rótulos de IU

As propriedades title e description fornecem os rótulos necessários para identificar o bloco no editor:

Palavras-chave

Como mencionamos anteriormente, você pode definir com precisão suas configurações de bloco usando propriedades e atributos. Por exemplo, você pode adicionar uma ou mais palavras- keywords para ajudar os usuários a pesquisar blocos:

 { "keywords": [ "kinsta", "affiliate", "money" ] }

If you now input “kinsta”, “affiliate” or “money” in the quick inserter, the editor will suggest you the Affiliate block:

Localização

If you are wondering how the localization of the strings in the JSON file happens, here is the answer:

In JavaScript, you can use now registerBlockTypeFromMetadata method from @wordpress/blocks package to register a block type using the metadata loaded from block.json file. All localized properties get automatically wrapped in _x (from @wordpress/i18n package) function calls similar to how it works in PHP with register_block_type_from_metadata . The only requirement is to set the textdomain property in the block.json file.

Here we are using the registerBlockType function instead of registerBlockTypeFromMetadata , as the latter has been deprecated since Gutenberg 10.7, but the mechanism is the same.

Using Built-In Components: The RichText Component

The elements that make up a Gutenberg block are React components, and you can access these components via the wp global variable. For example, try to type wp.editor into your browser's console. This will give you the full list of the components included in the wp.editor module.

Scroll through the list and guess what components are meant for by their names.

Similarly, you can check the list of components included in the wp.components module:

Now go back to the edit.js file and take a closer look at the script:

import { __ } from '@wordpress/i18n'; import { useBlockProps } from '@wordpress/block-editor'; import './editor.scss'; export default function Edit() { return ( <p {...useBlockProps()}> {__('My First Block – hello from the editor!', 'my-first-block')} </p> ); }

Esse código gera um bloco estático com texto simples e não editável. Mas podemos mudar as coisas facilmente:

Para tornar o texto editável, você terá que substituir a tag <p> atual por um componente que torne o conteúdo de entrada editável. Para isso, o Gutenberg fornece o componente RichText embutido.

Adicionar um componente interno ao seu bloco é um processo de 5 etapas:

1. Importe os componentes necessários de um pacote WordPress
2. Inclua os elementos correspondentes em seu código JSX
3. Defina os atributos necessários no arquivo block.json
4. Definir manipuladores de eventos
5. Guardar dados

Etapa 1: importar os componentes necessários de um pacote WordPress

Agora abra o arquivo edit.js e altere a seguinte instrução de import :

 import { useBlockProps } from '@wordpress/block-editor';

…para:

 import { useBlockProps, RichText } from '@wordpress/block-editor';

Dessa forma, você está importando a função useBlockProps e o componente RichText do pacote @wordpress/block-editor .

useBlockProps

O hook useBlockProps React marca o elemento wrapper do bloco:

Ao usar a API versão 2, você deve usar o novo gancho useBlockProps na função de edit do bloco para marcar o elemento wrapper do bloco. O gancho irá inserir atributos e manipuladores de eventos necessários para habilitar o comportamento do bloco. Quaisquer atributos que você deseja passar para o elemento de bloco devem ser passados ​​por useBlockProps e o valor retornado deve ser espalhado no elemento.

Para simplificar, useBlockProps atribui automaticamente atributos e classes ao elemento wrapper (o elemento p em nosso exemplo):

Se você remover useBlockProps do elemento wrapper, você terá uma string de texto simples sem acesso à funcionalidade e estilo do bloco:

Como explicaremos mais adiante, você também pode passar para useBlockProps um objeto de propriedades para personalizar a saída.

RichText

O componente RichText fornece uma entrada de conteúdo editável, permitindo que os usuários editem e formatem o conteúdo.

Você encontrará o componente documentado no GitHub em gutenberg/packages/block-editor/src/components/rich-text/README.md.

Etapa 2: inclua os elementos correspondentes em seu código JSX

 ... const blockProps = useBlockProps(); return ( <RichText { ...blockProps } tagName="p" onChange={ onChangeContent } allowedFormats={ [ 'core/bold', 'core/italic' ] } value={ attributes.content } placeholder={ __( 'Write your text...' ) } /> );

Vamos comentar o código linha por linha:

• tagName — o nome da tag do elemento HTML editável
• onChange — função chamada quando o conteúdo do elemento muda
• allowedFormats — uma matriz de formatos permitidos. Por padrão, todos os formatos são permitidos
• value — a string HTML para tornar editável
• placeholder — texto de placeholder para mostrar quando o elemento está vazio

Etapa 3: definir os atributos necessários no arquivo block.json

Os atributos fornecem informações sobre os dados armazenados por um bloco, como conteúdo avançado, cor de fundo, URLs etc.

Você pode definir um número arbitrário de atributos dentro de um objeto de attributes em pares chave/valor, onde a chave é o nome do atributo e o valor é a definição do atributo.

Agora abra o arquivo block.json e adicione os seguintes attributes prop:

 "attributes": { "content": { "type": "string", "source": "html", "selector": "p" } },

O atributo content permite armazenar o texto digitado pelo usuário no campo editável:

• type indica o tipo de dados armazenados pelo atributo. O tipo é obrigatório, a menos que você defina uma propriedade enum .
• source define como o valor do atributo é extraído do conteúdo do post. Em nosso exemplo, é o conteúdo HTML. Observe que, se você não fornecer uma propriedade de origem, os dados serão armazenados no delimitador de bloco (leia mais).
• selector é uma tag HTML ou qualquer outro seletor, como um nome de classe ou um atributo id.

Passaremos à função Edit um objeto de propriedades. Então, volte para o arquivo edit.js e faça a seguinte alteração:

 export default function Edit( { attributes, setAttributes } ) { ... }

Etapa 4: definir manipuladores de eventos

O elemento RichText possui um atributo onChange , fornecendo uma função a ser chamada quando o conteúdo do elemento for alterado.

Vamos definir essa função e ver todo o script edit.js :

 import { __ } from '@wordpress/i18n'; import { useBlockProps, RichText } from '@wordpress/block-editor'; import './editor.scss'; export default function Edit( { attributes, setAttributes } ) { const blockProps = useBlockProps(); const onChangeContent = ( newContent ) => { setAttributes( { content: newContent } ) } return ( <RichText { ...blockProps } tagName="p" onChange={ onChangeContent } allowedFormats={ [ 'core/bold', 'core/italic' ] } value={ attributes.content } placeholder={ __( 'Write your text...' ) } /> ); }

Agora salve o arquivo e execute npm run start na janela do seu terminal. Em seguida, volte ao seu painel do WordPress, crie um novo post ou página e adicione seu bloco de afiliados:

Adicione algum texto e mude para a visualização de código. Veja como seu código deve ficar:

 <!-- wp:my-affiliate-plugin/my-affiliate-block --> <p class="wp-block-my-affiliate-plugin-my-affiliate-block">This is my first editable Gutenberg block </p> <!-- /wp:my-affiliate-plugin/my-affiliate-block -->

Se você agora salvar a página e verificar o resultado do frontend, poderá ficar um pouco desapontado porque suas alterações não afetam o site. Isso porque você precisa modificar o arquivo save.js para armazenar a entrada do usuário no banco de dados quando a postagem for salva.

Etapa 5: salvar dados

Agora abra o arquivo save.js e altere o script da seguinte forma:

 import { __ } from '@wordpress/i18n'; import { useBlockProps, RichText } from '@wordpress/block-editor'; export default function save( { attributes } ) { const blockProps = useBlockProps.save(); return ( <RichText.Content { ...blockProps } tagName="p" value={ attributes.content } /> ); }

É o que estamos fazendo aqui:

• Importe o componente RichText do pacote block-editor .
• Passe várias propriedades através de um argumento de objeto para a função save (neste exemplo, estamos passando apenas a propriedade attributes )
• Retornar o conteúdo do componente RichText

Você pode ler mais sobre o componente RichText no Block Editor Handbook e encontrar a lista completa de props no Github.

Agora vamos dar um passo adiante. Na próxima seção, você aprenderá como adicionar controles à barra de ferramentas do bloco.

Adicionando controles à barra de ferramentas do bloco

A barra de ferramentas do bloco contém um conjunto de controles que permitem aos usuários manipular partes do conteúdo do bloco. Para cada controle da barra de ferramentas, você encontrará um componente:

Por exemplo, você pode adicionar um controle de alinhamento de texto para seu bloco. Tudo que você precisa fazer é importar dois componentes do pacote @wordpress/block-editor .

Vamos seguir os mesmos passos do exemplo anterior:

1. Importar Componentes Necessários de Pacotes WordPress
2. Inclua os elementos correspondentes em seu código JSX
3. Defina os atributos necessários no arquivo block.json
4. Definir manipuladores de eventos
5. Guardar dados

Etapa 1: Importar BlockControls e AlignmentControl Components do @wordpress/block-editor

Para adicionar um controle de alinhamento à barra de ferramentas do bloco, você precisa de dois componentes:

• BlockControls renderiza uma barra de ferramentas dinâmica de controles (não documentada).
• AlignmentControl renderiza um menu suspenso que exibe opções de alinhamento para o bloco selecionado (leia mais)

Abra o arquivo edit.js e edite a instrução de import conforme mostrado abaixo:

 import { useBlockProps, RichText, AlignmentControl, BlockControls } from '@wordpress/block-editor';

Etapa 2: adicionar elementos BlockControls e AlignmentControl

Vá para a função Edit e insira o elemento <BlockControls /> no mesmo nível que <RichText /> . Em seguida, adicione e <AlignmentControl /> dentro de <BlockControls /> :

 export default function Edit( { attributes, setAttributes } ) { const blockProps = useBlockProps(); return ( <> <BlockControls> <AlignmentControl value={ attributes.align } onChange={ onChangeAlign } /> </BlockControls> <RichText { ...blockProps } tagName="p" onChange={ onChangeContent } allowedFormats={ [ 'core/bold', 'core/italic' ] } value={ attributes.content } placeholder={ __( 'Write your text...' ) } style={ { textAlign: attributes.align } } /> </> ); }

No código acima, <> e </> são a sintaxe curta para declarar fragmentos do React, que são como retornamos vários elementos no React.

Neste exemplo, AlignmentControl tem dois atributos:

• value fornece o valor atual para o elemento
• onChange fornece um manipulador de eventos para ser executado quando o valor for alterado

Também definimos atributos adicionais para o elemento RichText (verifique a lista completa de atributos com exemplos)

Etapa 3: defina o atributo align em block.json

Agora vá para o arquivo block.json e adicione o atributo align :

 "align": { "type": "string", "default": "none" }

Volte para o terminal, pare o processo atual com ^C e inicie o script novamente com npm run start . Em seguida, volte ao editor de blocos, atualize a página e selecione o bloco. Você deve ver a barra de ferramentas do bloco com um controle de alinhamento:

Agora, se você tentar formatar o conteúdo do bloco usando os novos controles de alinhamento, verá que nada acontece. Isso porque ainda não definimos o manipulador de eventos.

Etapa 4: definir os manipuladores de eventos

Agora defina onChangeAlign :

 const onChangeAlign = ( newAlign ) => { setAttributes( { align: newAlign === undefined ? 'none' : newAlign, } ) }

Se newAlign for undefined , então definimos newAlign como none . Caso contrário, usamos newAlign .

Nosso script edit.js deve estar completo (por enquanto):

 export default function Edit( { attributes, setAttributes } ) { const blockProps = useBlockProps(); const onChangeContent = ( newContent ) => { setAttributes( { content: newContent } ) } const onChangeAlign = ( newAlign ) => { setAttributes( { align: newAlign === undefined ? 'none' : newAlign, } ) } return ( <> <BlockControls> <AlignmentControl value={ attributes.align } onChange={ onChangeAlign } /> </BlockControls> <RichText { ...blockProps } tagName="p" onChange={ onChangeContent } allowedFormats={ [ 'core/bold', 'core/italic' ] } value={ attributes.content } placeholder={ __( 'Write your text...' ) } style={ { textAlign: attributes.align } } /> </> ); }

Agora você pode voltar ao editor e alinhar o conteúdo do bloco.

Precisamos modificar a função save para armazenar o conteúdo e os atributos do bloco no banco de dados.

Etapa 5: salvar dados

Abra save.js e altere a função save da seguinte forma:

 export default function save( { attributes } ) { const blockProps = useBlockProps.save(); return ( <RichText.Content { ...blockProps } tagName="p" value={ attributes.content } style={ { textAlign: attributes.align } } /> ); }

Por fim, para tornar o código mais legível, você pode extrair as propriedades individuais do objeto de attribute usando a sintaxe de atribuição de desestruturação:

 export default function save( { attributes } ) { const blockProps = useBlockProps.save(); const { content, align } = attributes; return ( <RichText.Content { ...blockProps } tagName="p" value={ content } style={ { textAlign: align } } /> ); }

Salve o arquivo, reinicie o processo e retorne ao editor no modo Editor de código. O código deve ficar mais ou menos assim:

 <!-- wp:my-affiliate-plugin/my-affiliate-block {"align":"right"} --> <p class="wp-block-my-affiliate-plugin-my-affiliate-block">This is my first editable <strong><em>Gutenberg</em></strong> <em>block</em> </p> <!-- /wp:my-affiliate-plugin/my-affiliate-block -->

E é isso! Você acabou de adicionar um controle de alinhamento à barra de ferramentas do bloco

Você pode ler mais sobre os controles da barra de ferramentas do bloco no Manual do Editor de Blocos.

Personalizando a barra lateral de configurações de bloco

Você também pode adicionar controles à barra lateral de configurações do bloco (ou até mesmo criar uma nova barra lateral para seu aplicativo).

A API fornece um componente InspectorControls para isso.

O Manual do Editor de Blocos explica como usar a Barra Lateral de Configurações:

A barra lateral de configurações é usada para exibir configurações menos usadas ou configurações que exigem mais espaço na tela. A barra lateral de configurações deve ser usada apenas para configurações de nível de bloco .

Se você tiver configurações que afetam apenas o conteúdo selecionado dentro de um bloco (exemplo: a configuração “negrito” para o texto selecionado dentro de um parágrafo): não o coloque dentro da Barra Lateral de Configurações. A Barra Lateral de Configurações é exibida mesmo ao editar um bloco no modo HTML, portanto, deve conter apenas configurações de nível de bloco.

Novamente:

1. Importar Componentes Necessários de Pacotes WordPress
2. Inclua os elementos correspondentes em seu código JSX
3. Defina os atributos necessários no arquivo block.json
4. Definir manipuladores de eventos
5. Guardar dados

Etapa 1. Importe os componentes InspectorControls e PanelColorSettings do @wordpress/block-editor

Você pode adicionar vários controles para permitir que os usuários personalizem aspectos específicos do bloco. Por exemplo, você pode fornecer um painel de controle colorido. Para fazer isso, você precisará importar os componentes InspectorControls e PanelColorSettings do módulo block-editor :

 import { useBlockProps, RichText, AlignmentControl, BlockControls, InspectorControls, PanelColorSettings } from '@wordpress/block-editor';

Etapa 2: incluir os elementos correspondentes em seu código JSX

Agora você pode adicionar os elementos correspondentes ao JSX retornado pela função Edit :

 export default function Edit( { attributes, setAttributes } ) { const blockProps = useBlockProps(); const onChangeContent = ( newContent ) => { setAttributes( { content: newContent } ) } const onChangeAlign = ( newAlign ) => { setAttributes( { align: newAlign === undefined ? 'none' : newAlign, } ) } return ( <> <InspectorControls> <PanelColorSettings title={ __( 'Color settings', 'my-affiliate-block' ) } initialOpen={ false } colorSettings={ [ { value: textColor, onChange: onChangeTextColor, label: __( 'Text color', 'my-affiliate-block' ), }, { value: backgroundColor, onChange: onChangeBackgroundColor, label: __( 'Background color', 'my-affiliate-block' ), } ] } /> </InspectorControls> <BlockControls> <AlignmentControl value={ attributes.align } onChange={ onChangeAlign } /> </BlockControls> <RichText { ...blockProps } tagName="p" onChange={ onChangeContent } allowedFormats={ [ 'core/bold', 'core/italic' ] } value={ attributes.content } placeholder={ __( 'Write your text...', 'my-affiliate-block' ) } style={ { textAlign: align, backgroundColor: backgroundColor, color: textColor } } /> </> ); }

Observe que também atualizamos o atributo style do elemento RichText :

 <RichText { ...blockProps } tagName="p" onChange={ onChangeContent } allowedFormats={ [ 'core/bold', 'core/italic' ] } value={ content } placeholder={ __( 'Write your text...', 'my-affiliate-block' ) } style={ { textAlign: align, backgroundColor: backgroundColor, color: textColor } } />

Etapa 3: definir os atributos necessários em block.json

Agora defina os atributos backgroundColor e textColor no arquivo block.json :

 "attributes": { "content": { "type": "string", "source": "html", "selector": "p" }, "align": { "type": "string", "default": "none" }, "backgroundColor": { "type": "string" }, "textColor": { "type": "string" } },

Etapa 4: definir os manipuladores de eventos

Agora você precisa definir duas funções para atualizar backgroundColor e textColor na entrada do usuário:

 const onChangeBackgroundColor = ( newBackgroundColor ) => { setAttributes( { backgroundColor: newBackgroundColor } ) } const onChangeTextColor = ( newTextColor ) => { setAttributes( { textColor: newTextColor } ) }

Etapa 5: salvar dados

Uma última etapa: abra o arquivo save.js e altere o script da seguinte forma:

 export default function save( { attributes } ) { const blockProps = useBlockProps.save(); const { content, align, backgroundColor, textColor } = attributes; return ( <RichText.Content { ...blockProps } tagName="p" value={ content } style={ { textAlign: align, backgroundColor: backgroundColor, color: textColor } } /> ); }

Agora pare o processo (^C) e execute npm run start novamente. Atualize a página, exclua qualquer instância do seu bloco e adicione-a novamente à sua postagem:

Faça suas alterações, salve a postagem e visualize-a no frontend. As alterações feitas no editor de blocos devem ser refletidas no site frontal.

Adicionando e Personalizando um Link Externo

Nesta seção, você adicionará novos componentes ao seu tipo de bloco:

• Um componente ExternalLink que permite aos usuários adicionar um link personalizável ao bloco Afiliado
• Vários controles da barra lateral que permitem que os usuários personalizem as configurações de link

Etapa 1. Importar componentes de @wordpress/components

Agora você precisa importar vários componentes de @wordpress/components . Abra seu arquivo edit.js e adicione a seguinte instrução de import :

 import { TextControl, PanelBody, PanelRow, ToggleControl, ExternalLink } from '@wordpress/components';

• PanelBody adiciona um contêiner dobrável à barra lateral de configurações.
• PaneRow produz um contêiner genérico para controles de barra lateral.
• TextControl fornece um controle de entrada de texto.
• ToggleControl fornece uma alternância que permite aos usuários ativar/desativar uma opção específica
• ExternalLink é um componente simples para adicionar um link externo.

Etapa 2. Inclua os elementos correspondentes em seu código JSX

Você primeiro adicionará o elemento ExternalLink no mesmo nível de RichText em um contêiner div :

 <div { ...blockProps }> <RichText ... /> <ExternalLink href={ affiliateLink } className="affiliate-button" rel={ hasLinkNofollow ? "nofollow" : "" } > { linkLabel } </ExternalLink> </div>

O componente ExternalLink não está documentado, então nos referimos ao próprio componente para obter a lista de atributos disponíveis. Aqui estamos usando os href , className e rel .

Por padrão, o valor do atributo rel é definido como noopener noreferrer . Nosso código adicionará a palavra-chave nofollow ao atributo rel da tag resultante quando a controle de alternância estiver ativado .

Agora você pode adicionar configurações de link à barra lateral do bloco.

Primeiro, você adicionará um elemento PanelBody dentro de InspectorControls no mesmo nível de PanelColorSettings :

 <InspectorControls> <PanelColorSettings ... /> <PanelBody title={ __( 'Link Settings', 'my-affiliate-block' )} initialOpen={true} > ... </PanelBody> </InspectorControls>

Aqui está o que estamos fazendo com isso:

1. O atributo title fornece o título do painel.
2. initialOpen define se o painel está inicialmente aberto ou não.

Em seguida, adicionaremos dois elementos PanelRow dentro de PanelBody e um elemento TextControl dentro de cada PanelRow :

 <PanelBody title={ __( 'Link Settings', 'my-affiliate-block' )} initialOpen={true} > <PanelRow> <fieldset> <TextControl label={__( 'Affiliate link', 'my-affiliate-block' )} value={ affiliateLink } onChange={ onChangeAffiliateLink } help={ __( 'Add your affiliate link', 'my-affiliate-block' )} /> </fieldset> </PanelRow> <PanelRow> <fieldset> <TextControl label={__( 'Link label', 'my-affiliate-block' )} value={ linkLabel } onChange={ onChangeLinkLabel } help={ __( 'Add link label', 'my-affiliate-block' )} /> </fieldset> </PanelRow> </PanelBody>

O código acima agora deve parecer bastante simples. Os dois controles de texto permitem que os usuários definam o rótulo e o URL do link.

Também adicionaremos um PanelRow adicional com um ToggleControl para ativar/desativar uma opção específica, como incluir ou não um atributo:

 <PanelRow> <fieldset> <ToggleControl label="Add rel = nofollow" help={ hasLinkNofollow ? 'Has rel nofollow.' : 'No rel nofollow.' } checked={ hasLinkNofollow } onChange={ toggleNofollow } /> </fieldset> </PanelRow>

Etapa 3: definir os atributos necessários em block.json

Agora defina os atributos affiliateLink , linkLabel e hasLinkNofollow no arquivo block.json :

 "affiliateLink": { "type": "string", "default": "" }, "linkLabel": { "type": "string", "default": "Check it out!" }, "hasLinkNofollow": { "type": "boolean", "default": false }

Nada mais a acrescentar aqui! Vamos passar para a definição das funções de manipulação de eventos.

Etapa 4: definir os manipuladores de eventos

Volte para o arquivo edit.js e adicione as seguintes funções:

 const onChangeAffiliateLink = ( newAffiliateLink ) => { setAttributes( { affiliateLink: newAffiliateLink === undefined ? '' : newAffiliateLink } ) } const onChangeLinkLabel = ( newLinkLabel ) => { setAttributes( { linkLabel: newLinkLabel === undefined ? '' : newLinkLabel } ) } const toggleNofollow = () => { setAttributes( { hasLinkNofollow: ! hasLinkNofollow } ) }

Essas funções atualizam os valores de atributo correspondentes na entrada do usuário.

Etapa 5: salvar dados

Por último, temos que atualizar a função save em save.js :

 export default function save( { attributes } ) { const { align, content, backgroundColor, textColor, affiliateLink, linkLabel, hasLinkNofollow } = attributes; const blockProps = useBlockProps.save(); return ( <div { ...blockProps }> <RichText.Content tagName="p" value={ content } style={ { backgroundColor: backgroundColor, color: textColor } } /> <p> <a href={ affiliateLink } className="affiliate-button" rel={ hasLinkNofollow ? "nofollow" : "noopener noreferrer" } > { linkLabel } </a> </p> </div> ); }

Observe que aqui usamos a elemento regular a em vez de ExternalLink :

Agora salve os dados e reinicie seu ambiente.

Adicionando vários estilos de bloco

Em uma seção anterior, você aprendeu como adicionar um controle de barra de ferramentas de bloco que permite aos usuários alinhar a entrada do usuário. Podemos adicionar mais controles de estilo à barra de ferramentas do bloco, mas também podemos fornecer um conjunto de estilos de bloco predefinidos que o usuário pode escolher com um único clique.

Para isso, usaremos um recurso útil da Block API: Block Styles.

Tudo que você precisa fazer é definir a propriedade de styles block.json e declarar os estilos correspondentes em suas folhas de estilo.

Por exemplo, você pode adicionar a seguinte matriz de estilos:

 "styles": [ { "name": "default", "label": "Default", "isDefault": true }, { "name": "border", "label": "Border" } ],

Com isso, você acabou de adicionar um estilo padrão e um estilo adicional chamado border . Agora volte para o editor de blocos:

Os estilos estarão disponíveis para o usuário clicando no seletor de blocos e procurando o painel Estilos na Barra Lateral de Configurações do Bloco .

Selecione um estilo e verifique as classes aplicadas ao elemento p . Clique com o botão direito do mouse no bloco e Inspecione . Uma nova classe foi adicionada com um nome estruturado da seguinte forma:

 is-style-{style-name}

Se você marcou o estilo “Border”, uma classe is-style-border será adicionada ao elemento p . Se você marcou o estilo "Padrão", uma classe is-style-default será adicionada.

Agora você só precisa declarar as propriedades CSS. Abra o arquivo editor.scss e substitua os estilos atuais pelo seguinte:

 .wp-block-my-affiliate-plugin-my-affiliate-block { padding: 2px; &.is-style-default{ border: 0; } &.is-style-border{ border: 1px solid #000; } }

Agora você pode fazer o mesmo com style.scss :

 .wp-block-my-affiliate-plugin-my-affiliate-block { &.is-style-default{ border: 0; } &.is-style-border{ border: 1px solid #000; } }

Pare o processo (^C) e execute npm run start novamente.

E é isso! Atualize a página e divirta-se com seus novos estilos de bloco:

Aninhando blocos Gutenberg com o componente InnerBlocks

Embora totalmente funcional, nosso Bloco de Afiliados ainda não é muito atraente. Para torná-lo mais atraente para o público, poderíamos adicionar uma imagem.

Isso pode adicionar uma camada de complexidade ao nosso bloco, mas, felizmente, você não precisa reinventar a roda porque o Gutenberg fornece um componente específico que você pode usar para criar uma estrutura de blocos aninhados.

O componente InnerBlocks é definido da seguinte forma:

InnerBlocks exporta um par de componentes que podem ser usados ​​em implementações de bloco para habilitar o conteúdo de bloco aninhado.

Primeiro, você precisará criar um novo arquivo .js na pasta src . Em nosso exemplo, chamaremos esse arquivo de container.js .

Agora você precisará importar o novo recurso para o arquivo index.js :

 import './container';

Volte para container.js e importe os componentes necessários:

 import { registerBlockType } from "@wordpress/blocks"; import { __ } from "@wordpress/i18n"; import { useBlockProps, InnerBlocks } from "@wordpress/block-editor";

O próximo passo é definir um template fornecendo a estrutura dentro da qual os blocos serão colocados. No exemplo a seguir, definimos um modelo que consiste em duas colunas contendo um bloco de imagem principal e nosso bloco de afiliado personalizado:

 const TEMPLATE = [ [ 'core/columns', { backgroundColor: 'yellow', verticalAlignment: 'center' }, [ [ 'core/column', { templateLock: 'all' }, [ [ 'core/image' ], ] ], [ 'core/column', { templateLock: 'all' }, [ [ 'my-affiliate-plugin/my-affiliate-block', { placeholder: 'Enter side content...' } ], ] ], ] ] ];

O template é estruturado como um array de blockTypes (nome do bloco e atributos opcionais).

No código acima, usamos vários atributos para configurar os blocos Columns e Column. Especificamente, o atributo templateLock: 'all' bloqueia os blocos de coluna para que o usuário não adicione, reordene ou exclua os blocos existentes. templateLock pode ter um dos seguintes valores:

• all — InnerBlocks está bloqueado e nenhum bloco pode ser adicionado, reordenado ou removido.
• insert — Os blocos só podem ser reordenados ou removidos.
• false — O modelo não está bloqueado.

O template é então atribuído ao elemento InnerBlocks :

 <InnerBlocks template={ TEMPLATE } templateLock="all" />

Para evitar qualquer problema de compatibilidade, também adicionamos um atributo templateLock ao componente InnerBlocks (consulte também o problema #17262 e o pull #26128).

Aqui está nosso arquivo container.js final:

 import { registerBlockType } from "@wordpress/blocks"; import { __ } from "@wordpress/i18n"; import { useBlockProps, InnerBlocks } from "@wordpress/block-editor"; const TEMPLATE = [ [ 'core/columns', { backgroundColor: 'yellow', verticalAlignment: 'center' }, [ [ 'core/column', { templateLock: 'all' }, [ [ 'core/image' ], ] ], [ 'core/column', { templateLock: 'all' }, [ [ 'my-affiliate-plugin/my-affiliate-block', { placeholder: 'Enter side content...' } ], ] ], ] ] ]; registerBlockType('my-affiliate-plugin/my-affiliate-container-block', { title: __( 'Container', 'my-affiliate-block' ), category: 'design', edit( { className } ) { return( <div className={ className }> <InnerBlocks template={ TEMPLATE } templateLock="all" /> </div> ) }, save() { const blockProps = useBlockProps.save(); return( <div { ...blockProps }> <InnerBlocks.Content /> </div> ) }, });

Melhorias adicionais

Nosso bloco está totalmente funcional, mas poderíamos melhorá-lo um pouco com algumas pequenas mudanças.

Atribuímos o atributo backgroundColor ao parágrafo gerado pelo componente RichText . No entanto, podemos preferir atribuir a cor de fundo à div do contêiner:

Portanto, altere o arquivo edit.js e save.js div s da seguinte forma:

 <div { ...blockProps } style={ { backgroundColor: backgroundColor } } > ... </div>

Isso permitirá que o usuário altere o plano de fundo de todo o bloco.

Por outro lado, uma mudança mais relevante envolve o método useBlockProps . No código original, definimos a constante blockProps da seguinte forma:

 const blockProps = useBlockProps();

Mas podemos usar o useBlockProps de forma mais eficaz passando um conjunto de propriedades. Por exemplo, podemos importar nomes de classnames classnames definir o nome da classe wrapper de acordo.

No exemplo a seguir, atribuímos um nome de classe com base no valor do atributo align ( edit.js ):

 import classnames from 'classnames'; ... export default function Edit( { attributes, setAttributes } ) { ... const blockProps = useBlockProps( { className: classnames( { [ `has-text-align-${ align }` ]: align, } ) } ); ... }

Faremos a mesma alteração no arquivo save.js :

 import classnames from 'classnames'; ... export default function save( { attributes } ) { ... const blockProps = useBlockProps.save({ className: classnames( { [ `has-text-align-${ align }` ]: align, } ) }); ... }

E isso é um embrulho! Agora você pode executar a compilação para produção.

Resumo

E aqui estamos nós, no final desta incrível jornada! Começamos com a configuração do ambiente de desenvolvimento e acabamos criando um tipo de bloco completo.

Como mencionamos na introdução, um conhecimento sólido de Node.js, Webpack, Babel e React é essencial para criar blocos avançados de Gutenberg e se posicionar no mercado como um desenvolvedor profissional de Gutenberg.

Mas você não precisa ter experiência estabelecida em React para começar a se divertir com o desenvolvimento de blocos. O desenvolvimento de blocos pode fornecer motivação e objetivos para obter habilidades cada vez mais amplas nas tecnologias por trás dos blocos Gutenberg.

Este guia, portanto, está longe de ser completo. É apenas uma introdução a uma ampla variedade de tópicos que o ajudarão a começar a construir seus primeiros blocos Gutenberg.

Por esse motivo, recomendamos que você aprofunde seu conhecimento lendo atentamente a documentação e os guias on-line. Entre os muitos recursos disponíveis, recomendamos o seguinte:

• Tutorial oficial para criar um bloco para iniciantes
• Tutorial oficial do bloco para desenvolvedores intermediários
• Blocos dinâmicos
• Caixas Meta
• Criando uma barra lateral para seu plugin

Se você está apenas começando com o desenvolvimento do WordPress, talvez queira entender os conceitos básicos do desenvolvimento de front-end. Aqui está uma lista rápida de recursos que podem ajudá-lo a começar:

• Como instalar o WordPress localmente (ebook gratuito)
• O valor real da hospedagem gerenciada do WordPress (ebook gratuito)
• O que é JavaScript?
• HTML vs HTML5
• Como editar CSS no WordPress
• O que é PHP?
• O WordPress Hooks Bootcamp: Como usar ações, filtros e ganchos personalizados

E lembre-se que o código completo dos exemplos deste guia está disponível no Gist.

Agora é a sua vez: você desenvolveu algum bloco Gutenberg? Quais as principais dificuldades que você experimentou até agora? Conte-nos sobre sua experiência nos comentários!