Criar bloco personalizado do Gutenberg – Parte 9: blocos dinâmicos e renderização do PHP

Até agora, renderizamos a saída do bloco em Javascript. No entanto, com conteúdo dinâmico como postagens recentes ou exibindo uma postagem, precisamos renderizar a saída do bloco em PHP. Neste post vamos aprender como e por quê.

Por que precisamos lidar com blocos dinâmicos de maneira diferente?

Alguns exemplos são óbvios; um bloco que exibe as últimas postagens em uma categoria é dinâmico porque as postagens mudam com o tempo. Você não escolhe os posts no bloco; em vez disso, você provavelmente terá configurações para escolher a categoria, quais informações mostrar para cada postagem, o número de postagens, o número de colunas e assim por diante. Toda vez que o WordPress carrega um post com este bloco, ele precisa consultar o WordPress naquele momento para os posts mais recentes. Visualizar a mesma postagem no mês seguinte pode gerar resultados diferentes, mesmo que a postagem com o bloco em si não tenha sido atualizada.

Mas a necessidade de blocos dinâmicos às vezes não é tão óbvia. Você pode imaginar um bloco de postagem em destaque onde você escolhe um post específico para exibi-lo, não é necessariamente dinâmico. Mas pode ser – e deve ser. Lembre-se de que a postagem selecionada pode atualizar seu título, trecho ou imagem em destaque a qualquer momento – e isso deve ser refletido nos blocos que apresentam esta postagem.

Para fazer um bloco não dinâmico para mostrar uma única postagem, você precisará salvar o ID da postagem, sua URL, URL da imagem em destaque, sequência de trechos ou o que for necessário para visualizar a postagem nos atributos do bloco. E aqui reside o problema. Se você atualizar a imagem em destaque da postagem selecionada, a postagem com o bloco de postagem em destaque não atualizará automaticamente seus atributos. Ele ficará salvo com o URL da imagem em destaque antiga. Somente quando você editar o post com o bloco, e certificar-se de que ele salva novamente os atributos com as informações atualizadas, o bloco mostrará as informações atualizadas corretas.

Portanto, sempre que lidamos com conteúdo dinâmico – postagens, categorias ou qualquer coisa que possa mudar com o tempo – estamos lidando com blocos dinâmicos. E para blocos dinâmicos, precisamos usar PHP – código do lado do servidor – para renderizar nosso bloco para garantir que ele recuperará informações atualizadas toda vez que renderizar.

A natureza alterada dos blocos dinâmicos no editor

Quando você começar a desenvolver blocos dinâmicos, a natureza do seu bloco dentro do editor mudará. A função do seu bloco editgeralmente precisa ser dinâmica também. Por exemplo, para um bloco de postagem em destaque, você precisará buscar postagens para escolher ou, para um bloco de notícias mais recente, precisará recuperar uma lista de categorias para o usuário escolher.

É totalmente possível solicitar informações do WordPress de dentro do editor fazendo solicitações AJAX – seja usando pacotes e componentes ou executando-os manualmente com a API REST do WordPress. Independentemente do método que você usar, seu bloco precisa lidar com o fluxo assíncrono de entrada – o período de tempo enquanto aguarda uma resposta.

Existem vários métodos e padrões para criar um bloco dinâmico para Gutenberg. Mais comumente, você usará um padrão React chamado componentes de ordem superior, nos quais o WordPress fornece muitas funções e componentes.

Veremos como buscar postagens e como recuperar categorias em nosso bloco na próxima parte do tutorial. Por enquanto precisamos aprender como fazer o PHP renderizar nosso bloco.

Preparando nosso bloco para renderização em PHP

A parte principal que precisamos fazer em Javascript é fazer a savefunção do bloco retornar null. Você pode manter a saída original, mas assim que dissermos ao WordPress para usar PHP para renderizar o bloco, isso será ignorado. Para deixar claro para nós e para os outros que a saída do bloco não é tratada em Javascript, vamos alterar a savefunção.

