Renderização de atributos
Dentro dos arquivos de modelo, é possível acessar todos os atributos usando as variáveis $attributes ou $a e o ID correspondente do campo.
PHP
<h1><?php echo $attributes['message']; ?></h1>
<h1><?php echo $a['message']; ?></h1>
Twig
<h1>{{ attributes.message }}</h1>
<h1>{{ a.message }}</h1>
Gravação programática de atributos
O editor aninha os valores salvos em blockstudio.attributes. Qualquer ferramenta que grave um bloco fora do editor, como REST API, WP-CLI, uma migração de conteúdo ou um servidor MCP, descobre o bloco pelos atributos que Blockstudio registra em WP_Block_Type e os grava no nível superior. Ambos os formatos são renderizados:
// Top level, as a programmatic writer produces it.
echo do_blocks( '<!-- wp:acme/hero {"visual_type":"media"} /-->' );
// Nested, as the editor saves it.
echo do_blocks( '<!-- wp:acme/hero {"blockstudio":{"attributes":{"visual_type":"media"}}} /-->' );
Somente os IDs declarados pelo bloco são lidos do nível superior, portanto, os próprios atributos de WordPress, como anchor, className, lock, metadata e style, nunca são adotados como valores de campo. Quando o mesmo ID aparece nos dois locais, prevalece o valor aninhado.
Leitura programática de atributos
Código executado fora do modelo, como dados estruturados em save_post, exportações, indexação de pesquisa ou um filtro render_block, muitas vezes precisa dos valores de um bloco salvo tal como aparecem no modelo. bs_block_values() os retorna sem renderizar o bloco. Chame-o após o registro do bloco (init ou posterior) com a matriz completa de attrs de parse_blocks():
foreach (parse_blocks($post->post_content) as $block) {
if ($block['blockName'] === null) {
continue;
}
$a = bs_block_values($block['blockName'], $block['attrs']);
if ($a === null) {
// Not a Blockstudio block, and no extension applies.
continue;
}
echo esc_html($a['title'] ?? '');
}
O resultado é a matriz $a do modelo, indexada pelo ID do campo:
- Os valores padrão dos campos são aplicados, e um repetidor com
mintem suas linhas iniciais. - Os valores do nível superior e
blockstudio.attributessão combinados, e o valor aninhado prevalece. Apenas IDs declarados são lidos do nível superior, e WordPress descarta um valor do nível superior que não corresponda ao tipo registrado do campo, por exemplo uma string de seleção, exatamente como na renderização. - Os campos das extensões correspondentes extensões são incluídos, com seus valores padrão. Uma extensão de um bloco principal ou de terceiros lê apenas
blockstudio.attributes, como na renderização. - Os formatos de retorno são aplicados; assim, uma seleção com
returnFormatdelabelfornece o rótulo, e um campo de arquivos fornece os dados do anexo. - Campos desativados e vazios são
false, como no modelo.
null significa que nem o bloco nem uma extensão são gerenciados por Blockstudio. Um bloco Blockstudio sem campos retorna [].
A função executa a mesma transformação da renderização e, portanto, tem os mesmos efeitos colaterais: campos de arquivos consultam os anexos, um campo de bloco que não retorna data renderiza o bloco referenciado, e o filtro blockstudio/blocks/attributes/render é executado para cada valor. A função não renderiza o próprio modelo do bloco nem resolve innerBlocks; percorra-os você mesmo. Um campo de código mantém um ID %selector% gerado que varia entre chamadas.
A resolução usa o contexto atual de WordPress. Metadados exclusivos da renderização, como contadores de blocos e innerBlocks, não são criados; os filtros de renderização de atributos recebem o nome do bloco, não os metadados de um bloco totalmente renderizado.
Não há opção para obter os valores armazenados sem a transformação. Leia diretamente a matriz attrs para isso ou use bs_validate_block() para verificá-los.
Valores vazios
Os valores de atributos retornam false se o campo estiver vazio ou nenhuma opção tiver sido selecionada.
PHP
<?php if ($a['message']) : ?>
<h1><?php echo $a['message']; ?></h1>
<?php endif; ?>
Twig
{% if a.message %}
<h1>{{ a.message }}</h1>
{% endif %}
Tipos complexos
Arquivos
Por padrão (sem returnFormat ou com "returnFormat": "object"), o campo de arquivos retorna uma matriz com os dados do anexo. Com "multiple": true, retorna uma lista dessas matrizes. Um arquivo cujo anexo não existe mais é false.
| Chave | Descrição |
|---|---|
ID |
O ID do anexo. |
title |
O título do anexo. |
alt |
O texto alternativo. Se estiver vazio, usa o título do anexo. |
caption |
A legenda. |
description |
A descrição. |
href |
O link permanente da página do anexo. |
url |
O URL do arquivo. Com o menu suspenso de tamanho ("size": true), o URL do tamanho selecionado. |
sizes |
O URL e as dimensões de cada tamanho de imagem registrado; veja abaixo. |
PHP
<?php if ($a['image']) :
$image = $a['image'];
$sizes = $image['sizes'] ?? [];
?>
<img
src="<?php echo esc_url($sizes['large'] ?? $image['url']); ?>"
alt="<?php echo esc_attr($image['alt']); ?>"
<?php if (isset($sizes['large-width'], $sizes['large-height'])) : ?>
width="<?php echo esc_attr($sizes['large-width']); ?>"
height="<?php echo esc_attr($sizes['large-height']); ?>"
<?php endif; ?>
/>
<?php endif; ?>
Twig
{% if a.image %}
<img
src="{{ (a.image.sizes.large ?? a.image.url)|e('html_attr') }}"
alt="{{ a.image.alt|e('html_attr') }}"
{% if a.image.sizes['large-width'] is defined and a.image.sizes['large-height'] is defined %}
width="{{ a.image.sizes['large-width']|e('html_attr') }}"
height="{{ a.image.sizes['large-height']|e('html_attr') }}"
{% endif %}
/>
{% endif %}
sizes tem uma entrada por tamanho de imagem registrado, além de full: o URL sob o nome do tamanho e as dimensões sob <size>-width e <size>-height. Se um tamanho WordPress não tiver sido gerado para um anexo, ele resolve para o arquivo original e suas dimensões. Se WordPress não conseguir resolver uma imagem ou pré-visualização, a chave sizes estará ausente. Por exemplo, um PDF sem pré-visualização gerada não tem sizes, mas um PDF com metadados de pré-visualização pode ter tamanhos de imagem. sizes será null quando nenhum tamanho de imagem estiver registrado ou quando o filtro files/sizes os desativar. Esse filtro também pode reduzir o mapa; portanto, verifique se um tamanho existe antes de ler suas dimensões, como nos exemplos acima.
O objeto não tem chaves width, height, mime, type ou size. Leia as dimensões de sizes ou use ID com funções como wp_get_attachment_image() e get_post_mime_type().
Formatos de retorno
returnFormat altera o que o campo retorna:
returnFormat |
Valor |
|---|---|
"object" (padrão) |
A matriz descrita acima. |
"id" |
O ID do anexo tal como armazenado, ou uma lista de IDs com "multiple": true. |
"url" |
O URL como string, ou uma lista de URLs com "multiple": true. As imagens usam o tamanho definido com returnSize (padrão full); outros arquivos usam o URL do arquivo. |
Link
O campo de link retorna um objeto com URL e atributos:
PHP
<?php if ($a['link']) : ?>
<a
href="<?php echo $a['link']['url']; ?>"
target="<?php echo $a['link']['target']; ?>"
>
<?php echo $a['link']['title']; ?>
</a>
<?php endif; ?>
Twig
{% if a.link %}
<a href="{{ a.link.url }}" target="{{ a.link.target }}">
{{ a.link.title }}
</a>
{% endif %}
Ícone
O campo de ícone retorna um objeto com as chaves set, subSet e icon. Use as funções auxiliares bs_render_icon() e bs_icon() para gerar o SVG:
PHP
<?php if ($a['icon']) : ?>
<div class="icon">
<?php bs_render_icon($a['icon']); ?>
</div>
<?php endif; ?>
Twig
{% if a.icon %}
<div class="icon">
{{ bs_icon(a.icon) }}
</div>
{% endif %}
bs_render_icon() exibe o SVG diretamente. bs_icon() o retorna como uma string.
Atributos
O tipo de campo de atributos retorna um array de pares {attribute, value} para renderização como atributos HTML. Use bs_render_data_attributes() para exibi-los:
PHP
<div <?php bs_render_data_attributes($a['attributes']); ?>>
Content
</div>
Twig
<div {{ fn('bs_render_data_attributes', a.attributes) }}>
Content
</div>
bs_render_data_attributes() exibe os atributos diretamente. bs_data_attributes() retorna a string.
Grupo
Os campos de grupo acrescentam o nome do grupo como prefixo aos IDs de seus atributos filhos. Use bs_get_group() para extrair os campos do grupo em um array organizado:
PHP
<?php $group = bs_get_group($a, 'settings'); ?>
<h1><?php echo $group['title']; ?></h1>
<p><?php echo $group['description']; ?></p>
Twig
{% set group = fn('bs_get_group', a, 'settings') %}
<h1>{{ group.title }}</h1>
<p>{{ group.description }}</p>
Isso remove o prefixo do grupo das chaves de atributo. Por exemplo, $a['settings_title'] se torna $group['title'].
A função auxiliar também funciona quando o grupo vem de um campo personalizado reutilizado:
{
"name": "section-header",
"attributes": [
{
"id": "section-header",
"type": "group",
"attributes": [
{ "id": "kicker", "type": "text" },
{ "id": "title", "type": "text" }
]
}
]
}
{
"blockstudio": {
"attributes": [
{ "type": "custom/section-header" }
]
}
}
{% set sectionHeader = fn('bs_get_group', a, 'section-header') %}
<p>{{ sectionHeader.kicker }}</p>
<h2>{{ sectionHeader.title }}</h2>
Repetidor
Percorra os itens do repetidor:
PHP
<?php foreach ($a['items'] as $item) : ?>
<div class="item">
<h3><?php echo $item['title']; ?></h3>
<p><?php echo $item['description']; ?></p>
</div>
<?php endforeach; ?>
Twig
{% for item in a.items %}
<div class="item">
<h3>{{ item.title }}</h3>
<p>{{ item.description }}</p>
</div>
{% endfor %}