Pular para o conteúdo

Migração de ACF Blocks

Se você cria blocos personalizados de WordPress com ACF (Advanced Custom Fields), migrar para Blockstudio é simples. Os conceitos são parecidos: você define campos, escreve um template e o bloco aparece no editor. As diferenças são que Blockstudio detecta as pastas de blocos automaticamente, declara campos no próprio esquema dentro de block.json e fornece a cada template os valores dos campos em um único array $a.

Este guia apresenta a migração passo a passo, com comparações lado a lado dos padrões de ACF e Blockstudio.

A principal diferença

Desde ACF 6.0, um bloco ACF é um block.json com uma chave acf que identifica seu template de renderização, e cada pasta de bloco é registrada com sua própria chamada register_block_type(). Os campos vêm de um grupo de campos associado ao bloco por uma regra de localização de bloco (criado no painel de administração, sincronizado por meio de Local JSON ou registrado com acf_add_local_field_group()) ou, desde ACF PRO 6.8.1, de um array acf.fields em linha no mesmo block.json. Blockstudio substitui a chamada de registro pela descoberta automática baseada em arquivos: crie uma pasta com um block.json e um index.php, e o bloco será registrado automaticamente.

ACF:

JSON
{
  "name": "acf/hero",
  "title": "Hero",
  "acf": {
    "renderTemplate": "template.php"
  }
}
PHP
add_action( 'init', function () {
  register_block_type( __DIR__ . '/blocks/hero' );
} );
PHP
acf_add_local_field_group([
  'key'      => 'group_hero',
  'title'    => 'Hero Fields',
  'fields'   => [
    ['key' => 'field_title', 'name' => 'title', 'type' => 'text', 'label' => 'Title'],
    ['key' => 'field_image', 'name' => 'image', 'type' => 'image', 'label' => 'Background', 'return_format' => 'array'],
  ],
  'location' => [[['param' => 'block', 'operator' => '==', 'value' => 'acf/hero']]],
]);
PHP
<?php
$title = get_field('title');
$image = get_field('image');
?>
<div class="hero" <?php if ($image) : ?>style="background-image: url(<?php echo esc_url($image['url']); ?>)"<?php endif; ?>>
  <h1><?php echo esc_html($title); ?></h1>
</div>

Blockstudio:

JSON
{
  "name": "my-theme/hero",
  "title": "Hero",
  "blockstudio": {
    "attributes": [
      { "id": "title", "type": "text", "label": "Title" },
      { "id": "image", "type": "files", "label": "Background", "multiple": false }
    ]
  }
}
PHP
<div useBlockProps class="hero" <?php if ($a['image']) : ?>style="background-image: url(<?php echo esc_url($a['image']['url']); ?>)"<?php endif; ?>>
  <h1><?php echo esc_html($a['title']); ?></h1>
</div>

Não é preciso chamar um registro nem criar um callback de renderização: a estrutura de pastas faz o registro, e os campos ficam em block.json ao lado do template. O template lê $a em vez de chamar get_field().

Registro de blocos

ACF

Os blocos ACF atuais são registrados a partir de um block.json com uma chave acf (renderTemplate ou renderCallback, além de opções como blockVersion), carregado por uma chamada explícita a register_block_type() para cada pasta de bloco, normalmente em init dentro de functions.php ou em um arquivo de plugin. Blocos mais antigos ainda podem usar acf_register_block_type(), que ACF documenta como obsoleto desde ACF 6.0; ele continua funcionando, então migre esses blocos da mesma forma.

Blockstudio

Crie uma pasta no diretório blockstudio/ do seu tema (ou em blocks/, se preferir). Adicione um block.json com os metadados de bloco padrão WordPress e uma chave blockstudio. Pronto.

Código
theme/
└── blockstudio/
    └── hero/
        ├── block.json
        └── index.php

block.json usa o formato padrão WordPress block.json, com a chave blockstudio para campos e configurações:

JSON
{
  "name": "my-theme/hero",
  "title": "Hero",
  "category": "theme",
  "icon": "cover-image",
  "description": "Full-width hero section with background image.",
  "blockstudio": {
    "attributes": []
  }
}

Acessar valores dos campos

Esta é a mudança mais comum que você fará durante a migração.

