Pular para o conteúdo

Composição de templates com tags de bloco

Quando um projeto tem alguns blocos, os templates começam a depender uns dos outros. Um bloco features quer exibir três cartões. Uma página inicial quer uma seção com um botão dentro dela. Você pode chamar bs_render_block() para cada um, mas um template repleto de chamadas PHP com arrays aninhados é difícil de ler e ainda mais difícil de aninhá-las.

As tags de bloco permitem escrever um bloco onde sua saída deve aparecer, como uma tag HTML:

HTML
<bs:acme-card title="Fast" text="Rendered on the server." />

A mesma tag tem dois significados diferentes, dependendo de onde é escrita. Em um template de bloco ou no conteúdo de uma publicação, ela é substituída pela saída renderizada do HTML bloco. Em uma página, padrão ou fonte de Site Template, ela se torna um bloco WordPress real que aparece no editor. Este guia cria alguns blocos, compõe-os das duas maneiras, adiciona um prefixo de projeto para nomes mais curtos e depois mostra como migrar essas abreviações de volta à grafia portátil.

Os blocos

Três blocos pequenos são suficientes. Um cartão com dois campos:

JSON
{
  "$schema": "https://blockstudio.dev/schema/block",
  "apiVersion": 3,
  "name": "acme/card",
  "title": "Card",
  "blockstudio": {
    "attributes": [
      { "id": "title", "type": "text", "label": "Title", "default": "" },
      { "id": "text", "type": "textarea", "label": "Text", "default": "" }
    ]
  }
}
PHP
<article useBlockProps class="acme-card">
  <h3><?php echo esc_html( $a['title'] ); ?></h3>
  <p><?php echo esc_html( $a['text'] ); ?></p>
</article>

Uma seção que envolve o que quer que seja colocado dentro dela, com um campo heading declarado da mesma forma que o do cartão:

PHP
<section useBlockProps class="acme-section">
  <h2><?php echo esc_html( $a['heading'] ); ?></h2>
  <InnerBlocks />
</section>

E um botão em um segundo namespace, acme-ui/button, com os campos label e href:

PHP
<a useBlockProps class="acme-button" href="<?php echo esc_url( $a['href'] ); ?>"><?php echo esc_html( $a['label'] ); ?></a>

Tags dentro de um template de bloco

Templates de bloco renderizam tags automaticamente. Não é necessária nenhuma configuração. Um bloco features pode exibir dois cartões e um separador do core diretamente:

PHP
<div useBlockProps class="acme-features">
  <bs:acme-card title="Fast" text="Rendered on the server." />
  <block name="acme/card" title="Typed" text="Fields come from block.json." />
  <block name="core/separator" />
</div>

A renderização de acme/features produz:

HTML
<!--blockstudio/acme/features--><div class="acme-features wp-block-acme-features">
  <!--blockstudio/acme/card--><article class="acme-card wp-block-acme-card">
  <h3>Fast</h3>
  <p>Rendered on the server.</p>
</article>

  <!--blockstudio/acme/card--><article class="acme-card wp-block-acme-card">
  <h3>Typed</h3>
  <p>Fields come from block.json.</p>
</article>

  <hr class="wp-block-separator has-alpha-channel-opacity">
</div>

Cada bloco Blockstudio na saída é precedido por um comentário <!--blockstudio/namespace/slug-->. O buffer da página o remove da resposta; para saídas que ignoram o buffer, use bs_strip_render_markers(). As duas sintaxes são equivalentes. <bs:acme-card> codifica o nome do bloco na tag, e <block name="acme/card"> o passa como atributo. Todos os outros atributos se tornam valores de campos, então title chega ao template do cartão como $a['title']. Os blocos do núcleo também funcionam, renderizados por WordPress com os renderizadores de blocos integrados.

Tags pareadas e conteúdo interno

Uma tag pareada passa seus elementos filhos ao bloco. Para um bloco Blockstudio, eles preenchem <InnerBlocks />, e as tags aninhadas são renderizadas primeiro:

