Pular para o conteúdo

Renderização programática

Com Gutenberg se tornando a principal ferramenta para criar sites facilmente editáveis para clientes, faz sentido criar todas as áreas necessárias do site como blocos. Embora essa abordagem atenda à maioria dos casos, usuários avançados e casos de uso específicos talvez precisem usar esses blocos existentes fora do editor.

Blockstudio oferece duas abordagens para renderizar blocos programaticamente:

  • Funções PHP: bs_render_block e bs_block para renderizar a partir de código PHP
  • Tags HTML: tags <bs:block-name> que são substituídas pela saída do bloco em qualquer lugar da página

Todos os recursos específicos de Blockstudio, como estilos em linha, scripts e estilos com escopo, são compatíveis.

Ilhas também funcionam nesses caminhos de renderização. Uma ilha dinâmica renderizada com bs_render_block(), bs_block() ou uma tag de bloco retorna o mesmo marcador de placeholder que um bloco renderizado a partir do conteúdo do post, e o runtime do frontend é injetado quando esse marcador está presente na resposta.

Composições estruturadas e documentos completos

Para ferramentas, pré-visualizações, exportações e galerias de componentes duradouras, use a Blockstudio\Render API versionada. Ela aceita uma declaração ou uma lista ordenada e renderiza sem imprimir:

PHP
use Blockstudio\Render;

$composition = [
  'root' => 'theme/card',
  'example' => [
    'data' => [
      'heading' => 'Example card',
    ],
    'layers' => [
      [
        'name' => 'theme/button',
        'data' => [
          'label' => 'Continue',
        ],
      ],
    ],
  ],
];

$normalized = Render::normalize($composition);
$html = Render::composition($composition);
$document = Render::document($composition, [
  'title' => 'Component preview',
  'contentElement' => 'main',
  'contentClasses' => ['component-preview'],
]);

A declaração normalizada canônica tem quatro chaves:

PHP
[
  'name' => 'theme/card',
  'attributes' => [],
  'content' => '',
  'children' => [],
]

data, inner, innerBlocks, root, layers e example são conveniências de entrada e são removidas durante a normalização. Declarações aninhadas são renderizadas recursivamente pelo mesmo pipeline Blockstudio.

Render::document() retorna schemaVersion, html, body, blocks, assets, warnings e errors. O valor assets separa head, footer, styles, scripts, modules, interactivity, ui e tailwind. A lista de blocos e os recursos incluem dependências referenciadas pelos modelos selecionados, mas excluem recursos não relacionados e exclusivos do editor.

Documentos completos podem definir bodyClasses/bodyAttributes e, opcionalmente, envolver o corpo renderizado com contentElement, contentClasses e contentAttributes. O wrapper é restrito a um nome de elemento seguro; o valor body retornado continua sendo o conteúdo renderizado sem wrapper. As opções head e footer acrescentam marcação confiável do documento nas respectivas posições e são incluídas no conjunto de recursos retornado.

Para montar um documento em torno de HTML que já foi renderizado, forneça os nomes conhecidos dos blocos raiz:

PHP
$document = Render::document_from_html(
  $rendered_html,
  ['theme/hero', 'theme/button'],
  ['title' => 'Homepage preview']
);

Use Render::content() para conteúdo de bloco serializado de WordPress. Consumidores que renderizam vários documentos independentes em uma única solicitação devem chamar Blockstudio\Batch_Render::reset() entre eles; Canvas::documents() faz isso automaticamente.

Renderização fora da página

Blockstudio insere um comentário <!--blockstudio/namespace/slug--> antes de cada bloco que renderiza. Em uma página do frontend, o buffer lê esses comentários para identificar os blocos presentes, carregar os recursos deles e remover os comentários antes de enviar a resposta.

A saída que não passa por esse buffer mantém os comentários. Isso se aplica a respostas REST, feeds, manipuladores AJAX e HTML que você armazena ou envia para outro lugar após do_blocks(), Render::content() ou bs_render_block(). Use bs_strip_render_markers() para removê-los:

PHP
$html = bs_strip_render_markers(do_blocks($post->post_content));

A função remove os comentários dos blocos Blockstudio registrados e deixa todo o restante intacto, inclusive outros comentários HTML. Ela corresponde aos mesmos marcadores removidos pelo buffer da página. Chame-a após o registro dos blocos (init ou depois).

