Criando blocos para sites em WordPress

Recentemente publiquei no meu GitHub a minha primeira experiência na criação de blocos para sites em WordPress. O plugin Evolution Post List cria um bloco para listagem dos posts de uma forma que não era possível por blocos padrão.

Atualmente o WordPress estabeleceu um novo conceito em que todo o design do site é construído e publicado pelo editor de blocos, ao invés dos temas codificados em PHP. Essa abordagem low-code é bastante útil para quem precisa fazer ajustes no design e conteúdo sem tocar no código.

A desvantagem deste novo paradigma, no entanto, é que os recursos que não são nativos da plataforma precisam ser incorporados como blocos no editor visual, seja via plugins ou diretamente ao tema.

Já falei um pouco dos desafios do tema de blocos quando o tema Evolution ficou disponível no diretório de temas públicos do WordPress. Aqui abordarei o caso específico do Evolution Post List.

Por quê precisei criar um bloco?

O problema envolveu a formatação do código HTML para a listagem de posts na página inicial e arquivos do blog. O resultado final esperado era fazer com que o link agisse, após a estilização com CSS, como uma flexbox que permitisse a diagramação dos componentes e os direcionando para o post em questão.

Só que não foi possível utilizar um modelo em que eu conseguisse envelopar o título, as categorias e, quando aplicável, resumo e a imagem destacada em um link para a publicação.

Os blocos padrão colocavam o link para o post somente na imagem destacada e no título. Categorias listadas continham links pra as páginas de cada categoria. Além disso, o resumo não tinha a opção de link, bem como a diagramação de colunas faria o design quebrar caso o post não tivesse uma imagem destacada.

Portanto, a solução foi criar um bloco para gerar a saída HTML que eu precisava.

<a href="[link para o post]" title="[título do post]">
    [thumbnail, se existir]
    <section class="wp-block-group">
    	[categorias do post]
        <h3>[título do post]</h3>
        [resumo do post, se existir]
        [leia mais]
    </section>
</a>

Anatomia de um bloco

Um bloco do WordPress possui duas partes. Uma parte em PHP, responsável por exibir o conteúdo na página para o visitante. A outra parte, em JavaScript utilizando a biblioteca React, para exibir o conteúdo no editor visual dentro do painel de administração.

O WordPress fornece um esqueleto para iniciar o desenvolvimento de blocos. A etapa da saída do código para o site não é tão complexa, já que basicamente seria como programar um plugin convencional. Apenas é necessário realizar o registro do bloco através de funções e actions.

Contudo, a parte mais complicada está na parte de exibição no editor de blocos, que exige uma certa pesquisa no uso de componentes, hooks e dependências. Ler a documentação, além de ver (e reutilizar, se for o caso) os códigos dos blocos nativos do WordPress ajudam a entender como eles funcionam.

No caso, um dos desafios foi realizar a extração de dados dos posts (título, URL da imagem destacada, categorias e resumo) para a exibição no editor de blocos utilizando React ao invés do PHP.

Bônus: Usando controllers para criar novos recursos no bloco

Aproveitei para explorar um pouco mais e controlar, via interação no editor de blocos, opções de visualização que seriam manuseadas via PHP ou por atributos passados diretamente nos arquivos HTML.

Isso elimina não só pequenas edições de código, mas também dá mais flexibilidade ao utilizar o bloco. Inclusive ao disponibilizá-lo para a comunidade.

O bloco Evolution Post List permite exibir ou ocultar categorias, resumo e a sentença “leia mais” dos itens da listagem dos posts. Também há opções de personalização específica para os posts em destaque.

Para isso, o bloco utiliza atributos definidos no theme.json:

{
...
   "attributes": {
      "className": {
         "type": "string"
      },
      "showCategory": {
         "type": "boolean",
         "default": true
      },
      "showExcerpt": {
         "type": "boolean",
         "default": false
      },
      "showReadMore": {
         "type": "boolean",
         "default": false
      },
      "showCategoryOnSticky": {
         "type": "boolean",
         "default": true
      },
      "showExcerptOnSticky": {
         "type": "boolean",
         "default": true
      },
      "showReadMoreOnSticky": {
         "type": "boolean",
         "default": true
      }
   },
...
}

Os controles aparecem na barra lateral de configurações de bloco utilizando componentes, como o InspectorControls e o ToggleControl. As alterações passam para a visualização do bloco, e salvas junto com a página.

...
   <InspectorControls>
      <PanelBody title={ __( 'Settings' ) }>
         <ToggleControl
            __nextHasNoMarginBottom
            label={ __( 'Show Categories' ) }
            checked={ showCategory }
            onChange={ toggleAttribute( 'showCategory' ) }
         />
         <ToggleControl
            __nextHasNoMarginBottom
            label={ __( 'Show excerpt' ) }
            checked={ showExcerpt }
            onChange={ toggleAttribute( 'showExcerpt' ) }
         />
         <ToggleControl
            __nextHasNoMarginBottom
            label={ __( 'Show "Read More" text' ) }
            checked={ showReadMore }
            onChange={ toggleAttribute( 'showReadMore' ) }
         />
      </PanelBody>
      <PanelBody title={ __( 'Sticky Post Settings' ) }>
         <ToggleControl
            __nextHasNoMarginBottom
            label={ __( 'Show Categories' ) }
            checked={ showCategoryOnSticky }
            onChange={ toggleAttribute( 'showCategoryOnSticky' ) }
         />
         <ToggleControl
            __nextHasNoMarginBottom
            label={ __( 'Show Excerpt' ) }
            checked={ showExcerptOnSticky }
            onChange={ toggleAttribute( 'showExcerptOnSticky' ) }
         />
         <ToggleControl
            __nextHasNoMarginBottom
            label={ __( 'Show "Read More" text' ) }
            checked={ showReadMoreOnSticky }
            onChange={ toggleAttribute( 'showReadMoreOnSticky' ) }
         />
      </PanelBody>
   </InspectorControls>
...

O repositório com o código fonte está disponível no meu GitHub. A documentação oficial fornece outras informações de como criar blocos customizados para o WordPress.