Aller au contenu

Migrer depuis ACF Blocks

Si vous avez créé des blocs WordPress personnalisés avec ACF (Advanced Custom Fields), la migration vers Blockstudio est simple. Les concepts sont similaires : vous définissez des champs, écrivez un modèle et le bloc apparaît dans l’éditeur. Les différences : Blockstudio détecte automatiquement les dossiers de blocs, définit les champs dans son propre schéma dans block.json et fournit à chaque modèle les valeurs de ses champs dans un tableau $a unique.

Ce guide présente la migration étape par étape, avec des comparaisons côte à côte des modèles ACF et Blockstudio.

Différence fondamentale

Depuis ACF 6.0, un bloc ACF est un block.json doté d’une clé acf qui désigne son modèle de rendu, et chaque dossier de bloc est enregistré avec son propre appel à register_block_type(). Les champs proviennent d’un groupe de champs associé au bloc par une règle d’emplacement Block (créé dans l’interface d’administration, synchronisé via Local JSON ou enregistré avec acf_add_local_field_group()) ou, depuis ACF PRO 6.8.1, d’un tableau acf.fields intégré au même block.json. Blockstudio remplace l’appel d’enregistrement par la détection automatique des fichiers : créez un dossier contenant un block.json et un index.php, et le bloc est enregistré automatiquement.

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>

Aucun appel d’enregistrement ni fonction de rendu : la structure des dossiers tient lieu d’enregistrement, et les champs se trouvent dans block.json à côté du modèle. Celui-ci lit $a au lieu d’appeler get_field().

Enregistrement des blocs

ACF

Les blocs ACF actuels sont enregistrés depuis un block.json doté d’une clé acf (renderTemplate ou renderCallback, avec des options comme blockVersion), puis chargés par un appel explicite à register_block_type() pour chaque dossier de bloc, généralement dans init de functions.php ou dans un fichier d’extension. Les blocs plus anciens utilisent parfois acf_register_block_type(), que ACF indique comme obsolète depuis ACF 6.0. Cela fonctionne toujours ; migrez ces blocs de la même manière.

Blockstudio

Créez un dossier dans le répertoire blockstudio/ de votre thème (ou dans blocks/, si vous préférez). Ajoutez un block.json avec les métadonnées de bloc standard WordPress et une clé blockstudio. Voilà.

Code
theme/
└── blockstudio/
    └── hero/
        ├── block.json
        └── index.php

Le block.json utilise le format standard WordPress block.json, avec la clé blockstudio pour les champs et la configuration :

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

Accéder aux valeurs des champs

C’est le changement le plus courant à effectuer pendant la migration.

ACF Blockstudio
get_field('title') $a['title']
get_field('title', $post_id) $a['title'] (toujours 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 est un raccourci pour $attributes et contient toutes les valeurs des champs du bloc courant. Elle est toujours disponible dans le modèle, dans l’éditeur comme sur l’interface publique.

Variables de modèle

Blockstudio fournit plusieurs variables dans chaque modèle :

Variable Raccourci Description
$attributes $a Toutes les valeurs des champs
$block $b Métadonnées du bloc (name, title, dir, url, postId)
$context $c Contexte du bloc parent
$content Contenu InnerBlocks
$post_id ID de l’article courant (fonctionne dans l’éditeur et sur l’interface publique ; post_id ou postId dans Twig)

Correspondance des types de champs

La plupart des types de champs ACF ont un équivalent direct dans Blockstudio. La syntaxe JSON diffère, mais les concepts correspondent bien.

Champs de texte et de contenu

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" }

Pour du texte modifiable dans l’éditeur de blocs (et pas seulement un champ de saisie), utilisez le type richtext avec le composant <RichText /> :

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

Champs d’image et de fichier

Les champs image et file de ACF correspondent au type 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"] }

La structure de l’objet renvoyé est similaire :

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

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

Propriétés disponibles : ID, title, alt, caption, description, href, url, sizes. Les dimensions se trouvent dans sizes, par exemple $a['photo']['sizes']['full-width'].

Sélecteur, boutons radio et cases à cocher

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" }
  ]
}

Utilisez "returnFormat": "both" pour obtenir la valeur et le libellé :

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

Le même modèle s’applique aux types radio et checkbox.

Bascule et vrai/faux

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'];

Couleur et dégradé

ACF:

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

Blockstudio:

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

Le type color s’intègre à la palette de couleurs WordPress. Le type gradient fournit un sélecteur de dégradé.

Nombre, plage et date

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" }

Répétiteurs

Le champ répétiteur de ACF correspond directement au type repeater de Blockstudio. Les modèles ACF parcourent généralement les données avec have_rows() / the_row() / get_sub_field() (get_field() renvoie aussi un tableau de lignes pour un répétiteur) ; Blockstudio ne fournit que le tableau simple PHP, déjà au format $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; ?>