Não remova a marcação que ainda será impressa em uma página do frontend processada pelo buffer. A página precisa dos comentários para saber quais recursos dos blocos carregar, e Blockstudio os remove no final.

Remover os comentários não adiciona recursos. Os arquivos de CSS bloco e JavaScript só são inseridos pelo buffer da página. Use bs_block_assets() ou Render::document() quando o consumidor também precisar deles.

Inspeção de blocos

Use bs_block_fields() após o registro dos blocos (em init ou depois) para obter as definições resolvidas dos campos sem ler registros internos:

PHP
$fields = bs_block_fields('theme/card');

if ($fields === null) {
  // Unknown block, or not a Blockstudio block.
}

O valor de retorno é o array registrado de definições de campos, incluindo filtros de atributos, campos personalizados expandidos, substituições e grupos, abas e repetidores aninhados. Um bloco Blockstudio sem campos retorna []. O resultado é uma cópia: alterá-la não modifica o bloco registrado.

Estas são definições, não valores salvos. Para validar a marcação salva, use bs_validate_block() em vez de manter um percorrimento separado dos campos. Para descrever os valores que um bloco aceita, use bs_block_schema(). Os atributos pertencentes a WordPress permanecem separados.

Os campos adicionados por extensões não fazem parte de bs_block_fields(). Use bs_block_extension_fields() para obtê-los. A função identifica extensões pelo nome do bloco, portanto também funciona com blocos do núcleo e de terceiros:

PHP
$fields = array_merge(
  bs_block_fields('core/paragraph') ?? [],
  bs_block_extension_fields('core/paragraph')
);

O valor de retorno lista as definições de campos de cada extensão correspondente, na ordem em que foram registradas, com a mesma estrutura de bs_block_fields(). Para um bloco sem extensões correspondentes, o retorno é []. Os valores das extensões são salvos no mesmo objeto attrs.blockstudio.attributes que os valores dos campos do próprio bloco, portanto todos os IDs compartilham um único espaço de nomes. Se duas extensões definirem o mesmo ID, ambas as definições serão retornadas e editarão o mesmo valor; na renderização, aplica-se a definição da extensão registrada por último.

Para ler os valores de um bloco salvo tal como são recebidos pelo modelo, use bs_block_values().

Use bs_block_assets() para inspecionar o CSS e o JavaScript descobertos do bloco. Para obter um documento completo de prévia, incluindo blocos aninhados e dependências compartilhadas do ambiente de execução, use Render::document(), conforme descrito acima.

Validando valores armazenados

Use bs_validate_block() após o registro dos blocos (init ou depois) para verificar atributos de blocos gerados programaticamente ou importados antes de salvá-los:

PHP
$block = parse_blocks($content)[0];
$findings = bs_validate_block($block['blockName'], $block['attrs']);

if ($findings === null) {
  // No Blockstudio fields or matching extensions apply.
} elseif ($findings === []) {
  // No stored-value problems were found.
} else {
  // Review the findings before saving.
}

Passe o array attrs completo, não apenas blockstudio.attributes. Uma renderização Blockstudio também aceita campos declarados no nível superior, e os valores aninhados prevalecem quando ambos são fornecidos. Extensões de blocos do núcleo e de terceiros leem apenas blockstudio.attributes. Um bloco Blockstudio vazio é gerenciado e retorna [], não null.

A validação é explícita e somente para leitura. Ela não renderiza modelos, altera valores, salva posts, consulta mídia nem executa callbacks de preenchimento. Não é executada automaticamente durante o salvamento, a sincronização de páginas ou a renderização. Não é um sanitizador, uma verificação de autorização nem uma confirmação da existência de um anexo.

Cada resultado contém estas chaves estáveis:

PHP
[
  'code' => 'unknown_option',
  'path' => 'steps/1/style',
  'source' => 'block',
  'message' => 'This value is not among the field options.',
  'value' => 'c',
  'expected' => ['a', 'b'],
]

