Pular para o conteúdo

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

PHP
<h1><?php echo $attributes['message']; ?></h1>
<h1><?php echo $a['message']; ?></h1>

Twig

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:

PHP
// 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():

PHP
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 min tem suas linhas iniciais.
  • Os valores do nível superior e blockstudio.attributes sã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 returnFormat de label fornece 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
<?php if ($a['message']) : ?>
  <h1><?php echo $a['message']; ?></h1>
<?php endif; ?>

Twig

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
<?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

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.

O campo de link retorna um objeto com URL e atributos:

PHP

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

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
<?php if ($a['icon']) : ?>
  <div class="icon">
    <?php bs_render_icon($a['icon']); ?>
  </div>
<?php endif; ?>

Twig

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

PHP
<div <?php bs_render_data_attributes($a['attributes']); ?>>
  Content
</div>

Twig

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
<?php $group = bs_get_group($a, 'settings'); ?>
<h1><?php echo $group['title']; ?></h1>
<p><?php echo $group['description']; ?></p>

Twig

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:

JSON
{
  "name": "section-header",
  "attributes": [
    {
      "id": "section-header",
      "type": "group",
      "attributes": [
        { "id": "kicker", "type": "text" },
        { "id": "title", "type": "text" }
      ]
    }
  ]
}
JSON
{
  "blockstudio": {
    "attributes": [
      { "type": "custom/section-header" }
    ]
  }
}
Twig
{% 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
<?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

Twig
{% for item in a.items %}
  <div class="item">
    <h3>{{ item.title }}</h3>
    <p>{{ item.description }}</p>
  </div>
{% endfor %}

Receitas de padrões de campos