Desenvolvimento do Gutenberg com exemplos: Google Maps (parte 2)

Olá! Estamos de volta com nosso tutorial para desenvolver em Gutenberg. Na semana passada iniciamos um projeto que adicionou um bloco de mapa no WordPress. Nesse primeiro post definimos quais eram os requisitos que nosso plugin deveria atender e preparamos o esqueleto do que será o produto final, começando pelo fantástico clichê do plugin que criamos no Nelio.

Hoje vem a segunda parte do tutorial de como criar o bloco do mapa . Neste post veremos como adicionar um mapa do Google Maps dentro do editor do WordPress e como implementar uma interface de usuário que nos permita manipular seu comportamento.

Uma rápida olhada no status atual do projeto…

No estado atual do projeto temos um bloco Demo simples definido em packages/blocks/demo/ . Este pequeno bloco é o que vem como exemplo no clichê do plugin do Nelio e se parece com isso:

Obviamente, não é isso que queremos. Não estamos interessados ​​em um ícone de coração seguido por algum texto, mas em algo assim:

Ou seja, queremos um bloco do Google Maps com um marcador opcional. Como podemos passar do bloco de exemplo original que nosso clichê tinha para esse outro bloco mais poderoso? Bem, é isso que vamos responder hoje!

Mas antes disso, deixe-me investir alguns minutos explicando o que temos agora e como vamos seguir em frente. Acho que, se você entender o estado atual do projeto, terá mais facilidade para acompanhar o que virá a seguir.

Entendendo o bloco de demonstração …

Como já disse, o bloco demo é definido em packages/blocks/demo/ . Nesta pasta você encontrará os estilos do bloco, seu ícone e diversos arquivos com o código que implementa seu funcionamento. Vamos ver os arquivos mais importantes.

Por um lado, há o arquivo principal: index.js . Este arquivo exporta três variáveis: o nome do bloco ( name ), a definição do bloco ( settings ) e os estilos que o bloco suporta ( styles ). Essas três variáveis ​​são aquelas usadas em packages/blocks/index.js para registrar o bloco no Gutenberg (com registerBlockType ) e assim torná-lo disponível para usuários finais.

Este arquivo principal, então, serve como ponto de entrada para entender o bloco que estamos criando. Nas configurações do objeto ( settings ), vemos três propriedades importantes: attributes , edit e save . Cada uma dessas propriedades tem seu próprio arquivo JavaScript (por uma questão de simplicidade e facilidade de compreensão), cada uma com o nome de sua propriedade correspondente. Vamos dar uma olhada rápida em todos eles:

• O arquivo attributes.js define todas aquelas propriedades do nosso bloco que são dinâmicas e, portanto, devem ser ajustáveis ​​por nossos usuários. No caso do nosso bloco Demo , o único atributo que existe é o texto que o usuário escreveu, mas o bloco do mapa terá muito mais opções: as coordenadas do centro do mapa, o nível de zoom padrão que o mapa deve usar, qual botões (se houver) devem estar visíveis para interagir com o mapa, etc.
• O arquivo edit.js é aquele que define como o bloco é exibido no editor do WordPress e quais configurações são oferecidas ao usuário (tanto na barra de ferramentas quanto na barra lateral de configurações do bloco). Em Demo , a edit simplesmente inclui o componente RichText do WordPress para escrever o conteúdo. Como veremos, o bloco do mapa será mais complexo e também incluirá configurações adicionais.
• Por fim, save.js define o método que irá converter o bloco que estávamos editando no Gutenberg no HTML que deve ser renderizado no front-end. Novamente, em Demo vemos que esta função simplesmente salva o conteúdo de um RichText usando RichText.Content , mas pode ser qualquer outra coisa (como veremos na próxima semana na terceira e última parte deste tutorial).

Criação do bloco de mapa com base no bloco de demonstração incluído no plug-in Boilerplate