ACF Blockstudio
get_field('title') $a['title']
get_field('title', $post_id) $a['title'] (sempre disponível)
the_field('title') <?php echo $a['title']; ?>
have_rows('items') / the_row() foreach ($a['items'] as $item)
get_sub_field('name') $item['name']

A variável $a é um atalho para $attributes e contém todos os valores dos campos do bloco atual. Ela está sempre disponível no template, tanto no editor quanto no frontend.

Variáveis de template

Blockstudio fornece várias variáveis em cada template:

Variável Atalho Descrição
$attributes $a Todos os valores dos campos
$block $b Metadados do bloco (name, title, dir, url, postId)
$context $c Contexto do bloco pai
$content Conteúdo de InnerBlocks
$post_id ID do post atual (funciona no editor e no frontend; post_id ou postId em Twig)

Mapeamento de tipos de campo

A maioria dos tipos de campo ACF tem equivalentes diretos em Blockstudio. A sintaxe JSON é diferente, mas os conceitos correspondem bem.

Campos de texto e conteúdo

ACF:

PHP
['name' => 'title', 'type' => 'text', 'label' => 'Title', 'default_value' => 'Hello']
['name' => 'bio', 'type' => 'textarea', 'label' => 'Bio', 'rows' => 4]
['name' => 'content', 'type' => 'wysiwyg', 'label' => 'Content']

Blockstudio:

JSON
{ "id": "title", "type": "text", "label": "Title", "default": "Hello" }
{ "id": "bio", "type": "textarea", "label": "Bio", "rows": 4 }
{ "id": "content", "type": "wysiwyg", "label": "Content" }

Para texto editável no editor de blocos (não apenas uma entrada de texto), use o tipo richtext com o componente <RichText />:

JSON
{ "id": "heading", "type": "richtext" }
PHP
<RichText attribute="heading" tag="h1" placeholder="Enter heading" />

Campos de imagem e arquivo

Os campos ACF image e file correspondem ao tipo files de Blockstudio:

ACF:

PHP
['name' => 'photo', 'type' => 'image', 'return_format' => 'array']
['name' => 'gallery', 'type' => 'gallery', 'return_format' => 'array']
['name' => 'document', 'type' => 'file', 'return_format' => 'array']

Blockstudio:

JSON
{ "id": "photo", "type": "files", "label": "Photo", "multiple": false }
{ "id": "gallery", "type": "files", "label": "Gallery", "multiple": true }
{ "id": "document", "type": "files", "label": "Document", "multiple": false, "allowedTypes": ["application/pdf"] }

A estrutura do objeto retornado é semelhante:

PHP
// ACF
$image = get_field('photo');
echo $image['url'];
echo $image['alt'];

// Blockstudio
echo $a['photo']['url'];
echo $a['photo']['alt'];

Propriedades disponíveis: ID, title, alt, caption, description, href, url, sizes. As dimensões ficam em sizes, por exemplo $a['photo']['sizes']['full-width'].

Seleção, rádio e caixa de seleção

ACF:

PHP
[
  'name' => 'color',
  'type' => 'select',
  'choices' => ['red' => 'Red', 'blue' => 'Blue'],
  'return_format' => 'value',
]

Blockstudio:

JSON
{
  "id": "color",
  "type": "select",
  "label": "Color",
  "options": [
    { "value": "red", "label": "Red" },
    { "value": "blue", "label": "Blue" }
  ]
}

Use "returnFormat": "both" para obter o valor e o rótulo:

PHP
echo $a['color']['value'];  // "red"
echo $a['color']['label'];  // "Red"

O mesmo padrão se aplica aos tipos radio e checkbox.

Alternância e verdadeiro/falso

ACF:

PHP
['name' => 'show_cta', 'type' => 'true_false', 'label' => 'Show CTA']

Blockstudio:

JSON
{ "id": "showCta", "type": "toggle", "label": "Show CTA" }

ACF:

PHP
['name' => 'cta', 'type' => 'link', 'return_format' => 'array']

// Template
$link = get_field('cta');
echo $link['url'];
echo $link['title'];
echo $link['target'];

Blockstudio:

JSON
{ "id": "cta", "type": "link", "label": "CTA", "opensInNewTab": true }
PHP
echo $a['cta']['url'];
echo $a['cta']['title'];
echo $a['cta']['target'];

Cor e gradiente

ACF:

PHP
['name' => 'bgColor', 'type' => 'color_picker', 'label' => 'Background']

