Lewati ke konten

Migrasi dari ACF Blocks

Jika Anda telah membuat blok kustom WordPress menggunakan ACF (Advanced Custom Fields), migrasi ke Blockstudio cukup mudah. Konsepnya serupa: Anda menentukan field, menulis template, lalu blok muncul di editor. Perbedaannya, Blockstudio menemukan folder blok sendiri, mendeklarasikan field dalam skemanya sendiri di block.json, dan memberikan nilai field kepada setiap template sebagai satu array $a.

Panduan ini membahas proses migrasi langkah demi langkah, dengan perbandingan pola ACF dan Blockstudio secara berdampingan.

Perbedaan utama

Sejak ACF 6.0, blok ACF adalah block.json dengan kunci acf yang menentukan template render-nya, dan setiap folder blok didaftarkan dengan pemanggilan register_block_type() tersendiri. Field berasal dari grup field yang dikaitkan ke blok dengan aturan lokasi Block (dibuat di admin, disinkronkan melalui Local JSON, atau didaftarkan dengan acf_add_local_field_group()), atau, sejak ACF PRO 6.8.1, dari array acf.fields inline di block.json yang sama. Blockstudio mengganti pemanggilan pendaftaran dengan penemuan otomatis berbasis file: buat folder dengan block.json dan index.php, lalu blok didaftarkan secara otomatis.

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>

Tidak ada pemanggilan pendaftaran maupun callback render: struktur folder menjadi pendaftarannya, dan field berada di block.json bersama template. Template membaca $a alih-alih memanggil get_field().

Pendaftaran blok

ACF

Blok ACF saat ini didaftarkan dari block.json dengan kunci acf (renderTemplate atau renderCallback, ditambah opsi seperti blockVersion), yang dimuat melalui pemanggilan register_block_type() secara eksplisit untuk setiap folder blok, biasanya pada init di functions.php atau file plugin. Blok lama mungkin masih menggunakan acf_register_block_type(), yang oleh ACF didokumentasikan sebagai usang sejak ACF 6.0; fitur ini masih berfungsi, jadi migrasikan blok tersebut dengan cara yang sama.

Blockstudio

Buat folder di direktori blockstudio/ tema Anda (atau blocks/ jika Anda lebih suka). Tambahkan block.json dengan metadata blok WordPress standar serta kunci blockstudio. Selesai.

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

block.json menggunakan format standar WordPress block.json dengan kunci blockstudio untuk bidang dan konfigurasi:

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

Mengakses nilai field

Inilah perubahan paling umum yang akan Anda lakukan selama migrasi.

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

Variabel $a adalah singkatan dari $attributes dan berisi semua nilai field untuk blok saat ini. Variabel ini selalu tersedia di template, baik di editor maupun frontend.

Variabel template

Blockstudio menyediakan beberapa variabel di setiap template:

Variabel Singkatan Deskripsi
$attributes $a Semua nilai field
$block $b Metadata blok (name, title, dir, url, postId)
$context $c Konteks blok induk
$content Konten InnerBlocks
$post_id ID post saat ini (berfungsi di editor dan frontend; post_id atau postId di Twig)

Pemetaan tipe field

Sebagian besar tipe field ACF memiliki padanan langsung di Blockstudio. Sintaks JSON berbeda, tetapi konsepnya dapat dipetakan dengan jelas.

Field teks dan konten

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

Untuk teks yang dapat diedit di editor blok (bukan sekadar input teks), gunakan tipe richtext dengan komponen <RichText />:

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

Field gambar dan file

Field image dan file milik ACF dipetakan ke tipe files milik 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"] }

Struktur objek yang dikembalikan serupa:

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

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

Properti yang tersedia: ID, title, alt, caption, description, href, url, sizes. Dimensi tersedia di sizes, misalnya $a['photo']['sizes']['full-width'].

Pilihan, radio, dan kotak centang

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

Gunakan "returnFormat": "both" untuk mendapatkan nilai dan label:

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

Pola yang sama berlaku untuk tipe radio dan checkbox.

Toggle dan true/false

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

Warna dan gradien

ACF:

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

Blockstudio:

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

Tipe color terintegrasi dengan palet warna WordPress. Tipe gradient menyediakan pemilih gradien.

Angka, rentang, dan tanggal

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

Repeater

Field repeater ACF dipetakan langsung ke tipe repeater milik Blockstudio. Template ACF biasanya melakukan perulangan dengan have_rows() / the_row() / get_sub_field() (get_field() pada repeater juga mengembalikan array baris); Blockstudio hanya memiliki array PHP biasa yang sudah berbentuk $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; ?>