Use code, não o message traduzido, nas ferramentas. source é block ou extension. Os caminhos usam chaves de armazenamento e índices de linha de repetidor ou de seleção baseados em zero, sem barra inicial. Os caracteres literais ~ e / em uma chave são escapados como ~0 e ~1. Um grupo de nível superior prefixa seus filhos (cta_title); grupos anônimos e abas não acrescentam níveis. O builder não oferece suporte a grupos com um ID dentro de outro grupo ou de um repetidor, portanto suas chaves não são aceitas. Campos de mensagem não têm valor armazenado. Um campo de arquivos permite seu complemento <id>__size. Na raiz de um bloco Blockstudio, as chaves de controle e os atributos globais de HTML encaminhados ao elemento renderizado não são campos desconhecidos. Isso não permite chaves arbitrárias em linhas de repetidor nem extensões de blocos do núcleo.

Código Significado expected
unknown_field Nenhum campo mantido declara esta chave de armazenamento. Chaves de armazenamento conhecidas.
unknown_option Uma seleção não está entre as opções conhecidas. Valores de opção permitidos.
wrong_type A estrutura armazenada não é compatível com o campo. Família ou tipo de armazenamento esperado.
too_few_rows, too_many_rows Um repetidor presente está fora do limite de min ou max. O limite de linhas.
definition_conflict As definições aplicáveis a uma chave exigem estruturas de armazenamento diferentes. Origem e tipo de campo de cada definição.
shadowed_value Um valor aninhado substitui um valor diferente de campo de nível superior. O valor aninhado que prevalece.
extension_top_level O modelo pode ler um valor de nível superior, mas as vinculações de extensão não. O caminho necessário em blockstudio/attributes.
unknown_attribute Uma chave de nível superior de um bloco Blockstudio não é lida pelo caminho de renderização e é descartada. Nomes de atributos registrados, campos de extensão e blockstudio.
missing_container attributes, disabled, name ou editor está armazenado no nível superior, e falta blockstudio. O caminho necessário em blockstudio.
invalid_container blockstudio ou blockstudio.attributes não é um objeto. object.

A mensagem de uma ocorrência de unknown_field indica a chave de armazenamento mais próxima no mesmo nível quando ela está a até três edições de distância, conforme a regra para configurações desconhecidas: This storage key is not declared by the block or its extensions. Did you mean "title"?. expected ainda lista todas as chaves conhecidas. A correspondência ignora maiúsculas e minúsculas e considera apenas as chaves de armazenamento desse contêiner. As mensagens são traduzidas; as integrações devem usar code, path e expected em vez de analisar o texto da mensagem.

Uma chave de nível superior de um bloco Blockstudio que não seja um atributo registrado (seus campos, os atributos que WordPress adiciona para supports, lock e metadata), um campo de uma extensão correspondente, blockstudio, uma chave de controle ou um atributo global de HTML encaminhado é descartada antes da execução do modelo. Uma chave desse tipo, como um ID de campo digitado incorretamente ou um objeto de valores armazenado sem seu invólucro blockstudio, gera um apontamento porque o bloco é renderizado sem esse valor. Blocos que contêm apenas campos de extensão não são verificados quanto a chaves de nível superior.

As estruturas aceitas correspondem à renderização: seleções múltiplas e caixas de seleção podem conter uma lista, um objeto de opção ou um escalar importado, inclusive zero numérico. Strings numéricas são aceitas para números. Arquivos podem conter IDs de anexos, objetos de ID, listas ou referências de string. Valores de link e ícone precisam ser objetos; tipos de campo personalizados usam o tipo de atributo registrado. Um campo attributes contém uma lista de pares com um nome attribute não vazio e um escalar value; metadados opcionais, como data.media, são preservados.

WordPress valida atributos registrados de nível superior antes da renderização, o que pode rejeitar uma estrutura aceita dentro de blockstudio.attributes. Por exemplo, um valor de radio "a" funciona no objeto aninhado, mas é descartado no nível superior, onde seu tipo registrado é object. Esse valor gera wrong_type. Use o objeto aninhado para manter a mesma estrutura de armazenamento gravada pelo editor.

Campos ausentes não são obrigatórios. Valores aninhados vazios (null, false, '', []) e campos desativados não geram erros de valor. Um repetidor explicitamente vazio ainda é verificado em relação a min; um repetidor ausente ou desativado não é. Um valor vazio de nível superior é reportado se WordPress o descartar e restaurar um valor padrão não vazio. O mesmo valor no objeto aninhado pode limpá-lo. Conflitos entre definições são reportados mesmo quando a chave não tem valor salvo.