HTML
<bs:acme-section heading="Why Acme">
  <bs:acme-card title="Fast" text="Rendered on the server." />
  <bs:acme-ui-button label="Get started" href="/start" />
</bs:acme-section>
HTML
<!--blockstudio/acme/section--><section class="acme-section wp-block-acme-section">
  <h2>Why Acme</h2>
  <div>
  <!--blockstudio/acme/card--><article class="acme-card wp-block-acme-card">
  <h3>Fast</h3>
  <p>Rendered on the server.</p>
</article>

  <!--blockstudio/acme-ui/button--><a class="acme-button wp-block-acme-ui-button" href="/start">Get started</a>

</div>
</section>

Como o nome de uma tag se torna o nome de um bloco

O nome de uma tag <bs:> não tem barra, então Blockstudio procura uma. Ele substitui cada hífen por uma barra, um de cada vez, da esquerda para a direita, e usa o primeiro candidato registrado. <bs:acme-card> é resolvido como acme/card na primeira tentativa. <bs:acme-ui-button> tenta acme/ui-button, não encontra nada e depois é resolvido como acme-ui/button. Portanto, namespaces com hífens funcionam sem configuração, desde que os dois candidatos não existam ao mesmo tempo.

Nomes mais curtos com prefixos

<bs:acme-ui-button> é preciso, mas longo. Um prefixo de projeto associa um prefixo curto de tag a um ou mais namespaces. Configure-o em blockstudio.json:

JSON
{
  "$schema": "https://blockstudio.dev/schema/blockstudio",
  "blockTags": {
    "prefixes": {
      "acme": ["acme"],
      "ui": ["acme-ui"]
    }
  }
}

Ou registre o mesmo mapa de PHP:

PHP
add_filter( 'blockstudio/block_tags/prefixes', function ( $prefixes ) {
	$prefixes['acme'] = array( 'acme' );
	$prefixes['ui']   = array( 'acme-ui' );

	return $prefixes;
} );

Agora <acme-card> é resolvido como acme/card, e <ui-button> como acme-ui/button. Quando um prefixo lista vários namespaces, eles são testados em ordem, e vence o primeiro bloco registrado. Isso permite que um bloco do projeto prevaleça sobre um bloco de biblioteca com o mesmo slug.

Prefixos também podem ser compostos. <acme-ui-button> tenta primeiro acme/ui-button. Esse bloco não existe, e o restante da tag, ui-button, também é uma tag de prefixo registrada, então a resolução continua até acme-ui/button. Uma correspondência direta sempre prevalece sobre a aninhada.

HTML
<bs:acme-section heading="Why Acme">
  <acme-card title="Fast" text="Rendered on the server." />
  <acme-ui-button label="Get started" href="/start" />
</bs:acme-section>

Isso renderiza exatamente o mesmo HTML que a versão canônica acima.

Há algumas regras para os prefixos:

  • Um prefixo contém letras minúsculas e números, começa com uma letra e não contém hífens.
  • Uma tag com prefixo que não seja resolvida para nenhum bloco registrado permanece intacta na saída, então <acme-missing title="x" /> fica como foi escrita.
  • Aliases exatos do filtro blockstudio/block_tags/tag_aliases têm precedência sobre os prefixos. Um alias associa uma tag com hífen a um bloco. Por exemplo, $aliases['acme-cta'] = 'acme-ui/button'; faz <acme-cta> renderizar o botão.

Tags com prefixos e aliases são renderizadas em templates de bloco junto com as tags <bs:> e <block> do Blockstudio 7.5.

Atributos

Atributos que correspondem a um ID de campo se tornam valores de campo. Dois prefixos fazem outra coisa:

  • Atributos data-* são copiados para o elemento raiz do bloco renderizado.
  • Atributos html-* são copiados para o elemento raiz sem o prefixo, então html-id="intro" se torna id="intro".
HTML
<bs:acme-card title="Hi" text="There" data-track="card" html-id="intro" html-class="featured" />
HTML
<article data-track="card" id="intro" class="featured">
  <h3>Hi</h3>
  <p>There</p>