Les répétiteurs Blockstudio prennent en charge l’imbrication (un répétiteur dans un autre) jusqu’à 3 niveaux.

Groupes

Le champ de groupe de ACF correspond au type group de Blockstudio. Les identifiants des champs dans les groupes sont préfixés par l’identifiant du groupe.

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>

L’utilitaire bs_get_group() retire le préfixe de groupe des identifiants de champ, ce qui simplifie leur accès. Sans lui, vous accéderiez aux champs sous la forme $a['author_name'] et $a['author_role'].

Logique conditionnelle

ACF et Blockstudio prennent tous deux en charge la logique conditionnelle permettant d’afficher ou de masquer des champs en fonction des valeurs d’autres champs.

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 }]]
}

Les conditions Blockstudio font référence directement aux identifiants des champs (et non à leurs clés). Opérateurs disponibles : ==, !=, includes, !includes, empty, !empty, <, >, <=, >=.

Blockstudio prend également en charge les conditions globales fondées sur le type d’article, son ID, le rôle et l’ID de l’utilisateur :

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

InnerBlocks

ACF et Blockstudio prennent tous deux en charge InnerBlocks pour imbriquer d’autres blocs dans votre bloc personnalisé, avec la même balise <InnerBlocks /> et les mêmes attributs allowedBlocks, template et templateLock. Cette partie du modèle peut donc généralement être reprise telle quelle.

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>

La balise <InnerBlocks /> est remplacée par le composant React dans l’éditeur et par le contenu rendu du bloc sur l’interface publique.

Stockage des métadonnées d’article

ACF Blocks et Blockstudio stockent par défaut les valeurs des champs comme attributs de blocs dans le contenu de la publication, et non dans les métadonnées de publication. Cela signifie que les valeurs des champs ne peuvent pas être interrogées avec WP_Query, sauf si vous activez le stockage dans les métadonnées.

ACF a ajouté le stockage facultatif dans les métadonnées de publication pour les blocs dans ACF PRO 6.3 via usePostMeta: true, pour un bloc de premier niveau par page. Blockstudio propose un mécanisme facultatif par champ, à l’aide de la propriété storage :

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

La clé de métadonnée est enregistrée automatiquement avec show_in_rest. Vous pouvez y accéder n’importe où avec get_post_meta($post_id, 'is_featured', true).

Pour les valeurs à l’échelle du site (comme les pages d’options ACF), utilisez le stockage des options :

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

Étendre des blocs existants

La règle d’emplacement des blocs de ACF associe les groupes de champs uniquement aux blocs ACF ; elle n’ajoute pas de champs aux blocs du cœur ou de tiers. Pour les blocs du cœur tels que Titre, Paragraphe, Image et Bouton, ACF s’appuie sur WordPress Block Bindings API, qui relie les attributs de blocs existants aux valeurs de champs ACF. Blockstudio peut ajouter de nouveaux champs et contrôles à tout bloc enregistré au moyen de fichiers d’extension.

Créez un fichier d’extension dans votre répertoire blockstudio :

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

La propriété set applique automatiquement la valeur du champ à HTML du bloc. Utilisez des caractères génériques pour étendre plusieurs blocs à la fois : "name": "core/*".

Liste de contrôle pour la migration

  1. Créez le dossier du bloc dans theme/blockstudio/{block-name}/ avec block.json et index.php.
  2. Déplacez les définitions de champs du groupe de champs du bloc (Local JSON, acf_add_local_field_group() ou tableau acf.fields intégré) vers le tableau blockstudio.attributes dans block.json. Remplacez name par id, supprimez key et ajustez les noms de types au besoin.
  3. Mettez à jour l’accès au modèle de get_field('name') vers $a['name']. Remplacez les boucles have_rows() par foreach ($a['repeater'] as $item).
  4. Remplacez get_sub_field() par un accès direct au tableau : $item['fieldId'].
  5. Ajoutez useBlockProps à l’élément le plus externe de votre modèle pour assurer son intégration à l’éditeur.
  6. Déplacez la logique conditionnelle de conditional_logic de ACF vers conditions de Blockstudio, en faisant référence aux ID de champs plutôt qu’aux clés de champs.
  7. Ajoutez le stockage pour tous les champs précédemment interrogés via get_post_meta() ou utilisés dans WP_Query.
  8. Supprimez le code d’enregistrement ACF : les appels register_block_type() et les clés acf des blocs migrés (ou leurs appels acf_register_block_type()), ainsi que leurs groupes de champs, qu’ils se trouvent dans Local JSON, acf_add_local_field_group(), un tableau acf.fields intégré ou l’interface d’administration.
  9. Testez dans l’éditeur pour vérifier que les champs s’affichent correctement, puis vérifiez le rendu côté public.