Opções estáticas e opções de preenchimento resolvidas no registro são verificadas sem chamar o preenchimento novamente. Opções remotas de fetch e argumentos de preenchimento que contêm {attributes.*} são ignorados. Valores de cor e gradiente podem ser personalizados, a menos que disableCustomColors ou disableCustomGradients esteja definido. Isso verifica valores armazenados, não default, fallback nem regras de validação do editor.

Os campos de extensão correspondentes são incluídos em cada bloco ao qual se aplicam. No nível raiz, as definições posteriores prevalecem no bloco ou em suas extensões, como na renderização. Um campo do próprio bloco e um campo de extensão continuam sendo definições separadas da mesma chave, e ambas se aplicam. Nas linhas do repetidor, o renderizador lê o primeiro campo com um ID correspondente em cada origem, portanto suas opções e limites se aplicam. Definições duplicadas são mantidas para diagnósticos de conflito: estruturas de armazenamento incompatíveis geram definition_conflict, mesmo quando uma duplicata posterior não é lida na renderização.

A função verifica um bloco. Percorra innerBlocks ao validar um documento; partes sincronizadas e outras referências não são expandidas automaticamente. O comando wp bs blocks validate percorre os blocos de uma ou mais publicações e informa seus caminhos de bloco.

Sites com um resolvedor personalizado em tempo de renderização podem adaptar os apontamentos sem alterar os dados armazenados:

PHP
add_filter('blockstudio/blocks/attributes/validate', function($findings, $name, $attrs) {
  if ($name !== 'my-theme/card') {
    return $findings;
  }

  return array_values(array_filter($findings, function($finding) {
    return !($finding['path'] === 'customReference' && $finding['code'] === 'wrong_type');
  }));
}, 10, 3);

Sempre retorne uma lista de apontamentos; retornar [] aceita o bloco. Esse filtro é executado apenas para blocos gerenciados, nunca para o resultado de null.

Descrição dos valores armazenados

Use bs_block_schema() após o registro do bloco (init ou posterior) para descrever os valores que um bloco armazena, por exemplo, para gerar marcação de bloco em uma ferramenta ou integração de IA, ou para verificar a entrada em uma rota REST:

PHP
$schema = bs_block_schema('theme/card');

if ($schema === null) {
  // No Blockstudio fields or matching extensions apply.
}

O resultado é um Schema JSON do objeto salvo em attrs.blockstudio.attributes. Ele abrange os campos do bloco e os campos das extensões correspondentes, com as chaves de armazenamento usadas pela validação: um grupo de nível superior acrescenta um prefixo aos filhos; grupos anônimos e abas não adicionam níveis; e um campo de arquivos adiciona seu complemento <id>__size. Repetidores são listas de objetos de linha com minItems e maxItems provenientes de min e max. additionalProperties é false na raiz do armazenamento dos campos e nas linhas dos repetidores. Campos com valores de objeto, como links e objetos personalizados, podem ter seus próprios metadados. Um bloco sem campos não tem properties, portanto apenas um objeto vazio corresponde.

Cada campo é descrito em um formato canônico aceito por bs_validate_block():

Campo Schema
text, textarea, richtext, wysiwyg, code, date, datetime, unit, classes, html-tag, block Uma string.
number, range Um número, com minimum e maximum provenientes de min e max.
toggle Um booleano.
select, radio, checkbox Um valor de opção ou uma lista de valores de opção para checkbox e multiple, com enum.
color, gradient Uma string, com enum quando disableCustomColors ou disableCustomGradients está definido.
token Uma lista de strings.
files Um ID de anexo inteiro não negativo ou uma lista de IDs com multiple.
link Um objeto com url, title e opensInNewTab; url é obrigatório.
icon Um objeto com set, subSet e icon; set e icon são obrigatórios.
attributes Uma lista de objetos com attribute não vazio e um value escalar.
repeater Uma lista de objetos de linha.
Tipos de campo personalizados O tipo de atributo registrado.

enum lista as opções verificadas pela validação: opções estáticas e opções de preenchimento já resolvidas no registro. Opções fetch remotas e argumentos de preenchimento que contêm {attributes.*} não têm enum. Uma chave com definições de formatos de armazenamento diferentes é omitida, pois a validação informa todos os valores armazenados nela. Quando um campo de bloco e um campo de extensão compartilham uma chave, enum lista os valores aceitos por ambos. Repetidores compartilhados combinam seus campos filhos e aplicam os limites de linha mais restritos das duas definições. Nas linhas dos repetidores, aplica-se o primeiro campo com um ID correspondente em cada origem, como na renderização. Um campo explícito chamado <id>__size tem precedência sobre um complemento de tamanho de arquivo adicionado automaticamente.

