Como acessar e analisar blocos do Gutenberg com PHP

Neste post, veremos como analisar os blocos Gutenberg de um post e extrair blocos específicos para fazer outra coisa. Veremos as funções PHP do WordPress para analisar, extrair e renderizar os blocos escolhidos.

Um benefício do novo editor Gutenberg no WordPress são dados mais estruturados para o conteúdo do post. Antigamente, tudo era armazenado como HTML e não havia como extrair partes específicas de conteúdo sem algumas expressões regulares muito complexas. Mas com Gutenberg cada parte do conteúdo, seja um parágrafo, título, imagem, vídeo, botão ou uma coluna que tenha outros blocos dentro dela, é armazenada com informações que nos dizem qual é essa parte do conteúdo.

Com as funções integradas do WordPress, é muito fácil buscar todos os blocos no conteúdo de uma postagem em uma matriz com todas as suas informações. Isso abre muitos recursos úteis para desenvolvedores de temas. Só para citar algumas ideias:

• Gere dinamicamente um sumário buscando todos os títulos (tutorial abaixo).
• Busque todos os vídeos, imagens ou citações usados ​​em todas as postagens para reunir e listá-los em outra página.
• Extraia o primeiro parágrafo de um post e use-o como trecho nos arquivos (tutorial abaixo).
• Obtenha uma visão geral do uso de blocos específicos e sua posição. Por exemplo, digamos que você tenha um bloco de anúncios personalizado e precise saber com que frequência ele é usado em suas postagens e até que ponto eles aparecem no conteúdo.
• Renderize os blocos de uma postagem, mas exclua tipos de blocos específicos.
• Verifique se o conteúdo de uma postagem começa com um vídeo e use esse vídeo em vez da imagem em destaque nos arquivos.
• Se você usar um bloco personalizado que contém especificações técnicas de produtos, poderá criar facilmente uma página que exiba e compare as especificações técnicas em postagens de produtos.
• Reúna dinamicamente todas as imagens únicas usadas em uma postagem e gere uma galeria delas no final ou em outro lugar.

Vamos pular direto para isso!

Analisar os blocos de uma postagem