</article>

html-class define o atributo, não acrescenta conteúdo a ele: as classes acme-card wp-block-acme-card próprias do bloco desaparecem. Se quem chama o bloco deve adicionar classes a ele, declare um campo para elas e combine-o no template.

Qualquer outro atributo que não seja um campo declarado é descartado. Um class="wide" simples em <bs:acme-card> renderiza o cartão sem esse atributo. Blockstudio 7.7 informa esses atributos com um aviso _doing_it_wrong() quando WP_DEBUG está ativado.

As mesmas tags em fontes de página

Em páginas baseadas em arquivos, padrões e Site Templates, as tags não são renderizadas. Elas são convertidas em blocos durante a análise da fonte, para que apareçam no editor. Esta fonte de página:

HTML
<bs:acme-section heading="Why Acme">
  <p>Everything below is a real block.</p>
  <acme-card title="Fast" text="Rendered on the server." />
  <acme-ui-button label="Get started" href="/start" />
</bs:acme-section>

é convertida nesta marcação de blocos (com quebras de linha adicionadas para facilitar a leitura):

HTML
<!-- wp:acme/section {"blockstudio":{"attributes":{"heading":"Why Acme"}}} -->
<!-- wp:paragraph --><p>Everything below is a real block.</p><!-- /wp:paragraph -->
<!-- wp:acme/card {"blockstudio":{"attributes":{"title":"Fast","text":"Rendered on the server."}}} /-->
<!-- wp:acme-ui/button {"blockstudio":{"attributes":{"label":"Get started","href":"/start"}}} /-->
<!-- /wp:acme/section -->

Os valores dos campos ficam em blockstudio.attributes, onde os blocos Blockstudio os armazenam, e o parágrafo e os dois blocos internos se tornam blocos internos da seção. Os prefixos e aliases são resolvidos aqui exatamente como nos templates.

Tags no conteúdo das publicações

Por padrão, o conteúdo escrito no editor ou armazenado em widgets não é analisado. Ative a renderização por página em blockstudio.json:

JSON
{
  "blockTags": {
    "enabled": true
  }
}

As tags em the_content e widget_text são então renderizadas na prioridade 5. A mesma opção registra um filtro para renderizar tags em qualquer texto:

PHP
$html = apply_filters( 'blockstudio/block_tags/render', $content );

Restrinja as tags que podem ser renderizadas com os padrões allow e deny, que aceitam curingas fnmatch() e se aplicam a todas as sintaxes e aos dois modos de renderização:

JSON
{
  "blockTags": {
    "enabled": true,
    "deny": ["acme-ui/*"]
  }
}

Com essa regra em vigor, <acme-ui-button> e <bs:acme-ui-button> permanecem sem renderização na saída. deny tem precedência sobre allow. Os filtros blockstudio/block_tags/allow e blockstudio/block_tags/deny alteram as mesmas listas a partir de PHP.

A análise verifica a grafia canônica

A extensão PHPStan valida tags de bloco em PHP, Twig e modelos Blade. Um nome de campo ou de bloco com erro de digitação é informado junto com o bloco ao qual foi resolvido:

Text
  3      Block tag "acme/card" has unknown attribute "txt" in index.php
         🪪  blockstudio.blockTag.attribute
  4      Block tag references unknown block "acme/cards" in index.php
         🪪  blockstudio.blockTag.unknown

Na versão 7.6, isso abrange tags <bs:> e <block>. Uma tag com prefixo, como <acme-card txt="...">, passa sem ser verificada. Blockstudio 7.7 amplia a regra para tags com prefixo, fontes de página e elementos HTML mapeados, e a dica lista os atributos globais que uma tag pode encaminhar.

Migrar abreviações para a grafia canônica

Tags com prefixos e aliases são conveniências do projeto. Elas só são resolvidas onde os filtros e configurações do projeto são carregados, então um template copiado para outro projeto, uma biblioteca de blocos ou o contexto de um agente de programação perde o significado. <bs:namespace-slug> registra o nome real do bloco e é resolvido em qualquer lugar, por isso os próprios exemplos, diagnósticos e resultados gerados de Blockstudio usam essa forma.