Quando um campo fechado não tem opções disponíveis, ou dois conjuntos de opções aplicáveis não têm nenhuma opção em comum, seu valor canônico é null para uma seleção única ou uma lista vazia para seleções múltiplas. Uma lista de opções vazia não transforma o campo em irrestrito. As opções remotas e dependentes de atributos permanecem abertas.

O label de um campo se torna title, seu help se torna description, e seu default é mantido como anotação. O title próprio do schema é o título do bloco. Campos nunca são obrigatórios, e a lógica condicional não faz parte do schema.

As restrições usam apenas palavras-chave verificadas por rest_validate_value_from_schema(), então o schema funciona diretamente como schema de entrada de uma rota REST ou de uma habilidade:

PHP
$values = $block['attrs']['blockstudio']['attributes'] ?? [];
$schema = bs_block_schema($block['blockName']);
if ($schema !== null) {
  $result = rest_validate_value_from_schema($values, $schema);
}

O esquema descreve um formulário por campo; a validação também aceita formatos importados, como objetos de opções, strings numéricas e objetos de ID. Ele não substitui bs_validate_block(): conflitos de definição são problemas de configuração e ainda podem gerar ocorrências, mesmo quando a chave conflitante é omitida. Os filtros de validação também podem impor regras específicas do site. Use bs_validate_block() para verificar o conteúdo armazenado. Sites com um resolvedor personalizado no momento da renderização podem adaptar o esquema com o filtro blockstudio/blocks/attributes/schema.

Funções de PHP

Sem dados

Na forma mais simples, a função aceita um único valor, que é o ID do bloco que deve ser renderizado na página.

PHP
bs_render_block('blockstudio/cta');

Com dados

Para renderizar o bloco com dados personalizados, é necessário usar um array no lugar de um único valor no primeiro parâmetro. O valor na chave data será passado para a variável $attributes e $a dentro do modelo do bloco.

PHP
bs_render_block([
  'id' => 'blockstudio/cta',
  'data' => [
    'title' => 'My title',
    'subtitle' => 'My subtitle',
  ],
]);

Aninhamento

É possível aninhar blocos usando a função bs_block em conjunto com a poderosa variável $content dentro dos modelos dos blocos.

PHP
<div>
  <h1><?php echo $a['title']; ?></h1>
  <p><?php echo $a['subtitle']; ?></p>
  <?php echo $content; ?>
</div>
PHP
echo bs_block([
  'id' => 'blockstudio/cta',
  'data' => [
    'title' => 'My title',
    'subtitle' => 'My subtitle',
  ],
  'content' => bs_block([
    'id' => 'blockstudio/button',
    'data' => [
      'text' => 'Button Text',
    ]
  ])
]);

O bloco de botão será renderizado no lugar da variável $content dentro do modelo do bloco.

Blocos incorporados renderizados com bs_render_block() ou bs_block() sempre geram HTML resolvido no frontend, mesmo quando o bloco pai está renderizando uma prévia no editor. Pseudocomponentes de modelo, como <RichText /> e <InnerBlocks />, são resolvidos antes que o bloco incorporado seja retornado.

Vários espaços reservados

Também é possível criar vários espaços reservados de conteúdo simplesmente transformando a variável $content em um array associativo e chamando as chaves correspondentes na função bs_block.

PHP
<div>
  <?php echo $content['beforeContent']; ?>
  <h1><?php echo $a['title']; ?></h1>
  <p><?php echo $a['subtitle']; ?></p>
  <?php echo $content['afterContent']; ?>
</div>
PHP
echo bs_block([
  'id' => 'blockstudio/cta',
  'data' => [
    'title' => 'My title',
    'subtitle' => 'My subtitle',
  ],
  'content' => [
    'beforeContent' => bs_block([
      'id' => 'blockstudio/badge',
      'data' => ['text' => 'Before Content']
    ]),
    'afterContent' => bs_block([
      'id' => 'blockstudio/button',
      'data' => ['text' => 'Button Text']
    ])
  ]
]);

Tags de bloco