Uma vez que entendemos exatamente como funciona o bloco Demo , é hora de nos perguntarmos: como criamos o nosso? Bem, muito fácil: como Toni nos disse há alguns dias, simplesmente temos que duplicar o diretório packages/blocks/demo/ em packages/blocks/nelio-maps/ e começar a modificar tudo o que for necessário. Eu sei, é mais fácil falar do que fazer.

Vamos começar com algo fácil: attributes.js . Este arquivo contém todas as propriedades que devem ser modificáveis ​​por nossos usuários finais. No post anterior, especificamos quais requisitos nosso plugin deve atender e, portanto, descrevemos quais coisas devem ser ajustáveis. Bem, dando uma olhada nos attributes.js resultantes, você verá claramente o que pode ser ajustado em nosso bloco de mapas: nível de zoom, centro do mapa, visibilidade de diferentes botões… Coisas super simples!

O próximo ponto a modificar é tudo o que diz respeito à edição do bloco em Gutenberg. Para fazer isso, devemos mergulhar em edit.js . Se você olhar de perto, verá que não é muito mais complicado do que o que tínhamos em nosso bloco de demonstração original.

O mais importante está no método render do bloco (linha 33), onde recuperamos os atributos que acabamos de definir de um objeto chamado this.props . Usaremos essas propriedades para renderizar o bloco e suas configurações, é claro. Isto é o que temos:

1. Uma barra de ferramentas ToolbarControls (linha 66), que definimos em um arquivo externo chamado toolbar.js (não se preocupe, veremos seu conteúdo em um minuto).
2. As configurações de bloco que aparecem na barra lateral do editor (linha 68), que encontramos em um componente chamado Inspector que definimos em inspector.js .
3. O conteúdo do próprio bloco, que possui dois estados:
   • Se eu não tiver uma chave de API do Google Maps disponível, mostraremos um aviso ao usuário (linha 122).
   • Se tivermos essa chave, mostramos o mapa usando MapBlock (linha 83). O mapa pode incluir um Marker (linha 97), que só fica visível quando a opção está ativada, e pode também ser acompanhado de uma div (linha 104) com informações adicionais sobre ele.

Google Maps como um componente React

Se quisermos colocar um mapa do Google em nosso editor, devemos usar um componente que nos permita usar a API de mapas do Google Maps. Considerando que o Gutenberg é construído em cima do React, o lógico a fazer é descobrir se existe um componente React do Google Maps. E, com certeza, há um!

Como você pode ler na documentação do projeto, primeiro temos que adicionar o componente ao nosso projeto. Basta instalar e adicionar a dependência executando o seguinte comando:

 npm install react-google-maps --save-dev

que adiciona uma nova entrada em nosso package.json e baixa o pacote em node_modules .

Como criar um componente WordPress que encapsula um componente React

Se continuarmos analisando a documentação deste projeto React para o Google Maps, veremos que eles nos recomendam envolver seu componente GoogleMap com nosso próprio componente. Uma vez encapsulado, teremos que usar nosso componente em nosso plugin.

Bem, vamos seguir o exemplo e criar um componente chamado MapBlock em seu próprio arquivo map-block.js . E é isso! Agora temos um componente de mapa pronto que podemos usar em nosso bloco Gutenberg.

Como adicionar configurações de bloco no inspetor do editor do WordPress

O próximo passo é configurar a aparência deste mapa no editor e adicionar algumas configurações para ajustar sua aparência. Para fazer isso, devemos adicionar várias seções de configurações na barra lateral do Gutenberg. Como já adiantei, conseguimos isso com um componente que chamamos de Inspector e que definimos no arquivo inspector.js .

Se você der uma olhada nesse arquivo, verá que ele segue o mesmo padrão de sempre: estamos definindo um Component com um método render . Este método extrai os atributos relevantes em this.props e retorna o JSX com todos os controles. Nesse caso específico, ele retorna uma instância de InspectorControls (isso informa ao WordPress que esse conteúdo vai para a barra lateral) com várias seções PanelBody . Vamos ver cada seção em detalhes.