Um comando independente reescreve as abreviações nessa grafia. Considere um projeto cujas fontes ainda usam as formas curtas, incluindo um alias, uma tag de um bloco que já não existe e um exemplo dentro de um trecho de código:

PHP
<div useBlockProps class="acme-features">
  <acme-card title="Fast" text="Rendered on the server." />
  <acme-ui-button label="Get started" href="/start" />
</div>
PHP
<acme-section heading="Why Acme">
  <acme-cta label="Talk to us" href="/contact" />
  <acme-quote text="Missing block" />
</acme-section>
<pre><code>&lt;acme-card /&gt; <acme-card title="Example" /></code></pre>

O comando não carrega WordPress, então recebe a configuração do projeto como arquivos JSON mantidos fora da árvore analisada:

JSON
{ "acme": ["acme"], "ui": ["acme-ui"] }
JSON
["acme/card", "acme/section", "acme/features", "acme-ui/button"]
JSON
{ "acme-cta": "acme-ui/button" }

Comece com uma simulação, que também é o padrão:

Shell
php vendor/blockstudio/blockstudio/bin/migrate-block-tags.php \
  --root="$PWD" \
  --prefix-map=/tmp/acme-tags/prefixes.json \
  --known-blocks=/tmp/acme-tags/blocks.json \
  --aliases=/tmp/acme-tags/aliases.json \
  --report=/tmp/acme-tags/report.json \
  --dry-run
Text
Report: /tmp/acme-tags/report.json
Dry run: 2 files, 2 changed, 5 replacements, 1 unknown, 0 ambiguous, 1 manual.

O relatório lista cada mapeamento que seria aplicado e cada caso que não será adivinhado:

JSON
{
  "mappings": [
    { "legacy": "acme-card", "canonical": "bs:acme-card", "block": "acme/card", "occurrences": 1 },
    { "legacy": "acme-cta", "canonical": "bs:acme-ui-button", "block": "acme-ui/button", "occurrences": 1 },
    { "legacy": "acme-section", "canonical": "bs:acme-section", "block": "acme/section", "occurrences": 2 },
    { "legacy": "acme-ui-button", "canonical": "bs:acme-ui-button", "block": "acme-ui/button", "occurrences": 1 }
  ],
  "unknown": [
    { "path": "pages/home/index.php", "line": 3, "column": 4, "tag": "acme-quote", "reason": "no-known-block" }
  ],
  "manual": [
    { "path": "pages/home/index.php", "line": 5, "column": 33, "tag": "acme-card", "reason": "code-sample" }
  ]
}

O relatório está resumido aqui. Ele também registra hashes da configuração e de cada arquivo antes e depois. As tags de abertura e fechamento da seção contam como duas ocorrências. acme-quote corresponde ao prefixo acme, mas não nomeia nenhum bloco conhecido, portanto é desconhecido. acme-card dentro de <pre><code> é um exemplo, não uma marcação, então é sinalizado para revisão manual e nunca é reescrito; o mesmo se aplica a comentários HTML e ao código em linha.

A aplicação é recusada enquanto houver tags desconhecidas, ambíguas ou dinâmicas:

Text
Error: Unresolved tags remain; no files were written. Review a dry-run report or pass --allow-unresolved.

O comando termina com o código 2. Corrija a tag desconhecida, removendo-a neste caso, e execute com --apply em vez de --dry-run:

Text
Applied: 2 files, 2 changed, 5 replacements, 0 unknown, 0 ambiguous, 1 manual.

Somente os nomes das tags mudam. Os atributos são preservados byte por byte:

HTML
<bs:acme-section heading="Why Acme">
  <bs:acme-ui-button label="Talk to us" href="/contact" />
</bs:acme-section>

Executar novamente a simulação sobre o resultado informa 0 changed, 0 replacements. Os prefixos podem continuar registrados depois disso, para que nada deixe de funcionar enquanto outros branches ainda usam a forma curta.

Próximas etapas