Incorpore qualquer bloco usando a sintaxe de tag HTML. Há suporte para dois formatos:

HTML
<bs:acme-hero title="Welcome" />
<block name="acme/hero" title="Welcome" />

Ambos renderizam o mesmo bloco. A sintaxe <bs:> transforma um hífen no separador de namespace (acme-hero se torna acme/hero). Os hífens são testados da esquerda para a direita, e o primeiro candidato registrado é usado; assim, namespaces que contêm hífens também são resolvidos: <bs:acme-ui-button> testa acme/ui-button e depois acme-ui/button. A sintaxe <block> usa o nome completo do bloco como atributo name.

Tanto os blocos Blockstudio quanto os blocos principais do WordPress funcionam. Os blocos Blockstudio são renderizados pelo fluxo completo (modelos, Tailwind, recursos). Os blocos principais são renderizados pelo sistema de renderização de blocos do WordPress, usando os renderizadores de blocos integrados.

Como funciona

As tags de bloco se comportam de maneira diferente dependendo de onde aparecem:

Em modelos de bloco e conteúdo de posts, as tags são substituídas por HTML renderizado durante a execução. A saída é a marcação final do bloco referenciado, incorporada diretamente à página. Não há nenhum bloco WordPress no editor para essas tags. Elas são apenas um mecanismo de renderização.

Em Páginas, padrões e modelos do site, as tags são convertidas em blocos nativos do WordPress antes de o arquivo de origem ser sincronizado ou registrado no WordPress. Isso significa que os blocos aparecem no editor, podem ser editados quando o destino oferece suporte à edição e passam por todo o ciclo de vida de blocos do WordPress. A sintaxe de tag é uma forma abreviada de definir conteúdo de bloco em arquivos de modelo.

Essa distinção é importante: tags de bloco em modelos geram saída; tags de bloco em páginas, padrões e modelos do site geram blocos nativos.

Em modelos de bloco

As tags de bloco são renderizadas automaticamente dentro dos modelos Twig e PHP. Não é necessário configurar nada. Isso inclui as sintaxes <bs:> e <block>, além de qualquer prefixo e tags de alias registrados, para que um modelo possa emiti-los diretamente, sem chamar bs_render_block(). A saída é renderizada HTML e incorporada diretamente à saída do modelo do bloco:

Twig
<div class="my-page">
  <bs:mytheme-card title="Featured" />
  <block name="core/separator" />
  <bs:core-paragraph>Rendered by WordPress</bs:core-paragraph>
  <block name="core/heading" level="2">Also WordPress</block>
  <theme-card title="Prefix shorthand" />
</div>

No conteúdo de posts

A renderização no nível da página (conteúdo de posts, áreas de widgets) é opcional:

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

Ou por meio de um filtro:

PHP
add_filter('blockstudio/settings/block_tags/enabled', '__return_true');

Sintaxe

Tags sem fechamento:

HTML
<bs:mytheme-cta title="Get started" variant="primary" />
<block name="core/separator" />

Tags pareadas com conteúdo interno:

HTML
<bs:mytheme-section layout="wide">
  <p>Content inside the block.</p>
</bs:mytheme-section>

<block name="core/group">
  <block name="core/paragraph">Inside a group.</block>
</block>

Combine à vontade. As duas sintaxes podem ser aninhadas uma dentro da outra:

HTML
<bs:mytheme-section>
  <block name="core/heading" level="2">Title</block>
  <bs:mytheme-card title="Features" />
  <block name="core/paragraph">Description text.</block>
</bs:mytheme-section>

Abreviações de prefixo

As tags de bloco também podem usar abreviações de prefixo específicas do projeto. Registre um prefixo com um ou mais namespaces e Blockstudio resolve <prefix-slug> para o primeiro bloco registrado nessa ordem de namespaces:

PHP
add_filter('blockstudio/block_tags/prefixes', function($prefixes) {
  $prefixes['theme'] = ['theme-components', 'bsui'];

  return $prefixes;
});
HTML
<theme-card title="Homepage" />
<theme-button label="Get started" />
<theme-ui-feature-matrix />

Com o exemplo acima, <theme-card> é resolvido para theme-components/card, <theme-button> recorre a bsui/button quando theme-components/button não está registrado, e <theme-ui-feature-matrix> é resolvido para theme-components/ui-feature-matrix.