Blockstudio:

JSON
{ "id": "bgColor", "type": "color", "label": "Background" }
{ "id": "bgGradient", "type": "gradient", "label": "Background Gradient" }

O tipo color se integra à paleta de cores WordPress. O tipo gradient oferece um seletor de gradiente.

Número, intervalo e data

ACF:

PHP
['name' => 'count', 'type' => 'number', 'min' => 1, 'max' => 10]
['name' => 'opacity', 'type' => 'range', 'min' => 0, 'max' => 100, 'step' => 5]
['name' => 'eventDate', 'type' => 'date_picker']

Blockstudio:

JSON
{ "id": "count", "type": "number", "label": "Count", "min": 1, "max": 10 }
{ "id": "opacity", "type": "range", "label": "Opacity", "min": 0, "max": 100, "step": 5 }
{ "id": "eventDate", "type": "date", "label": "Event Date" }

Repetidores

O campo repetidor de ACF corresponde diretamente ao tipo repeater de Blockstudio. Os templates ACF normalmente percorrem os dados com have_rows() / the_row() / get_sub_field() (get_field() em um repetidor também retorna um array de linhas); Blockstudio tem apenas o array PHP simples, já em $a.

ACF:

PHP
['name' => 'features', 'type' => 'repeater', 'sub_fields' => [
  ['name' => 'title', 'type' => 'text'],
  ['name' => 'description', 'type' => 'textarea'],
]]

// Template
if (have_rows('features')) :
  while (have_rows('features')) : the_row();
    echo get_sub_field('title');
    echo get_sub_field('description');
  endwhile;
endif;

Blockstudio:

JSON
{
  "id": "features",
  "type": "repeater",
  "label": "Features",
  "min": 1,
  "max": 10,
  "attributes": [
    { "id": "title", "type": "text", "label": "Title" },
    { "id": "description", "type": "textarea", "label": "Description" }
  ]
}
PHP
<?php foreach ($a['features'] as $feature) : ?>
  <h3><?php echo esc_html($feature['title']); ?></h3>
  <p><?php echo esc_html($feature['description']); ?></p>
<?php endforeach; ?>

Os repetidores Blockstudio permitem aninhamento (um repetidor dentro de outro) até 3 níveis.

Grupos

O campo de grupo de ACF corresponde ao tipo group de Blockstudio. Os IDs dos campos dentro dos grupos recebem o prefixo do ID do grupo.

ACF:

PHP
['name' => 'author', 'type' => 'group', 'sub_fields' => [
  ['name' => 'name', 'type' => 'text'],
  ['name' => 'role', 'type' => 'text'],
]]

// Template
$author = get_field('author');
echo $author['name'];
echo $author['role'];

Blockstudio:

JSON
{
  "id": "author",
  "type": "group",
  "title": "Author",
  "attributes": [
    { "id": "name", "type": "text", "label": "Name" },
    { "id": "role", "type": "text", "label": "Role" }
  ]
}
PHP
<?php $author = bs_get_group($a, 'author'); ?>
<p><?php echo esc_html($author['name']); ?></p>
<p><?php echo esc_html($author['role']); ?></p>

O helper bs_get_group() remove o prefixo do grupo dos IDs dos campos, permitindo acessá-los diretamente. Sem ele, você acessaria os campos como $a['author_name'] e $a['author_role'].

Lógica condicional

Tanto ACF quanto Blockstudio permitem lógica condicional para mostrar e ocultar campos com base nos valores de outros campos.

ACF:

PHP
['name' => 'showSubtitle', 'type' => 'true_false'],
[
  'name' => 'subtitle',
  'type' => 'text',
  'conditional_logic' => [[['field' => 'field_showSubtitle', 'operator' => '==', 'value' => '1']]]
]

Blockstudio:

JSON
{ "id": "showSubtitle", "type": "toggle", "label": "Show Subtitle" },
{
  "id": "subtitle",
  "type": "text",
  "label": "Subtitle",
  "conditions": [[{ "id": "showSubtitle", "operator": "==", "value": true }]]
}

As condições de Blockstudio referenciam IDs de campos diretamente (não as chaves dos campos). Operadores disponíveis: ==, !=, includes, !includes, empty, !empty, <, >, <=, >=.

Blockstudio também permite condições globais baseadas no tipo de post, ID do post, função do usuário e ID do usuário:

