Pular para o conteúdo

Armazenamento

Por padrão, todos os valores dos campos são armazenados como atributos de bloco dentro do comentário do bloco no conteúdo do post. O recurso de armazenamento também permite armazenar valores em metadados de posts (wp_postmeta) ou opções (wp_options), tornando-os acessíveis fora do contexto do bloco.

Por que usar o armazenamento?

Os atributos de bloco são armazenados em comentários HTML no conteúdo do post, o que significa que só ficam acessíveis ao analisar o conteúdo do bloco. Com locais de armazenamento adicionais, você pode:

  • Consultar posts por valores de campo usando meta_query
  • Acessar valores por meio de REST API em configurações headless
  • Compartilhar dados com outros plugins, como SEO ou plugins de cache
  • Criar configurações globais que persistem entre posts

Tipos de armazenamento

Tipo Local Escopo Ideal para
postMeta tabela wp_postmeta Por post Dados específicos do post que podem ser consultados
option tabela wp_options Global (todo o site) Configurações do site, valores compartilhados

Observação

O armazenamento de atributos de bloco (no comentário HTML do conteúdo do post) ocorre sempre de forma automática. A propriedade storage adiciona locais de armazenamento adicionais; ela não substitui o armazenamento do bloco.

Configuração

Adicione a propriedade storage a qualquer definição de campo:

JSON
{
  "name": "blockstudio/example",
  "title": "Example Block",
  "blockstudio": {
    "attributes": [
      {
        "id": "subtitle",
        "type": "text",
        "label": "Subtitle",
        "storage": {
          "type": "postMeta",
          "postMetaKey": "my_subtitle"
        }
      }
    ]
  }
}

Propriedades de armazenamento

Propriedade Tipo Descrição
type string | string[] location(s) de armazenamento adicional: "postMeta", "option"
postMetaKey string Chave personalizada de metadados (padrão: {block_name}_{field_id})
optionKey string Chave personalizada de opção (padrão: {block_name}_{field_id})

Armazenamento único ou múltiplo

JSON
// Add post meta storage
"storage": {
  "type": "postMeta"
}

// Add both post meta and option storage
"storage": {
  "type": ["postMeta", "option"]
}

Como funciona

  1. Registro: quando WordPress é carregado, Blockstudio registra chaves de metadados e configurações com base nas configurações dos seus campos
  2. Edição: os valores são gerenciados como atributos de bloco no editor (sempre armazenados no bloco)
  3. Salvamento: os metadados do post são sincronizados quando o post é salvo. As opções do site são sincronizadas quando o post é publicado ou quando o valor de um campo de um post publicado muda.

As gravações automáticas e as revisões não sincronizam nenhum dos locais de armazenamento. Posts em rascunho, pendentes, privados ou agendados podem atualizar os próprios metadados, mas não alteram as opções ativas do site. Um post agendado sincroniza as opções quando WordPress o publica.

Os valores são copiados literalmente, incluindo barras invertidas, aspas e valores aninhados de repetidores. Não adicione caracteres de escape aos valores dos campos para compensar o armazenamento de metadados WordPress; Blockstudio trata desse limite. As opções do site mantêm os mesmos valores literais, sem adicionar barras.

Se uma versão anterior removeu barras invertidas da cópia dos metadados de um post, salve o post novamente após a atualização. O valor original do campo nos atributos do bloco é usado para atualizar a cópia dos metadados.

Salvamento de opções do site

As opções são compartilhadas em todo o site. Publicar um novo bloco grava os campos de opção fornecidos em seus atributos salvos. Salvamentos posteriores comparam cada campo com a versão salva anteriormente desse bloco e gravam apenas os valores alterados. Salvar o título de um post ou uma cópia antiga e inalterada do bloco em outro post não substitui um valor de opção mais recente.

Um campo omitido dos atributos salvos deixa sua opção intacta. Isso também protege opções existentes quando um novo campo é adicionado a block.json. Um null explícito exclui uma opção; strings vazias, false, 0 e arrays vazios são salvos como valores. Remover um bloco não exclui suas opções.

Use um bloco publicado designado para gerenciar cada opção compartilhada. Se vários blocos alterarem deliberadamente a mesma opção, prevalecerá o último valor alterado que for salvo. O armazenamento não carrega a opção atual em cada bloco: cada bloco mantém seus próprios valores de campo no conteúdo do post.

