ACF Blocksからの移行
ACF(Advanced Custom Fields)でカスタムWordPressブロックを作成している場合、Blockstudioへの移行は簡単です。基本的な考え方は似ています。フィールドを定義し、テンプレートを書けば、ブロックがエディターに表示されます。違いは、Blockstudioがブロックのフォルダーを自動で検出すること、独自のスキーマでblock.json内にフィールドを宣言すること、そして各テンプレートにフィールド値を1つの$a配列として渡すことです。
このガイドでは、ACFとBlockstudioのパターンを対比しながら、移行手順を順を追って説明します。
主な違い
ACF 6.0以降では、ACFブロックはacfキーでレンダリングテンプレートを指定するblock.jsonであり、各ブロックフォルダーは独自のregister_block_type()呼び出しで登録されます。フィールドは、Blockロケーションルールでブロックに紐付けたフィールドグループ(管理画面で作成し、Local JSONで同期するか、acf_add_local_field_group()で登録)、またはACF PRO 6.8.1以降では同じblock.json内のインラインacf.fields配列から取得します。Blockstudioでは登録呼び出しの代わりにファイルベースの自動検出を使います。block.jsonとindex.phpを含むフォルダーを作成すると、ブロックが自動的に登録されます。
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>
登録呼び出しもレンダリングコールバックも不要です。フォルダー構成が登録となり、フィールドはテンプレートの隣にあるblock.jsonに記述します。テンプレートではget_field()を呼び出す代わりに$aを読み取ります。
ブロックの登録
ACF
現在のACFブロックは、acfキー(renderTemplateまたはrenderCallback、およびblockVersionなどのオプション)を含むblock.jsonから登録されます。通常、各ブロックフォルダーで明示的にregister_block_type()を呼び出し、functions.php内のinitやプラグインファイルで読み込みます。古いブロックではacf_register_block_type()を使っている場合があります。ACFはこれをACF 6.0以降で非推奨としていますが、引き続き動作するため、同じ方法で移行できます。
Blockstudio
テーマのblockstudio/ディレクトリ(または任意でblocks/)にフォルダーを作成します。標準のWordPressブロックメタデータとblockstudioキーを含むblock.jsonを追加します。これで完了です。
theme/
└── blockstudio/
└── hero/
├── block.json
└── index.php
block.jsonでは、フィールドと設定にblockstudioキーを使う標準のWordPress block.json形式を使用します。
{
"name": "my-theme/hero",
"title": "Hero",
"category": "theme",
"icon": "cover-image",
"description": "Full-width hero section with background image.",
"blockstudio": {
"attributes": []
}
}
フィールド値へのアクセス
移行時に最もよく行う変更です。
| ACF | Blockstudio |
|---|---|
get_field('title') |
$a['title'] |
get_field('title', $post_id) |
$a['title'](常に利用可能) |
the_field('title') |
<?php echo $a['title']; ?> |
have_rows('items') / the_row() |
foreach ($a['items'] as $item) |
get_sub_field('name') |
$item['name'] |
$a変数は$attributesの略記で、現在のブロックのすべてのフィールド値が含まれています。エディターでもフロントエンドでも、常にテンプレートで利用できます。
テンプレート変数
Blockstudioはすべてのテンプレートで次の変数を提供します。
| 変数 | 略記 | 説明 |
|---|---|---|
$attributes |
$a |
すべてのフィールド値 |
$block |
$b |
ブロックのメタデータ(name、title、dir、url、postId) |
$context |
$c |
親ブロックのコンテキスト |
$content |
InnerBlocksコンテンツ | |
$post_id |
現在の投稿ID(エディターとフロントエンドで動作。Twigではpost_idまたはpostId) |
フィールドタイプの対応付け
ほとんどのACFフィールドタイプには、Blockstudioで直接対応するものがあります。JSONの構文は異なりますが、概念は簡単に対応付けられます。
テキストとコンテンツのフィールド
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" }
単なるテキスト入力ではなく、ブロックエディターで編集できるテキストには、<RichText />コンポーネントとrichtextタイプを使います。
{ "id": "heading", "type": "richtext" }
<RichText attribute="heading" tag="h1" placeholder="Enter heading" />
画像とファイルのフィールド
ACFのimageフィールドとfileフィールドは、Blockstudioのfilesタイプに対応します。
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"] }
返されるオブジェクトの構造も似ています。
// ACF
$image = get_field('photo');
echo $image['url'];
echo $image['alt'];
// Blockstudio
echo $a['photo']['url'];
echo $a['photo']['alt'];
利用可能なプロパティ: ID、title、alt、caption、description、href、url、sizes。寸法はsizesにあり、たとえば$a['photo']['sizes']['full-width']のように指定します。
セレクト、ラジオ、チェックボックス
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" }
]
}
値とラベルの両方を取得するには、"returnFormat": "both"を使います。
echo $a['color']['value']; // "red"
echo $a['color']['label']; // "Red"
radioタイプとcheckboxタイプにも同じパターンを適用できます。
トグルと真偽値
ACF:
['name' => 'show_cta', 'type' => 'true_false', 'label' => 'Show CTA']
Blockstudio:
{ "id": "showCta", "type": "toggle", "label": "Show CTA" }
リンクフィールド
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'];
色とグラデーション
ACF:
['name' => 'bgColor', 'type' => 'color_picker', 'label' => 'Background']
Blockstudio:
{ "id": "bgColor", "type": "color", "label": "Background" }
{ "id": "bgGradient", "type": "gradient", "label": "Background Gradient" }
colorタイプはWordPressのカラーパレットと連携します。gradientタイプではグラデーションピッカーを利用できます。
数値、範囲、日付
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" }
リピーター
ACFのリピーターフィールドは、Blockstudioのrepeaterタイプに直接対応します。ACFテンプレートでは通常、have_rows() / the_row() / get_sub_field()でループします(リピーターでのget_field()も行の配列を返します)。Blockstudioで得られるのは通常のPHP配列だけで、すでに$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; ?>
Blockstudioのリピーターは、最大3階層までネスト(リピーター内にリピーターを配置)できます。
グループ
ACFのグループフィールドは、Blockstudioのgroupタイプに対応します。グループ内のフィールドIDには、グループIDが接頭辞として付きます。
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>
bs_get_group()ヘルパーはフィールドIDからグループの接頭辞を取り除き、簡潔にアクセスできるようにします。これを使わない場合は、$a['author_name']や$a['author_role']のようにフィールドへアクセスします。
条件付きロジック
ACFとBlockstudioはどちらも、ほかのフィールド値に基づいてフィールドの表示・非表示を切り替える条件付きロジックに対応しています。
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 }]]
}
Blockstudioの条件ではフィールドキーではなくフィールドIDを直接指定します。利用可能な演算子: ==、!=、includes、!includes、empty、!empty、<、>、<=、>=。
Blockstudioは、投稿タイプ、投稿ID、ユーザーロール、ユーザーIDに基づくグローバル条件にも対応しています。
{
"conditions": [[{ "type": "postType", "operator": "==", "value": "page" }]]
}
InnerBlocks
ACFとBlockstudioはどちらも、カスタムブロック内にほかのブロックをネストするInnerBlocksに対応しています。同じ<InnerBlocks />タグとallowedBlocks、template、templateLock属性を使うため、テンプレートのこの部分は通常そのまま移行できます。
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>
エディターでは<InnerBlocks />タグがReactコンポーネントに置き換わり、フロントエンドではレンダリング済みのブロックコンテンツに置き換わります。
投稿メタへの保存
ACF BlocksとBlockstudioはどちらも、標準ではフィールド値を投稿メタではなく投稿コンテンツ内のブロック属性として保存します。そのため、メタ保存を有効にしない限り、WP_Queryではフィールド値を検索できません。
ACFでは、ACF PRO 6.3からusePostMeta: trueによりブロックの投稿メタ保存を任意で有効にできます。ただし、1ページにつき最上位ブロック1つが対象です。Blockstudioでは、storageプロパティを使ってフィールドごとに有効化できます。
{
"id": "featured",
"type": "toggle",
"label": "Featured",
"storage": {
"type": "postMeta",
"postMetaKey": "is_featured"
}
}
メタキーはshow_in_restに自動登録されます。get_post_meta($post_id, 'is_featured', true)を使うと、どこからでもアクセスできます。
サイト全体で使う値(ACFのオプションページなど)には、オプション保存を使います。
{
"storage": {
"type": "option",
"optionKey": "site_company_name"
}
}
既存ブロックの拡張
ACFのブロック位置ルールは、フィールドグループをACFブロックにのみ割り当てます。コアブロックやサードパーティ製ブロックにフィールドを追加するものではありません。見出し、段落、画像、ボタンなどのコアブロックにフィールドを追加するには、ACFのWordPressブロックバインディングAPIを使い、既存のブロック属性をACFのフィールド値に接続します。Blockstudioでは、拡張ファイルを使って登録済みの任意のブロックに新しいフィールドやコントロールを追加できます。
blockstudioディレクトリに拡張ファイルを作成します。
{
"name": "core/heading",
"blockstudio": {
"extend": true,
"attributes": [
{
"id": "accentColor",
"type": "color",
"label": "Accent Color",
"set": [{ "attribute": "style", "value": "color: {attributes.accentColor}" }]
}
]
}
}
setプロパティによって、フィールド値がブロックのHTMLに自動適用されます。ワイルドカードを使うと複数のブロックを一度に拡張できます: "name": "core/*"。
移行チェックリスト
- ブロックフォルダーを作成する:
theme/blockstudio/{block-name}/内に、block.jsonとindex.phpを配置します。 - フィールド定義を移す: ブロックのフィールドグループ(Local JSON、
acf_add_local_field_group()、またはインラインのacf.fields配列)から、block.json内のblockstudio.attributes配列へ移します。nameをidに変更し、keyを削除して、必要に応じてタイプ名を調整します。 - テンプレートでのアクセスを更新する:
get_field('name')から$a['name']に変更します。have_rows()のループをforeach ($a['repeater'] as $item)に置き換えます。 get_sub_field()を置き換える: 配列に直接アクセスします:$item['fieldId']。useBlockPropsを追加する: エディターとの連携に必要なため、テンプレートの最上位要素に追加します。- 条件付きロジックを移す: ACFの
conditional_logicからBlockstudioのconditionsに移し、フィールドキーではなくフィールドIDを指定します。 - 保存方法を追加する: 以前
get_post_meta()で検索していたフィールドや、WP_Queryで使っていたフィールドに保存を設定します。 - ACFの登録コードを削除する: 移行したブロックの
register_block_type()呼び出しとacfキー(またはacf_register_block_type()呼び出し)を削除し、Local JSON、acf_add_local_field_group()、インラインのacf.fields配列、または管理画面で管理していたフィールドグループも削除します。 - エディターでテストする: フィールドが正しく表示されることを確認し、続けてフロントエンドの出力も確認します。