Os prefixos também podem ser compostos. Quando uma tag com prefixo não é resolvida diretamente e o slug restante é, por si só, uma tag de prefixo registrada, a resolução é recursiva; assim, um prefixo de marca pode se sobrepor a um prefixo de namespace:

PHP
add_filter('blockstudio/block_tags/prefixes', function($prefixes) {
  $prefixes['theme'] = ['theme-components'];
  $prefixes['ui'] = ['bsui'];

  return $prefixes;
});
HTML
<theme-ui-input />

<theme-ui-input> não tem um bloco theme-components/ui-input, então recorre ao prefixo ui e resolve bsui/input. Correspondências diretas sempre prevalecem sobre a resolução aninhada, e as regras de permissão e bloqueio se aplicam ao bloco resolvido final.

Você também pode configurar prefixos em blockstudio.json:

JSON
{
  "blockTags": {
    "prefixes": {
      "theme": ["theme-components", "bsui"]
    }
  }
}

Os prefixos devem conter letras minúsculas ou números, começar com uma letra e não podem conter hífens. Os aliases explícitos de blockstudio/block_tags/tag_aliases têm prioridade sobre a resolução de prefixos. Tags com prefixos desconhecidos permanecem inalteradas.

As tags de prefixo e alias continuam sendo conveniências de autoria. A forma canônica e portátil é sempre <bs:namespace-slug>, pois registra o nome real do bloco sem depender de filtros do projeto:

HTML
<bs:theme-components-card />
<bs:bsui-input />

Os exemplos de Blockstudio, os diagnósticos gerados e a saída programática usam essa forma canônica. Projetos que queiram remover uma sintaxe abreviada antiga podem usar a migração de tags canônicas autônoma, com simulação antes da execução, sem iniciar o WordPress.

Blocos principais

Qualquer bloco com um renderizador registrado pode ser usado:

HTML
<bs:core-paragraph>A paragraph</bs:core-paragraph>
<bs:core-heading level="2">A heading</bs:core-heading>
<bs:core-separator />
<bs:core-image url="photo.jpg" alt="Photo" />
<bs:core-buttons>
  <bs:core-button url="/about">About</bs:core-button>
</bs:core-buttons>

Ou com a sintaxe <block>:

HTML
<block name="core/group">
  <block name="core/columns">
    <block name="core/column">
      <block name="core/paragraph">Left column</block>
    </block>
    <block name="core/column">
      <block name="core/paragraph">Right column</block>
    </block>
  </block>
</block>

Listas de permissão e bloqueio

Controle quais blocos podem ser renderizados por meio de tags:

JSON
{
  "blockTags": {
    "enabled": true,
    "allow": ["mytheme/*", "core/*"],
    "deny": ["mytheme/internal-*"]
  }
}

allow restringe a correspondência apenas aos padrões correspondentes. deny exclui os padrões correspondentes e tem prioridade. Ambos oferecem suporte a curingas * por meio de fnmatch(). Essas regras se aplicam às duas sintaxes e à renderização no nível do modelo e da página.

Filtros: blockstudio/block_tags/allow e blockstudio/block_tags/deny.

Repasse de HTML

Atributos prefixados com data- são repassados ao elemento raiz do bloco renderizado. Atributos prefixados com html- também são repassados, com o prefixo removido. Funciona com as duas sintaxes. Um atributo repassado substitui o valor existente do elemento raiz em vez de combiná-lo; assim, html-class substitui as classes do próprio bloco.

Um bloco Blockstudio também insere no elemento raiz os atributos globais que não declara como campos: id, style, role, title, lang, dir, hidden, tabindex e todo atributo aria-*. Um campo declarado sempre prevalece; portanto, um bloco com um campo title recebe o valor em $a['title']. Os estilos encaminhados passam por safecss_filter_attr(); o filtro WordPress se aplica aos atributos de estilo no conteúdo de posts, e eles são acrescentados ao estilo já definido pelo modelo.

Os valores dos atributos são HTML; portanto, as entidades são decodificadas uma vez quando uma tag é analisada: title="Tom &amp; Jerry" chega ao modelo como Tom & Jerry e é escapado novamente na saída. Valores entre aspas podem conter >, como nas variantes de Tailwind e nos seletores de animação, tanto em tags sem fechamento quanto em tags pareadas.