JSON
{
  "conditions": [[{ "type": "postType", "operator": "==", "value": "page" }]]
}

InnerBlocks

Tanto ACF quanto Blockstudio permitem usar InnerBlocks para aninhar outros blocos no seu bloco personalizado, com a mesma tag <InnerBlocks /> e os mesmos atributos allowedBlocks, template e templateLock; por isso, esta parte do template geralmente pode ser mantida sem alterações.

Blockstudio:

PHP
<div useBlockProps class="my-wrapper">
  <InnerBlocks
    allowedBlocks='<?php echo esc_attr(wp_json_encode(["core/heading", "core/paragraph", "core/image"])); ?>'
    template='<?php echo esc_attr(wp_json_encode([
      ["core/heading", ["placeholder" => "Section title"]],
      ["core/paragraph", ["placeholder" => "Section content"]]
    ])); ?>'
    templateLock="insert"
  />
</div>

A tag <InnerBlocks /> é substituída pelo componente React no editor e pelo conteúdo renderizado do bloco no frontend.

Armazenamento de metadados do post

Tanto ACF Blocks quanto Blockstudio armazenam valores de campos como atributos de bloco no conteúdo do post por padrão, não em metadados do post. Isso significa que os valores dos campos não podem ser consultados com WP_Query, a menos que você opte pelo armazenamento em metadados.

ACF adicionou o armazenamento opcional de metadados do post para blocos em ACF PRO 6.3 por meio de usePostMeta: true, para um bloco de nível superior por página. Blockstudio tem um mecanismo opcional por campo, usando a propriedade storage:

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

A chave de metadados é registrada automaticamente com show_in_rest. Acesse-a em qualquer lugar com get_post_meta($post_id, 'is_featured', true).

Para valores de todo o site (como páginas de opções ACF), use o armazenamento de opções:

JSON
{
  "storage": {
    "type": "option",
    "optionKey": "site_company_name"
  }
}

Estendendo blocos existentes

A regra de localização de blocos de ACF associa grupos de campos apenas a blocos ACF; ela não adiciona campos a blocos do núcleo ou de terceiros. O caminho de ACF para blocos do núcleo, como Título, Parágrafo, Imagem e Botão, é WordPress Block Bindings API, que conecta atributos de blocos existentes a valores de campos de ACF. Blockstudio pode adicionar novos campos e controles a qualquer bloco registrado por meio de arquivos de extensão.

Crie um arquivo de extensão no diretório blockstudio:

JSON
{
  "name": "core/heading",
  "blockstudio": {
    "extend": true,
    "attributes": [
      {
        "id": "accentColor",
        "type": "color",
        "label": "Accent Color",
        "set": [{ "attribute": "style", "value": "color: {attributes.accentColor}" }]
      }
    ]
  }
}

A propriedade set aplica automaticamente o valor do campo ao HTML do bloco. Use curingas para estender vários blocos de uma só vez: "name": "core/*".

Lista de verificação da migração

  1. Crie a pasta do bloco em theme/blockstudio/{block-name}/ com block.json e index.php.
  2. Mova as definições de campos do grupo de campos do bloco (Local JSON, acf_add_local_field_group() ou uma matriz acf.fields inline) para a matriz blockstudio.attributes em block.json. Altere name para id, remova key e ajuste os nomes dos tipos conforme necessário.
  3. Atualize o acesso ao modelo de get_field('name') para $a['name']. Substitua os loops have_rows() por foreach ($a['repeater'] as $item).
  4. Substitua get_sub_field() pelo acesso direto à matriz: $item['fieldId'].
  5. Adicione useBlockProps ao elemento mais externo do modelo para integrar corretamente com o editor.
  6. Mova a lógica condicional de conditional_logic de ACF para conditions de Blockstudio, usando os IDs dos campos em vez das chaves.
  7. Adicione armazenamento para quaisquer campos que antes eram consultados por meio de get_post_meta() ou usados em WP_Query.
  8. Remova o código de registro de ACF: as chamadas register_block_type() e as chaves acf dos blocos migrados (ou suas chamadas acf_register_block_type()) e seus grupos de campos, estejam eles em Local JSON, acf_add_local_field_group(), uma matriz acf.fields inline ou no painel de administração.
  9. Teste no editor para verificar se os campos aparecem corretamente e, em seguida, confira a saída do site.