Repeater Blockstudio mendukung nesting (repeater di dalam repeater) hingga 3 level.

Grup

Field grup ACF dipetakan ke tipe group milik Blockstudio. ID field di dalam grup diberi awalan berupa ID grup.

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>

Helper bs_get_group() menghapus awalan grup dari ID field, sehingga Anda dapat mengaksesnya dengan mudah. Tanpa helper ini, Anda akan mengakses field sebagai $a['author_name'] dan $a['author_role'].

Logika Kondisional

ACF dan Blockstudio mendukung logika kondisional untuk menampilkan dan menyembunyikan field berdasarkan nilai field lain.

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

Kondisi Blockstudio merujuk langsung ke ID field (bukan key field). Operator yang tersedia: ==, !=, includes, !includes, empty, !empty, <, >, <=, >=.

Blockstudio juga mendukung kondisi global berdasarkan tipe post, ID post, peran pengguna, dan ID pengguna:

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

InnerBlocks

ACF dan Blockstudio mendukung InnerBlocks untuk menambahkan blok lain di dalam blok kustom Anda, dengan tag <InnerBlocks /> serta atribut allowedBlocks, template, dan templateLock yang sama. Karena itu, bagian template ini biasanya dapat dipindahkan tanpa perubahan.

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>

Tag <InnerBlocks /> digantikan dengan komponen React di editor dan dengan konten blok yang dirender di frontend.

Penyimpanan meta post

Baik ACF Blocks maupun Blockstudio secara default menyimpan nilai field sebagai atribut blok dalam konten pos, bukan di meta pos. Artinya, nilai field tidak dapat dikueri dengan WP_Query kecuali Anda memilih penyimpanan meta.

ACF menambahkan penyimpanan meta pos opsional untuk blok di ACF PRO 6.3 melalui usePostMeta: true, untuk satu blok tingkat teratas per halaman. Blockstudio memiliki mekanisme opsional per field, menggunakan properti storage:

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

Kunci meta didaftarkan otomatis dengan show_in_rest. Akses di mana saja dengan get_post_meta($post_id, 'is_featured', true).

Untuk nilai yang berlaku di seluruh situs (seperti halaman opsi ACF), gunakan penyimpanan opsi:

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

Memperluas blok yang sudah ada

Aturan lokasi blok milik ACF hanya memasang grup field ke blok ACF; aturan ini tidak menambahkan field ke blok inti atau pihak ketiga. Jalur ACF untuk blok inti seperti Heading, Paragraph, Image, dan Button adalah WordPress Block Bindings API, yang menghubungkan atribut blok yang sudah ada ke nilai field ACF. Blockstudio dapat menambahkan field dan kontrol baru ke blok terdaftar mana pun melalui file ekstensi.

Buat file ekstensi di direktori blockstudio Anda:

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

Properti set secara otomatis menerapkan nilai field ke HTML blok. Gunakan wildcard untuk memperluas beberapa blok sekaligus: "name": "core/*".

Daftar periksa migrasi

  1. Buat folder blok di theme/blockstudio/{block-name}/ dengan block.json dan index.php.
  2. Pindahkan definisi field dari grup field blok (Local JSON, acf_add_local_field_group(), atau array acf.fields inline) ke array blockstudio.attributes di block.json. Ubah name menjadi id, hapus key, dan sesuaikan nama tipe bila perlu.
  3. Perbarui akses template dari get_field('name') menjadi $a['name']. Ganti loop have_rows() dengan foreach ($a['repeater'] as $item).
  4. Ganti get_sub_field() dengan akses array langsung: $item['fieldId'].
  5. Tambahkan useBlockProps ke elemen terluar di template agar integrasi editor berjalan dengan benar.
  6. Pindahkan logika kondisional dari conditional_logic milik ACF ke conditions milik Blockstudio, dengan merujuk ID field, bukan kunci field.
  7. Tambahkan penyimpanan untuk field apa pun yang sebelumnya dikueri melalui get_post_meta() atau digunakan di WP_Query.
  8. Hapus kode pendaftaran ACF: pemanggilan register_block_type() dan kunci acf untuk blok yang dimigrasikan (atau pemanggilan acf_register_block_type()), beserta grup field-nya, baik yang berada di Local JSON, acf_add_local_field_group(), array acf.fields inline, maupun admin.
  9. Uji di editor untuk memastikan field tampil dengan benar, lalu periksa keluaran frontend.