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
storageadiciona locais de armazenamento adicionais; ela não substitui o armazenamento do bloco.
Configuração
Adicione a propriedade storage a qualquer definição de campo:
{
"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
// Add post meta storage
"storage": {
"type": "postMeta"
}
// Add both post meta and option storage
"storage": {
"type": ["postMeta", "option"]
}
Como funciona
- Registro: quando WordPress é carregado, Blockstudio registra chaves de metadados e configurações com base nas configurações dos seus campos
- Edição: os valores são gerenciados como atributos de bloco no editor (sempre armazenados no bloco)
- 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
<div>
<h1><?php echo $a['subtitle']; ?></h1>
</div>
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
// 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
{# 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:
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
$company_name = get_option( 'site_company_name' );
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:
{
"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"
}
}
]
}
}
Conteúdo em destaque com consulta
Adicione o armazenamento de metadados do post para permitir consultar posts pelo valor do campo:
{
"blockstudio": {
"attributes": [
{
"id": "featured",
"type": "toggle",
"label": "Featured",
"storage": {
"type": "postMeta",
"postMetaKey": "is_featured"
}
}
]
}
}
Consultar posts em destaque:
$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:
{
"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:
<footer>
<p>© <?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:
{
"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.