Configurações básicas do mapa

O primeiro PanelBody que encontramos (linha 47) não tem title e, portanto, sempre aparece como uma seção que não pode ser fechada:

A seção define um par de RangeControl s, cujo resultado você pode ver na captura de tela anterior. Esses dois controles nos permitem modificar a altura do mapa e seu nível de zoom.

Outra seção interessante e simples é a encontrada na linha 121. Aqui adicionamos algumas opções para ativar ou desativar os botões que devem ser mostrados no mapa quando exibidos no front-end :

Para fazer isso, basta usar o componente padrão do WordPress CheckboxControl .

Como adicionar uma seção de estilo personalizado para nosso bloco de mapa

Outra seção interessante do nosso bloco é a seção de estilo (linha 68). Você pode ver o resultado final na captura de tela a seguir:

É uma seção especial porque o componente que usamos ( MapStyles ) não é algo que existe no WordPress por padrão, mas algo que criamos para este bloco em particular. Como você pode ver no link anterior, é um componente que carrega um conjunto de estilos predefinidos em um componente do tipo ImagePicker (que, aliás, também não existe por padrão no WordPress - você pode encontrá-lo em packages/components/image-picker/ ).

Quando o usuário seleciona qualquer um dos estilos incluídos no ImagePicker , o componente MapStyles invoca a função onChange que lhe foi atribuída (veja a linha 76 do inspector.js ) passando dois valores: o nome do estilo selecionado e o JSON associado.

Por fim, observe que uma das opções que o MapStyles inclui é um estilo personalizado :

Quando selecionado, o componente renderiza uma caixa de texto adicional (linha 45) para que o usuário possa inserir seu próprio estilo no formato JSON. Caso você não saiba, os mapas do Google Maps podem ser muito personalizados!

Como adicionar um marcador em nosso mapa

A próxima seção que temos é a que controla nosso marcador (linha 81). Esta seção nos permite mostrar ou ocultar o marcador (linha 86) e, quando ativo, nos fornece algumas configurações adicionais:

Como você vê, uma caixa de pesquisa aparece para pesquisar locais no Google Maps (que implementamos, novamente, com um componente personalizado chamado AddressSearch ) e a capacidade de mostrar ou ocultar o bloco de texto no qual colocar informações adicionais sobre o marcador .

A propósito, observe que o componente AddressSearch é baseado em um componente chamado StandaloneSearchBox , que também faz parte do projeto React . Que prazer é reutilizar o trabalho dos outros!

Como configurar a barra de ferramentas de um bloco

A última coisa que temos que discutir é a barra de ferramentas. Se você entendeu como a barra lateral funciona, a barra de ferramentas é muito fácil.

A barra de ferramentas do nosso plugin é representada pelo componente ToolbarControls definido em toolbar.js . Aqui nós simplesmente adicionamos um componente para definir o alinhamento do bloco ( BlockAlignmentToolbar , na linha 42), um par de dropdowns para centralizar o mapa (linha 50) e modificar a localização do marcador (linha 79), e alguns botões extras para alterar a localização da caixa de texto na qual podemos colocar informações adicionais sobre o marcador (linhas 107 e 120).

Em suma

Hoje vimos como criar toda a interface de edição do nosso bloco de mapas. Como você pode ver, é um processo que pode parecer complicado à primeira vista, mas se torna bastante natural rapidamente. No final, o segredo é partir de um exemplo bem organizado (como é o nosso clichê de plugins) e construir a interface passo a passo, reutilizando os componentes que o WordPress oferece ou que já existem, ou até mesmo criando os seus próprios.

Até a próxima semana com a última parte deste tutorial, onde veremos como salvar nosso mapa e como visualizá-lo no front-end .

Imagem em destaque por rawpixel no Unsplash .