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:
<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:
{
"$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": "" }
]
}
}
<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:
<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:
<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:
<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:
<!--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:
<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>
<!--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:
{
"$schema": "https://blockstudio.dev/schema/blockstudio",
"blockTags": {
"prefixes": {
"acme": ["acme"],
"ui": ["acme-ui"]
}
}
}
Ou registre o mesmo mapa de 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.
<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_aliasestê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ãohtml-id="intro"se tornaid="intro".
<bs:acme-card title="Hi" text="There" data-track="card" html-id="intro" html-class="featured" />
<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:
<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):
<!-- 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:
{
"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:
$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:
{
"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
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:
<div useBlockProps class="acme-features">
<acme-card title="Fast" text="Rendered on the server." />
<acme-ui-button label="Get started" href="/start" />
</div>
<acme-section heading="Why Acme">
<acme-cta label="Talk to us" href="/contact" />
<acme-quote text="Missing block" />
</acme-section>
<pre><code><acme-card /> <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:
{ "acme": ["acme"], "ui": ["acme-ui"] }
["acme/card", "acme/section", "acme/features", "acme-ui/button"]
{ "acme-cta": "acme-ui/button" }
Comece com uma simulação, que também é o padrão:
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
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:
{
"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:
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:
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:
<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
- Renderização: a sintaxe completa das tags, renderizadores personalizados e o analisador.
- Configurações: todas as opções de
blockTags. - Criação de páginas baseadas em arquivos: fontes de página nas quais as tags se tornam blocos editáveis.
- Migração de tags de bloco: todas as opções do comando de migração.
- Templates verificados com PHPStan: execução da análise que valida as tags.