Não esqueça que alterar a função salvar fará com que todos os blocos existentes sejam quebrados. Adicione novamente o bloco. O bloco deve funcionar como antes; com as configurações e atualizando os atributos. Ele agora simplesmente não produzirá nada no frontend. O bloco de comentários estará lá, armazenando todos os atributos em JSON, mas nenhum HTML visível será renderizado.

No entanto; se algum de seus atributos estiver usando a sourcepropriedade, você precisará alterar isso. Isso não é suportado com blocos que são renderizados com PHP porque eles são analisados ​​diretamente da saída do save – que agora retornamos null. Usamos source no segundo RichTextem nosso bloco – para o parágrafo. Neste ponto, o editor não salvará o que você colocar RichTextnele.

Portanto, se você ainda estiver usando sourceo myRichTextatributo, precisamos remover as propriedades sourcee selectorpara garantir que os atributos sejam armazenados e não analisados ​​da savefunção:

attributes: {
    ...
    myRichText: {
        type: 'string',
    },
    ...

Depois disso nosso bloco está pronto para renderização em PHP. Podemos deixar os arquivos Javascript (não esqueça de compilar) e o resto é feito em PHP.

Renderizando blocos em PHP

Para dizer ao WordPress para renderizar a saída do bloco em PHP, adicionamos um novo argumento à função register_block_type(). Precisamos adicionar a chave render_callbackao array com um valor da função que deve ser executada.

A função de renderização do PHP

Vamos definir a função awp_myfirstblock_rendermais abaixo functions.php(ou onde quer que você tenha colocado seu código PHP). Nossa função receberá dois parâmetros; vamos chamá-los $attre $content.

function awp_myfirstblock_render($attr, $content) {
    // return the block's output here
}

O parâmetro $attrserá um array associativo com todos os atributos salvos. O segundo parâmetro, $content, é para blocos dentro do nosso bloco. Isso é relevante apenas para blocos que suportam blocos aninhados – o que, por exemplo, Colunas ou Capa fazem.

A função nunca deve echosair nada. Toda a saída deve ser retornada, então você precisa construir uma string e devolvê-la no final.

Algo importante a ser lembrado sobre os atributos é que apenas os atributos salvos aparecerão no primeiro parâmetro da função. Se um atributo nunca foi realmente alterado e salvo – ou seja, apenas confiando em seu default, o atributo não será incluído em nossa função PHP.

Você precisa lidar com esse problema sempre verificando if (isset($attr['...']))ou da maneira preferível: definindo os atributos em nossa register_block_type()chamada. Podemos fornecer outra chave, attributes, e definir seu valor para um array com todos os atributos que desejamos extrair do nosso bloco. A estrutura deve ser idêntica à que você definiu em Javascript, mas em vez de um objeto Javascript você precisa dele em um array PHP. Isso pode ser um pouco complicado para redefinir os mesmos atributos, mas com um editor de código inteligente deve ser bem rápido copiar + colar e editar em várias linhas em PHP.

Adicionando os atributos para nossa função de renderização

Vamos adicionar o novo attributeselemento register_block_type()e colar exatamente os mesmos atributos que definimos em nosso arquivo Javascript:

Tenha em mente que se você definir a defaultpara todos os atributos, o $attrparâmetro da sua função deve sempre conter todos os atributos. Por exemplo, o atributo textAlignmentacima só existirá $attrse tiver sido alterado – e você precisará verificar isset($attr['textAlignment']).

Infelizmente, no momento, há duas coisas que você não vai conseguir com o PHP block render. Um é o classNameprop – então você precisa construir a classe de encapsulamento (se quiser) você mesmo. A outra é a supportpropriedade para alinhamento de blocos. No momento o WordPress não está suportando esta propriedade em blocos dinâmicos. Não obteremos o valor do alinhamento de bloco escolhido, a menos que o transformemos em um atributo e o tratemos manualmente em Javascript.

Quanto à saída HTML da função, isso depende totalmente de você!

Solicitando renderização do PHP de dentro do editor

É possível solicitar a renderização do PHP do nosso bloco dentro do editor. Isso é útil se você quiser visualizar a saída do bloco no editor. Podemos fazer isso com um componente chamado ServerSideRenderdo wp.editorpacote.

Como adereços, ServerSideRendervocê precisa definir todos os atributos que deseja passar. No mínimo, você precisa fornecer o nome do bloco para o prop block, para que o WordPress saiba qual método de renderização procurar. Isso está disponível para você na props.namefunção edit. Você também precisa fornecer quaisquer atributos necessários no prop attributes. Se desejar, você também pode adicionar variáveis ​​personalizadas fora dos atributos aqui. Apenas tenha em mente que isso só funcionará para o editor interno, e não para o frontend.

Você não pode usar ServerSideRenderna função do bloco save. Sua savefunção ainda deve retornar null.

Vamos implementar ServerSideRenderem nosso bloco para ver na prática.

Usando ServerSideRender para o modo de visualização/edição de bloco

Se você seguiu a etapa anterior, onde criamos uma alternância de modo de visualização/edição para nosso bloco, agora podemos usar ServerSideRenderpara renderizar a visualização do bloco do PHP quando alternamos para o modo de visualização.

Primeiro precisamos lembrar de desestruturar ServerSideRenderno topo:

const { ServerSideRender } = wp.editor;

Se você se lembra do passo anterior, usamos os componentes Disablede/ou Placeholderpara realizar a visualização. O problema com o uso Placeholderé que temos um estilo indesejado aplicado à nossa saída. Vamos substituir Placeholderpor ServerSideRender. Você pode optar por manter o Disabledcomponente, para garantir que nenhum conteúdo seja clicável ou arrastável.

No código para renderizar o bloco quando o atributo editModefor false, fazemos:

Agora, nosso botão personalizado na barra de ferramentas renderizará a saída do PHP quando mudarmos para o modo de visualização. A saída deve ser idêntica ao visualizar o post no frontend. Este é um bom hábito para garantir que a saída seja idêntica no editor e no frontend.

Exemplo: bloco dinâmico mostrando uma postagem selecionada

A saída em sua função de renderização PHP pode ser qualquer coisa e você tem acesso total a todas as funções do WordPress. Suponha um bloco onde um ID de postagem será salvo em um atributo. Na render_callbackfunção PHP você pode consultar a postagem do ID e gerar suas informações. Deve ser bastante auto-explicativo como fazer isso, mas aqui está um exemplo rápido.

NB: Neste exemplo, simplesmente adicionaremos uma entrada de texto ao editor para inserir manualmente um ID de postagem. Esta não é uma solução muito intuitiva e fácil de usar para selecionar uma postagem – mas é isso que aprenderemos na próxima etapa. O foco aqui é na parte do PHP de renderizar o post selecionado.

Vamos adicionar um atributo selectedPostIddo tipo number:

attributes: {
    selectedPostId: {
        type: 'number'
    }
}

E em algum lugar dentro da função do nosso bloco editadicionamos um TextControlcomponente. Pode ser onde você quiser – dentro do bloco ou no Inspetor.

Observe que estou tomando cuidado extra para garantir que a entrada salve o atributo corretamente como um número, convertendo-o em inteiro com parseInt(). Embora tenhamos definido o tipo prop typepara numberrenderizar uma entrada numérica, o valor alterado ainda é interpretado como uma string. O WordPress não salvará seu atributo se estiver no formato errado.

Não se esqueça de adicionar o novo atributo ao seu ServerSideRendercomponente se você tiver um:

A parte do PHP

Isso deveria ter cuidado da parte do Javascript. Vamos para o PHP. Primeiro, precisamos adicionar o novo atributo selectedPostIdao attributesarray em register_block_type():

Na render_callbackfunção agora podemos acessar o ID do post com $attr['selectedPostId']. Podemos com isso fazer um simples get_post()e gerar os dados do post; seu link e título:

Este é um exemplo muito básico que serve como um trampolim para você escrever um código mais avançado e personalizado.

Agora que sabemos como lidar com a renderização de blocos dinâmicos, o próximo passo é aprender como tornar a parte do editor mais intuitiva também. Na próxima etapa, focaremos em como consultar postagens de dentro do editor de blocos e fornecer ao usuário uma maneira melhor de selecionar uma postagem.