Migrar desde ACF Blocks
Si ha creado bloques personalizados de WordPress con ACF (Advanced Custom Fields), migrarlos a Blockstudio es sencillo. Los conceptos son similares: se definen campos, se escribe una plantilla y el bloque aparece en el editor. Las diferencias son que Blockstudio detecta las carpetas de bloques por sí solo, define los campos en su propio esquema dentro de block.json y proporciona a cada plantilla los valores de sus campos en una única matriz $a.
Esta guía explica la migración paso a paso, con comparaciones paralelas de los patrones de ACF y Blockstudio.
La diferencia fundamental
Desde ACF 6.0, un bloque de ACF es un block.json con una clave acf que indica su plantilla de renderizado, y cada carpeta de bloques se registra con su propia llamada a register_block_type(). Los campos provienen de un grupo de campos vinculado al bloque mediante una regla de ubicación de Block (creado en el administrador, sincronizado mediante Local JSON o registrado con acf_add_local_field_group()) o, desde ACF PRO 6.8.1, de una matriz acf.fields en línea en el mismo block.json. Blockstudio sustituye la llamada de registro por detección automática basada en archivos: cree una carpeta con un block.json y un index.php, y el bloque se registrará automáticamente.
ACF:
{
"name": "acf/hero",
"title": "Hero",
"acf": {
"renderTemplate": "template.php"
}
}
add_action( 'init', function () {
register_block_type( __DIR__ . '/blocks/hero' );
} );
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
$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:
{
"name": "my-theme/hero",
"title": "Hero",
"blockstudio": {
"attributes": [
{ "id": "title", "type": "text", "label": "Title" },
{ "id": "image", "type": "files", "label": "Background", "multiple": false }
]
}
}
<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>
No hace falta una llamada de registro ni una función de retorno de renderizado: la estructura de carpetas es el registro, y los campos se encuentran en block.json junto a la plantilla. La plantilla lee $a en lugar de llamar a get_field().
Registro de bloques
ACF
Los bloques actuales de ACF se registran desde un block.json con una clave acf (renderTemplate o renderCallback, además de opciones como blockVersion), que se carga mediante una llamada explícita a register_block_type() por cada carpeta de bloques, normalmente desde init en functions.php o desde un archivo del complemento. Es posible que los bloques más antiguos aún utilicen acf_register_block_type(), que ACF documenta como obsoleto desde ACF 6.0; sigue funcionando, así que migre esos bloques del mismo modo.
Blockstudio
Cree una carpeta en el directorio blockstudio/ de su tema (o en blocks/, si lo prefiere). Añada un block.json con los metadatos de bloque estándar de WordPress y una clave blockstudio. Eso es todo.
theme/
└── blockstudio/
└── hero/
├── block.json
└── index.php
block.json usa el formato estándar de WordPress block.json⟧ con la clave blockstudio para los campos y la configuración:
{
"name": "my-theme/hero",
"title": "Hero",
"category": "theme",
"icon": "cover-image",
"description": "Full-width hero section with background image.",
"blockstudio": {
"attributes": []
}
}
Acceso a los valores de los campos
Este es el cambio más habitual que hará durante la migración.
| ACF | Blockstudio |
|---|---|
get_field('title') |
$a['title'] |
get_field('title', $post_id) |
$a['title'] (siempre disponible) |
the_field('title') |
<?php echo $a['title']; ?> |
have_rows('items') / the_row() |
foreach ($a['items'] as $item) |
get_sub_field('name') |
$item['name'] |
La variable $a es una forma abreviada de $attributes y contiene todos los valores de campo del bloque actual. Siempre está disponible en la plantilla, tanto en el editor como en el frontend.
Variables de plantilla
Blockstudio proporciona varias variables en cada plantilla:
| Variable | Forma abreviada | Descripción |
|---|---|---|
$attributes |
$a |
Todos los valores de campo |
$block |
$b |
Metadatos del bloque (nombre, título, dir, url, postId) |
$context |
$c |
Contexto del bloque principal |
$content |
Contenido de InnerBlocks | |
$post_id |
ID de la entrada actual (funciona en el editor y en el frontend; post_id o postId en Twig) |
Equivalencias de tipos de campo
La mayoría de los tipos de campo de ACF tienen un equivalente directo en Blockstudio. La sintaxis de JSON es distinta, pero los conceptos se corresponden claramente.
Campos de texto y contenido
ACF:
['name' => 'title', 'type' => 'text', 'label' => 'Title', 'default_value' => 'Hello']
['name' => 'bio', 'type' => 'textarea', 'label' => 'Bio', 'rows' => 4]
['name' => 'content', 'type' => 'wysiwyg', 'label' => 'Content']
Blockstudio:
{ "id": "title", "type": "text", "label": "Title", "default": "Hello" }
{ "id": "bio", "type": "textarea", "label": "Bio", "rows": 4 }
{ "id": "content", "type": "wysiwyg", "label": "Content" }
Para el texto editable en el editor de bloques (no solo un campo de texto), use el tipo richtext con el componente <RichText />:
{ "id": "heading", "type": "richtext" }
<RichText attribute="heading" tag="h1" placeholder="Enter heading" />
Campos de imagen y archivo
Los campos image y file de ACF corresponden al tipo files de Blockstudio:
ACF:
['name' => 'photo', 'type' => 'image', 'return_format' => 'array']
['name' => 'gallery', 'type' => 'gallery', 'return_format' => 'array']
['name' => 'document', 'type' => 'file', 'return_format' => 'array']
Blockstudio:
{ "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"] }
La estructura del objeto devuelto es similar:
// ACF
$image = get_field('photo');
echo $image['url'];
echo $image['alt'];
// Blockstudio
echo $a['photo']['url'];
echo $a['photo']['alt'];
Propiedades disponibles: ID, title, alt, caption, description, href, url, sizes. Las dimensiones están en sizes, por ejemplo $a['photo']['sizes']['full-width'].
Selectores, botones de opción y casillas de verificación
ACF:
[
'name' => 'color',
'type' => 'select',
'choices' => ['red' => 'Red', 'blue' => 'Blue'],
'return_format' => 'value',
]
Blockstudio:
{
"id": "color",
"type": "select",
"label": "Color",
"options": [
{ "value": "red", "label": "Red" },
{ "value": "blue", "label": "Blue" }
]
}
Use "returnFormat": "both" para obtener tanto el valor como la etiqueta:
echo $a['color']['value']; // "red"
echo $a['color']['label']; // "Red"
El mismo patrón se aplica a los tipos radio y checkbox.
Alternancia y verdadero/falso
ACF:
['name' => 'show_cta', 'type' => 'true_false', 'label' => 'Show CTA']
Blockstudio:
{ "id": "showCta", "type": "toggle", "label": "Show CTA" }
Campo de enlace
ACF:
['name' => 'cta', 'type' => 'link', 'return_format' => 'array']
// Template
$link = get_field('cta');
echo $link['url'];
echo $link['title'];
echo $link['target'];
Blockstudio:
{ "id": "cta", "type": "link", "label": "CTA", "opensInNewTab": true }
echo $a['cta']['url'];
echo $a['cta']['title'];
echo $a['cta']['target'];
Color y degradado
ACF:
['name' => 'bgColor', 'type' => 'color_picker', 'label' => 'Background']
Blockstudio:
{ "id": "bgColor", "type": "color", "label": "Background" }
{ "id": "bgGradient", "type": "gradient", "label": "Background Gradient" }
El tipo color se integra con la paleta de colores de WordPress. El tipo gradient proporciona un selector de degradado.
Número, intervalo y fecha
ACF:
['name' => 'count', 'type' => 'number', 'min' => 1, 'max' => 10]
['name' => 'opacity', 'type' => 'range', 'min' => 0, 'max' => 100, 'step' => 5]
['name' => 'eventDate', 'type' => 'date_picker']
Blockstudio:
{ "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" }
Campos repetidores
El campo repetidor de ACF corresponde directamente al tipo repeater de Blockstudio. Las plantillas de ACF suelen recorrer los datos con have_rows() / the_row() / get_sub_field() (get_field() también devuelve una matriz de filas para un repetidor); Blockstudio solo tiene la matriz simple PHP, que ya está en $a.
ACF:
['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:
{
"id": "features",
"type": "repeater",
"label": "Features",
"min": 1,
"max": 10,
"attributes": [
{ "id": "title", "type": "text", "label": "Title" },
{ "id": "description", "type": "textarea", "label": "Description" }
]
}
<?php foreach ($a['features'] as $feature) : ?>
<h3><?php echo esc_html($feature['title']); ?></h3>
<p><?php echo esc_html($feature['description']); ?></p>
<?php endforeach; ?>
Los campos repetidores de Blockstudio admiten anidamiento (un repetidor dentro de otro) de hasta 3 niveles.
Grupos
El campo de grupo de ACF corresponde al tipo group de Blockstudio. Los ID de los campos dentro de los grupos llevan el ID del grupo como prefijo.
ACF:
['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:
{
"id": "author",
"type": "group",
"title": "Author",
"attributes": [
{ "id": "name", "type": "text", "label": "Name" },
{ "id": "role", "type": "text", "label": "Role" }
]
}
<?php $author = bs_get_group($a, 'author'); ?>
<p><?php echo esc_html($author['name']); ?></p>
<p><?php echo esc_html($author['role']); ?></p>
El asistente bs_get_group() elimina el prefijo del grupo de los ID de los campos para que pueda acceder a ellos directamente. Sin este asistente, accedería a los campos como $a['author_name'] y $a['author_role'].
Lógica condicional
Tanto ACF como Blockstudio admiten lógica condicional para mostrar y ocultar campos según los valores de otros campos.
ACF:
['name' => 'showSubtitle', 'type' => 'true_false'],
[
'name' => 'subtitle',
'type' => 'text',
'conditional_logic' => [[['field' => 'field_showSubtitle', 'operator' => '==', 'value' => '1']]]
]
Blockstudio:
{ "id": "showSubtitle", "type": "toggle", "label": "Show Subtitle" },
{
"id": "subtitle",
"type": "text",
"label": "Subtitle",
"conditions": [[{ "id": "showSubtitle", "operator": "==", "value": true }]]
}
Las condiciones de Blockstudio hacen referencia directamente a los ID de los campos (no a las claves de los campos). Operadores disponibles: ==, !=, includes, !includes, empty, !empty, <, >, <=, >=.
Blockstudio también admite condiciones globales basadas en el tipo de entrada, el ID de la entrada, el perfil del usuario y el ID del usuario:
{
"conditions": [[{ "type": "postType", "operator": "==", "value": "page" }]]
}
InnerBlocks
Tanto ACF como Blockstudio admiten InnerBlocks para anidar otros bloques dentro de su bloque personalizado, con la misma etiqueta <InnerBlocks /> y los mismos atributos allowedBlocks, template y templateLock, por lo que esta parte de la plantilla suele conservarse sin cambios.
Blockstudio:
<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>
La etiqueta <InnerBlocks /> se sustituye por el componente React en el editor y por el contenido renderizado del bloque en el frontend.
Almacenamiento de metadatos de entradas
Tanto ACF Blocks como Blockstudio almacenan los valores de los campos como atributos de bloque en el contenido de la entrada de forma predeterminada, no en los metadatos de la entrada. Esto significa que los valores de los campos no se pueden consultar con WP_Query a menos que se active el almacenamiento en metadatos.
ACF añadió el almacenamiento opcional en los metadatos de la entrada para bloques en ACF PRO 6.3 mediante usePostMeta: true, para un bloque de nivel superior por página. Blockstudio ofrece un mecanismo opcional por campo mediante la propiedad storage:
{
"id": "featured",
"type": "toggle",
"label": "Featured",
"storage": {
"type": "postMeta",
"postMetaKey": "is_featured"
}
}
La clave de metadatos se registra automáticamente con show_in_rest. Acceda a ella desde cualquier lugar con get_post_meta($post_id, 'is_featured', true).
Para valores de todo el sitio (como las páginas de opciones de ACF), use el almacenamiento de opciones:
{
"storage": {
"type": "option",
"optionKey": "site_company_name"
}
}
Ampliar bloques existentes
La regla de ubicación de bloques de ACF solo asigna grupos de campos a bloques de ACF; no añade campos a bloques del núcleo ni de terceros. Para añadir campos a bloques del núcleo como Encabezado, Párrafo, Imagen y Botón, ACF ofrece WordPress Block Bindings API, que conecta los atributos de bloques existentes con los valores de campos de ACF. Blockstudio puede añadir campos y controles nuevos a cualquier bloque registrado mediante archivos de extensión.
Cree un archivo de extensión en el directorio blockstudio:
{
"name": "core/heading",
"blockstudio": {
"extend": true,
"attributes": [
{
"id": "accentColor",
"type": "color",
"label": "Accent Color",
"set": [{ "attribute": "style", "value": "color: {attributes.accentColor}" }]
}
]
}
}
La propiedad set aplica automáticamente el valor del campo al HTML del bloque. Use comodines para ampliar varios bloques a la vez: "name": "core/*".
Lista de verificación para la migración
- Cree la carpeta del bloque en
theme/blockstudio/{block-name}/conblock.jsonyindex.php. - Traslade las definiciones de campos del grupo de campos del bloque (Local JSON,
acf_add_local_field_group()o una matrizacf.fieldsintegrada) a la matrizblockstudio.attributesenblock.json. Cambienameporid, eliminekeyy ajuste los nombres de tipo según sea necesario. - Actualice el acceso a las plantillas de
get_field('name')a$a['name']. Sustituya los bucleshave_rows()porforeach ($a['repeater'] as $item). - Sustituya
get_sub_field()por acceso directo a la matriz:$item['fieldId']. - Añada
useBlockPropsal elemento más externo de la plantilla para integrarla correctamente con el editor. - Traslade la lógica condicional de ACF’s
conditional_logica Blockstudio’sconditions; haga referencia a los ID de campo en lugar de a las claves de campo. - Añada almacenamiento para los campos que antes se consultaban mediante
get_post_meta()o se usaban enWP_Query. - Elimine el código de registro de ACF: las llamadas
register_block_type()y las clavesacfde los bloques migrados (o sus llamadasacf_register_block_type()), así como sus grupos de campos, ya estén en Local JSON,acf_add_local_field_group(), una matrizacf.fieldsintegrada o el panel de administración. - Pruebe en el editor que los campos aparezcan correctamente y, después, compruebe la salida del frontend.