Em páginas baseadas em arquivos, uma chave persistente de bloco key permite que Blockstudio reconheça o mesmo bloco depois que ele muda de posição no documento. Blocos sem chave são identificados pelo nome e pela posição.

Acessar valores armazenados

Em templates de bloco

Dentro do template do bloco, os valores dos campos estão sempre disponíveis via $attributes:

PHP

PHP
<div>
  <h1><?php echo $a['subtitle']; ?></h1>
</div>

Twig

Twig
<div>
  <h1>{{ a.subtitle }}</h1>
</div>

Metadados do post (fora do contexto do bloco)

Os valores armazenados em postMeta podem ser acessados em qualquer lugar no WordPress:

PHP

PHP
// Get meta value
$subtitle = get_post_meta( $post_id, 'my_subtitle', true );

// Query posts by meta value
$posts = get_posts([
  'meta_key'   => 'my_subtitle',
  'meta_value' => 'Hello World',
]);

Twig

Twig
{# Using Timber #}
{{ post.meta('my_subtitle') }}

{# Or via function #}
{{ function('get_post_meta', post.id, 'my_subtitle', true) }}

Os metadados do post também estão disponíveis via REST API:

Shell
GET /wp-json/wp/v2/posts/123
# Response includes: { "meta": { "my_subtitle": "Hello World" } }

Opções (valores globais)

Os valores armazenados em option podem ser acessados em todo o site:

PHP

PHP
$company_name = get_option( 'site_company_name' );

Twig

Twig
{{ function('get_option', 'site_company_name') }}

Exemplos

Campos de metadados SEO

Armazene dados SEO nos metadados do post para ter compatibilidade com plugins SEO:

JSON
{
  "blockstudio": {
    "attributes": [
      {
        "id": "seo_title",
        "type": "text",
        "label": "SEO Title",
        "storage": {
          "type": "postMeta",
          "postMetaKey": "_yoast_wpseo_title"
        }
      },
      {
        "id": "seo_description",
        "type": "textarea",
        "label": "Meta Description",
        "storage": {
          "type": "postMeta",
          "postMetaKey": "_yoast_wpseo_metadesc"
        }
      }
    ]
  }
}

Adicione o armazenamento de metadados do post para permitir consultar posts pelo valor do campo:

JSON
{
  "blockstudio": {
    "attributes": [
      {
        "id": "featured",
        "type": "toggle",
        "label": "Featured",
        "storage": {
          "type": "postMeta",
          "postMetaKey": "is_featured"
        }
      }
    ]
  }
}

Consultar posts em destaque:

PHP
$featured_posts = get_posts([
  'meta_key'   => 'is_featured',
  'meta_value' => '1',
]);

Configurações globais do site

Armazene a configuração global do site em opções:

JSON
{
  "blockstudio": {
    "attributes": [
      {
        "id": "company_name",
        "type": "text",
        "label": "Company Name",
        "storage": {
          "type": "option",
          "optionKey": "site_company_name"
        }
      },
      {
        "id": "support_email",
        "type": "text",
        "label": "Support Email",
        "storage": {
          "type": "option",
          "optionKey": "site_support_email"
        }
      }
    ]
  }
}

Acesse em qualquer lugar do site:

PHP
<footer>
  <p>&copy; <?php echo get_option( 'site_company_name' ); ?></p>
  <p>Contact: <?php echo get_option( 'site_support_email' ); ?></p>
</footer>

Metadados e opção do post

Para dados que precisam ser acessíveis tanto no nível do post quanto globalmente:

JSON
{
  "blockstudio": {
    "attributes": [
      {
        "id": "important_value",
        "type": "text",
        "label": "Important Value",
        "storage": {
          "type": ["postMeta", "option"],
          "postMetaKey": "important_meta",
          "optionKey": "important_option"
        }
      }
    ]
  }
}

Nomes de chave padrão

Quando você não especifica uma chave personalizada, Blockstudio gera uma automaticamente:

Tipo de armazenamento Formato de chave padrão Exemplo
postMeta {block_name}_{field_id} blockstudio_example_subtitle
option {block_name}_{field_id} blockstudio_example_subtitle

O nome do bloco é sanitizado (barras substituídas por sublinhados).

Aviso

Recomenda-se usar chaves personalizadas em produção. As chaves padrão podem mudar se você renomear o bloco.