Qualquer outro atributo que um bloco não declare, incluindo class, nunca chega ao HTML. Com WP_DEBUG ativado, Blockstudio relata cada um desses atributos uma vez por solicitação por meio de _doing_it_wrong(). Declare um campo para esse atributo ou escreva-o como atributo data-, aria- ou html-.

HTML
<bs:mytheme-card
  title="My Card"
  html-class="featured-card"
  html-id="main-card"
  data-analytics="card-click"
/>

<block name="core/paragraph" html-class="highlight" data-section="intro">
  Highlighted paragraph.
</block>

Renderizadores personalizados

Registre renderizadores de bloco personalizados para tipos de bloco adicionais. Os renderizadores recebem um array de atributos e uma string de conteúdo interno e retornam um array de bloco WordPress:

PHP
add_filter('blockstudio/block_tags/builders', function ($builders, $parser) {
    $builders['myplugin/custom-block'] = function (array $attrs, string $inner_content) {
        $html = '<div class="my-block">' . $inner_content . '</div>';
        return [
            'blockName'    => 'myplugin/custom-block',
            'attrs'        => $attrs,
            'innerBlocks'  => [],
            'innerHTML'    => $html,
            'innerContent' => [$html],
        ];
    };
    return $builders;
}, 10, 2);

Para blocos contêiner que precisam analisar o conteúdo interno em blocos filhos, adicione uma segunda entrada dentro do mesmo filtro:

PHP
$builders['myplugin/wrapper'] = function (array $attrs, string $inner_content) {
    $inner_blocks = Blockstudio\Block_Tags::parse_inner_blocks($inner_content);
    $content = ['<div class="my-wrapper">'];
    foreach ($inner_blocks as $block) {
        $content[] = null;
    }
    $content[] = '</div>';
    return [
        'blockName'    => 'myplugin/wrapper',
        'attrs'        => $attrs,
        'innerBlocks'  => $inner_blocks,
        'innerHTML'    => '<div class="my-wrapper"></div>',
        'innerContent' => $content,
    ];
};

blockstudio/block_tags/builders se aplica tanto às tags de bloco quanto aos blocos personalizados selecionados por meio de blockstudio/parser/element_mapping. Este é o gancho apropriado quando um bloco do projeto com mapeamento de elementos precisa mover o texto interno para um campo Blockstudio ou construir um array de bloco personalizado.

blockstudio/block_tags/renderers e blockstudio/parser/renderers recebem o mesmo registro e formato de callback. Continuam disponíveis por compatibilidade e para substituições finais no nível do analisador. Os filtros são executados nesta ordem:

  1. blockstudio/block_tags/builders
  2. blockstudio/block_tags/renderers
  3. blockstudio/parser/renderers

Um filtro posterior pode substituir um renderizador registrado por um anterior.

Uso programático

Aplique a renderização de tags a qualquer string de PHP:

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

Componentes

As tags de bloco combinam bem com Componentes. Componentes são blocos que só são renderizados programaticamente e nunca aparecem no editor.

HTML
<bs:mytheme-card title="My Card" description="Card content." />

Analisador

As tags de bloco são processadas por um analisador leve de strings que substitui o DOMDocument. O analisador lida com as sintaxes <bs:> e <block>, tags aninhadas com o mesmo nome usando controle de profundidade, valores de atributos entre aspas e blocos contêiner recursivos. Foi desenvolvido especificamente para esse caso de uso, tem desempenho superior ao do DOMDocument e ao do WordPress WP_HTML_Tag_Processor, e evita problemas conhecidos do DOMDocument com a remoção de prefixos de namespace e a conversão de atributos para minúsculas.

Para Páginas, padrões e modelos do site, o mesmo analisador também lida com elementos HTML brutos (<p>, <div>, <h1> etc.), mapeando-os para os blocos principais WordPress correspondentes.

Quando um mapeamento de elemento direciona <p> para um bloco não principal Blockstudio registrado que declara um atributo richtext content, o conteúdo interno HTML é encaminhado automaticamente para esse atributo content, inclusive tags em linha como code e img mapeadas no nível do bloco. Um parágrafo cujo único filho é uma imagem se torna o bloco para o qual <img> aponta. Tags de bloco aninhadas ou HTML em nível de bloco continuam usando a análise normal de blocos internos. <block name="core/shortcode"> mantém o texto do shortcode como conteúdo do bloco.