Nesta parte veremos como definir atributos, buscar seus valores e atualizá-los. Com os atributos, podemos aceitar a entrada do editor, salvá-la e produzi-la da maneira que escolhermos. Na etapa anterior, analisamos os componentes do WordPress, onde encontrá-los e como implementá-los. Neste post vamos adicionar adereços para fazer a conexão com os atributos – os dados salvos.
Definindo atributos
Os atributos são adicionados como objetos em uma matriz à attributespropriedade em registerBlockType(). A chave de cada atributo é o nome do atributo e você deve ter a propriedade typeno mínimo.
A typepropriedade pode ser qualquer uma das seguintes; null, boolean, object, array, number, stringou integer.
Opcionalmente, você pode fornecer a propriedade defaultpara definir o valor inicial de seu atributo. Se você não fornecer um padrão, o atributo padrão será null.
Outra propriedade de atributo é sourceque funciona em conjunto com a selectorpropriedade, mas essas são coisas complicadas que veremos em detalhes mais abaixo.
Por exemplo, definir dois atributos; exampleTextcomo string e postIdscomo array, ficaria assim:
Qualquer coisa que você precise salvar para o seu bloco (entrada do usuário/editor) requer um atributo. Cabe a você como estruturar seus dados, definindo atributos separados para cada um ou agrupando-os em um objeto. Será apenas uma diferença em como você busca seus dados e como você os atualiza.
Obtendo valores de atributo
Os atributos estão disponíveis como adereços para seus blocos edite savefunções. Se você seguiu esta série do passo anterior, lembre-se que atualizamos as funções para passar props como parâmetro.
É comum desestruturar atributos de adereços, já que você normalmente se refere a eles com frequência. Por exemplo, a saída de um atributo chamado exampleTextficaria assim:
Atualizando valores de atributo
Para atualizar atributos temos um método disponível em props, chamado setAttributes(). Esta função aceita um objeto onde você pode adicionar qualquer atributo que deseja atualizar. Você pode atualizar apenas um atributo, mais ou todos de uma vez. Se você tiver vários atributos definidos e chamar setAttributes()para atualizar apenas um deles, os outros não serão tocados.
Se você tem experiência com React, provavelmente reconhecerá imediatamente semelhanças entre setAttributes()e setState(). Eles funcionam exatamente da mesma forma, mas a diferença é que o estado no React é apenas algo armazenado localmente naquele componente, e os atributos são realmente salvos como dados fora do componente.
Para atualizar um atributo, você normalmente destruiria a função de props e a chamaria assim: Abaixo, atualizamos o exampleTextatributo para ser "Hi".
const { setAttributes } = props;
setAttributes({ exampleText: 'Hi' });Naturalmente você executaria a setAttributes()partir de alguma ação. Um exemplo comum é dentro do onChangeprop em algum tipo de campo de entrada que é usado para armazenar o valor do exampleTextatributo.
Certifique-se de salvar os atributos no tipo que você definiu no atributo. Você não terá sorte tentando salvar objetos em um atributo de string, por exemplo.
Vamos experimentar na prática! Inicie npm run startse ainda não o fez.
Exibindo um atributo em uma entrada de texto personalizada e atualizando o valor do atributo
Na etapa anterior adicionamos alguns componentes em edit, por exemplo, uma entrada de texto, mas nada foi armazenado. Vamos adicionar um atributo e uma entrada de texto para ele em nosso bloco. Nós dois nos certificaremos de que a entrada de texto mostre o valor atual e, sempre que a entrada for alterada, atualizaremos o atributo.
Adicionando a entrada de texto e sua onChangeprop
Desestruturamos attributese setAttributesa partir de propscomo usaremos ambos. Em seguida, usamos um componente do pacote TextControldo WordPress. wp.componentsPassamos dois adereços para ele; valueirá definir o valor da entrada (tanto inicialmente quanto enquanto digitamos) e uma ação no evento da entrada onChange.
Em valuedefinimos o valor do nosso atributo; attributes.exampleText. No onChangecaso de executarmos uma função, passando o valor digitado de nossa entrada como parâmetro, newtext(o valor de entrada é uma prop que é retornada do componente). Nessa função chamamos setAttributes()e atualizamos o atributo exampleTextpara o que foi digitado na entrada.
Isso é React básico – além do fato de trabalharmos com atributos e não com estado. Se o acima o confundiu, recomendo ver um tutorial rápido no React, pois provavelmente explicará dessa maneira melhor do que eu!
Atualize seu editor e veja como o bloco funciona! Você deve obter uma entrada de texto padrão para digitar as coisas, e ela será salva sempre que você clicar em Salvar/Atualizar na pós-edição.
O resultado no frontend e no banco de dados
Se você visualizar sua postagem no frontend, ela ainda deve ecoar uma div com “:)" porque é isso que ainda temos em nossa savefunção. Mas algo aconteceu nos bastidores! O bloco de comentários do nosso bloco agora contém o valor do nosso atributo em JSON.
Você não pode ver os blocos de comentários em um modelo que faz uma the_content()chamada normal. Para ver os blocos de comentários, você tem duas opções. Ou olhe na post_contenttabela de banco de dados de postagens. Ou adicione echo get_the_content()o modelo e veja-o na ferramenta Inspecionar/depurar.
Obviamente, temos acesso aos atributos savetambém, a partir de adereços.
Exibindo o valor da entrada emsave
Vamos exibir o valor do atributo dentro de uma div em nossa savefunção:
Nota: Depois de fazer essa alteração, você receberá um bloco quebrado na postagem à qual já adicionou esse bloco. Isso acontece porque o editor encontra uma saída diferente da saveque definimos agora. Remova o bloco e adicione-o novamente. Digite algo em sua entrada de texto, atualize a postagem e visualize-a no frontend.
E esta é a essência disso, na verdade. Você decide quais atributos você precisa para salvar o que deseja em seu bloco. Em editvocê renderizará formas para o usuário inserir, cuidando para que os valores atuais sejam exibidos e os atualize sempre que forem alterados. E em savevocê extrai os atributos salvos e renderiza a saída como quiser.
Abordaremos muito mais componentes e atributos diferentes à medida que avançamos nesta série de tutoriais. Mas vamos ver um outro componente neste post para ver do que sourcese trata a propriedade do atributo.
RichText e a propriedade de atributosource
O componente do WordPress RichTextoferece uma área de texto “sem bordas” com suporte para formatação de texto. Você pode preferir usar isso em vez de uma entrada de texto padrão (feia?) ou área de texto. Mas lembre-se de que isso RichTextdeve ser tratado de forma um pouco diferente, pois há vários adereços que você precisa conhecer, e há uma diferença em como obtemos o valor em nossa savefunção.
Adicionando um RichTextcomponente
A forma mais simples RichTexté implementá-lo como você faria com uma entrada de texto:
Nós desestruturamos o RichTextcomponente do wp.blockEditorpacote, mas fora isso o que foi dito acima é idêntico ao que fizemos com a entrada de texto padrão.
Manipulando savecomRichText
Porém na savefunção você precisa usar o RichTextcomponente novamente para obter o valor do atributo. Chamamos RichText.Contente configuramos o prop valuepara nosso atributo:
Isso produzirá o que foi digitado no RichTexteditor diretamente sem qualquer HTML envolvido.
Quando você trabalha com RichTextvocê provavelmente deseja controlar o wrapper HTML em torno do texto, por exemplo a <p>ou a <h2>, tanto no frontend quanto no editor. Para isso podemos usar um prop chamado tagName.
O componente RichTextpermite vários outros adereços também. Você pode definir um texto de espaço reservado que está sendo mostrado (desbotado) quando está vazio com o placeholderprop. O componente também permite controlar quais opções de formatação o campo permite (quais botões ele mostra na barra de ferramentas).
RichTextcomtagName
Com a prop tagNamevocê pode predefinir em qual tag HTML sua saída será encapsulada. Quando você usar tagNamevocê deve usar a mesma tagNameprop e valor em ambos edite save.
Digamos que você queira colocar seu valor de atributo em um <h2>, que no editor forçará qualquer entrada a ser um h2. Em editvocê pode fazer:
E em save:
O acima agora produzirá o que foi digitado na RichTextárea dentro de uma <h2>tag.
Usandosource
Obviamente, você pode combinar vários richtext para um bloco, por exemplo, um para o título e outro para um parágrafo. Apenas lembre-se de que cada um precisará de seu próprio atributo. Por exemplo:
No entanto, agora você começará a encontrar alguns problemas. Mesmo que você possa fazer a formatação de texto no editor, nada (ou parte) da sua formatação não será salvo. Quando você visualizar o post no frontend, ele simplesmente sairá como h2e um p, sem nenhuma formatação que você tenha feito (itálico, negrito, link). Nem mesmo o bloco de comentários do seu bloco contém a formatação. Esta é a coisa complicada com RichText. Para resolver isso precisamos trabalhar com a propriedade do atributo source.
A sourcepropriedade que permite ao WordPress extrair e interpretar o conteúdo diretamente do conteúdo do post. Se um atributo não tiver um sourceconjunto, ele será salvo e extraído do bloco de comentários HTML.
Ao trabalhar com RichText, geralmente definimos sourcecomo html, que usa a biblioteca do WordPress para analisar a marcação HTML. A propriedade sourcefunciona em conjunto com outra propriedade de atributo; selectorque define de qual tag HTML ele deve extrair.
Como exemplo, definimos sourcecomo htmlem nosso parágrafo RichTexte definimos selectorcomo p(caso contrário, o padrão é a raiz do bloco do bloco).
attributes: {
...
myRichText: {
type: 'string',
source: 'html',
selector: 'p'
}
},Agora nosso segundo RichTextdeve salvar com sucesso toda a sua formatação de texto. Você também notará que o bloco de comentários agora exibe apenas o myRichHeadingatributo em JSON. O atributo myRichTextdesapareceu completamente do bloco de comentários. Isso ocorre porque com sourceo WordPress agora analisa o conteúdo da postagem em vez do bloco de comentários para o valor do atributo.
Para ser perfeitamente honesto, não trabalhei muito com o sourceatributo e recomendo evitá-lo se puder. A documentação do WordPress explica um pouco mais sobre a fonte e os atributos que você deseja verificar por si mesmo.
Neste post aprendemos o básico sobre atributos; como defini-los, atualizá-los e gerar seus valores. Nas próximas etapas, veremos mais componentes diferentes e como adicionar configurações fora do próprio conteúdo do bloco; na barra de ferramentas e na barra lateral do editor (chamada Inspetor).