Para analisar blocos usamos a função WordPress [parse_blocks](https://developer.wordpress.org/reference/functions/parse_blocks/)(). Como parâmetro, você precisa fornecer uma string do conteúdo de uma postagem. Se você estiver dentro de um loop ou tiver acesso a um objeto post simplesmente forneça $post->post_contentcomo parâmetro para a função.

O retorno de parse_blocks()é um array onde cada elemento do array é um bloco. Para cada elemento de bloco você tem informações como tipo de bloco (chave ‘ blockName‘), atributos do bloco (chave ‘ attrs‘), blocos internos para blocos aninhados como Colunas (chave ‘ innerBlocks‘) e dois elementos para o conteúdo real do bloco (chaves ‘ innerHTML‘ e ‘ innerContent‘). O elemento innerHTMLé uma string de conteúdo HTML, enquanto innerContenté uma matriz de strings HTML.

E isso é tudo! Percorra o array retornado de parse_blocks()para fazer o que você quer. Veremos mais exemplos de código disso mais adiante neste post.

Uma nota sobre posts clássicos (não-Gutenberg)

Você pode estar trabalhando em um site WordPress mais antigo que criou postagens antes de atualizar para o Gutenberg (ou usou um plug-in Desativar Gutenberg). Nesse caso, essas postagens não terão conteúdo de postagem estruturado, mas todo o conteúdo da postagem estará dentro de um bloco "Editor clássico".

O array retornado da função parse_blocks()neste tipo de post retornará um elemento de array de bloco com blockNamedefinido como null. O conteúdo HTML completo do post está dentro da innerHTMLstring deste elemento.

Podemos assumir com segurança que se o retorno de um post parse_blocks()tem um elemento e blockNameé null, estamos lidando com um post “pré-Gutenberg". Caso contrário blockName, será sempre preenchido. Esta é uma boa verificação para se ter em mente ao escrever código para analisar os blocos de postagens e você deseja lidar com conteúdo mais antigo do WordPress.

Renderizar um bloco

O WordPress também oferece uma função para renderizar um bloco específico com [render_block](https://developer.wordpress.org/reference/functions/render_block/)(). Como parâmetro você precisa fornecer um array para um bloco, assim como um daqueles retornados de parse_blocks()cima. A função retorna uma string de HTML renderizado que você pode simplesmente ecoar diretamente.

O código acima irá renderizar todos os blocos do post, exatamente como faria normalmente ao renderizar o conteúdo do post. A parte divertida vem quando começamos a adicionar código para excluir ou incluir blocos específicos nos quais estamos interessados.

Por exemplo, o código abaixo imprimirá apenas os blocos de parágrafos do post:

foreach ($blocks as $block) {
    if ($block['blockName'] == 'core/paragraph') {
        echo render_block($block);
    }
}

E isso renderizará todos os blocos, mas excluirá todos os blocos de shortcode:

foreach ($blocks as $block) {
    if ($block['blockName'] != 'core/shortcode') {
        echo render_block($block);
    }
}

Nomes de bloco

Ao analisar os blocos de uma postagem, você provavelmente precisará verificar o tipo do bloco. Eles são bem simples de adivinhar. Por exemplo, um bloco de parágrafo é, bem, você adivinhou, paragraph. No entanto, lembre-se de que todos os blocos do Gutenberg no WordPress são prefixados com um namespace. Para os blocos principais do WordPress (padrão), todos eles são prefixados com ” core/“. A exceção são os blocos Embed que são prefixados com ” core-embed/“. Assim, por exemplo, um bloco de parágrafo terá o nome do bloco core/paragraph.

Para evitar adivinhações, aqui está uma visão geral dos blocos padrão fornecidos pelo WordPress (no momento em que escrevo isso):

Blocos comuns

• Parágrafo:core/paragraph
• Imagem:core/image
• Cabeçalho:core/heading
• Galeria:core/gallery
• Lista:core/list
• Citar:core/quote
• Áudio:core/audio
• Cobrir:core/cover
• Arquivo:core/file
• Vídeo:core/video

Formatação

• Pré-formatado:core/preformatted
• Código:core/code
• Clássico: core/freeform
  (mas para postagens não-Gutenberg será null, veja a nota sobre postagens não-Gutenberg)
• HTML personalizado:core/html
• Citação:core/pullquote
• Mesa:core/table
• Versículo:core/verse

Esquema

• Botão:core/button
• Colunas:core/columns
• Mais:core/more
• Quebra de página:core/nextpage
• Separador:core/separator
• Espaçador:core/spacer
• Mídia e texto:core/media-text

Widgets

• Código curto:core/shortcode
• Arquivos:core/archives
• Categorias:core/categories
• Últimos Comentários:core/latest-omments
• Últimas postagens:core/latest-posts

Incorporações

• Embutir:core/embed

• Twitter:core-embed/twitter

• Youtube:core-embed/youtube

• Facebook:core-embed/facebook

• Instagram:core-embed/instagram

• WordPress:core-embed/wordpress

• SoundCloud:core-embed/soundcloud

• Spotify:core-embed/spotify

• Flickr:core-embed/flickr

• Vimeo:core-embed/vimeo

• Animado:core-embed/animoto

• Nuvem:core-embed/cloudup

• Crowdsignal:core-embed/crowdsignal

• Movimento diário:core-embed/dailymotion

• Hulu:core-embed/hulu

• Imgur:core-embed/imgur

• Questão:core-embed/issuu

• Iniciador:core-embed/kickstarter

• Meetup. com:core-embed/meetup-com

• Mixcloud:core-embed/mixcloud

• Reddit:core-embed/reddit

• ReverbNation:core-embed/reverbnation

• Screencast:core-embed/screencast

• Scribd:core-embed/scribd

• Compartilhamento de slides:core-embed/slideshare

• SmugMug:core-embed/smugmug

• Plataforma de alto-falante:core-embed/speaker

• TED:core-embed/ted

• Tumblr:core-embed/tumblr

• VideoPress:core-embed/videopress

• wordpress.tv:core-embed/wordpress-tv

• Amazon Kindle:core-embed/amazon-kindle

Exemplo de código: buscar o primeiro parágrafo de uma postagem como trecho

Um post bem escrito deve começar com um parágrafo que apresente o assunto do post e tente as pessoas a continuar lendo. Eles são perfeitos para usar como trechos em vez de depender da função de trecho automático no WordPress!

Esta é uma função que você pode adicionar ao seu tema functions.phpque retornará o primeiro parágrafo de um post. Se nenhum post foi fornecido, ele se referirá ao objeto global post. Ele também acomoda postagens que não são de Gutenberg, retornando o trecho real do WordPress para elas.

Após a parse_blocks()chamada da função, verificamos se o post tem ou não dados de bloco inválidos (o post foi criado antes do Gutenberg) e retornamos o trecho do post se for o caso. Caso contrário, percorremos os blocos da postagem, encontramos o primeiro bloco de parágrafo e retornamos seu innerHTML. No final, retornamos uma string com (isso é opcional) a <div>em torno dela.

Para usar esta função tudo que você precisa fazer é chamar:

echo awp_get_excerpt();

Supondo que a chamada da função seja colocada em algum lugar, há um $postobjeto global, por exemplo, dentro de um loop. Se você quiser especificar um post, forneça o objeto post como parâmetro para a chamada de função:

$post_id = 1;
$post = get_post($post_id);
echo awp_get_excerpt($post);

Exemplo: criar um índice a partir dos títulos de uma postagem

Você pode gerar automática e dinamicamente um índice com base nos blocos de cabeçalho de uma postagem. O processo é bastante simples; analise os blocos do post e encontre todos os blocos do tipo core/heading. Mas podemos dar um passo adiante e incorporar níveis; por exemplo, colocando h3como subtítulo sob h2e assim por diante.

Um bloco de cabeçalho contém informações sobre seu nível no elemento da matriz de atributos (chave ‘ attrs‘). Dentro do attrsarray seria um elemento do array com a chave ‘ level‘ e um inteiro significando o nível. A h3teria ‘ level‘ valor de 3, a h4teria ‘ level‘ de 4, e assim por diante.

No entanto, observe que os attrsblocos de cabeçalho podem estar vazios! Isso acontece quando o autor não alterou o tipo de título para fora dos padrões nas configurações do bloco. Para contornar isso, precisamos fazer algumas suposições. Como os títulos padrão serão h2(a menos que você tenha alterado isso em seu tema). Portanto, podemos supor que, se um bloco de cabeçalho não tiver um atributo de nível, é um h2. Caso contrário, obtemos as informações de nível dos atributos.

Se você realmente está à altura do desafio, convido você a melhorar o código abaixo. A questão de gerar uma ollista bem estruturada é que não podemos controlar como o autor estrutura seus títulos. Eles podem muito bem enlouquecer e começar com um h4título e pular direto para um h2título logo depois. E de repente eles misturam um h1no meio. Minha solução, portanto, envolve gerar uma ollista simples e fornecer as informações de nível nas classes do item da lista. Então, com algum CSS inteligente, você pode recuar os itens da lista de acordo com algum preenchimento esquerdo.

O código

Aqui está a função de índice:

A função começa com a manipulação da postagem e a análise de seus blocos. Na linha #9, acomodamos posts que não sejam Gutenberg. A função continua a percorrer todos os blocos e sempre que encontra um bloco de cabeçalho, ele é adicionado ao nosso $headingsarray. Usamos [wp_strip_all_tags](https://developer.wordpress.org/reference/functions/wp_strip_all_tags/)()para retirar as tags HTML dos títulos. Também adicionamos as informações de nível ao nosso array, onde o padrão é definido como 2se os atributos estiverem vazios.

Após o loop de blocos, o $headingsarray deve conter todos os títulos do post, em ordem. Podemos então simplesmente gerar uma string HTML e produzir seu conteúdo. Como mencionado, gerei um nome de classe em cada elemento com informações sobre o nível do cabeçalho para que possamos criar a ilusão de uma lista estruturada com CSS.

Como com a função de excerto acima, podemos chamar esta função quando estamos dentro do loop assim:

echo awp_table_of_contents();

Ou se estamos fora do loop ou queremos especificar um post;

$post_id = 1;
$post = get_post($post_id);
echo awp_table_of_contents($post);

Isso gerará uma lista parecida com esta:

Conclusão

Como vimos com o conteúdo de postagem rico estruturado possibilitado pelo Gutenberg, podemos encontrar e extrair facilmente partes específicas do conteúdo das postagens. Consulte a lista de exemplos que mencionei no início do post. Não há limites para o que você, como desenvolvedor de temas, pode fazer. Depende apenas do que o seu tema ou site WordPress precisa (ou o que seria simplesmente legal).