Migrálás a ACF Blocks-ról
Ha egyéni WordPress blokkokat készítettél ACF segítségével (Advanced Custom Fields), egyszerűen átállhatsz Blockstudio-ra. A fogalmak hasonlóak: mezőket határozol meg, sablont írsz, a blokk pedig megjelenik a szerkesztőben. A különbség az, hogy az Blockstudio magától felfedezi a blokkmappákat, saját sémájában, az block.json fájlban deklarálja a mezőket, és minden sablonnak egyetlen $a tömbként adja át a mezőértékeket.
Ez az útmutató lépésről lépésre végigvezet a migráción, az ACF és az Blockstudio megoldásmintáinak egymás melletti összehasonlításával.
A lényegi különbség
Az ACF 6.0 óta egy ACF blokk olyan block.json, amelynek acf kulcsa nevezi meg a megjelenítősablonját; minden blokkmappa a saját register_block_type() hívásával kerül regisztrálásra. A mezők egy, a blokkhoz Block helyszabállyal csatolt mezőcsoportból származnak (az adminfelületen létrehozva, a Local JSON segítségével szinkronizálva, vagy acf_add_local_field_group() használatával regisztrálva), illetve az ACF PRO 6.8.1 óta ugyanabban az block.json fájlban lévő inline acf.fields tömbből is. Az Blockstudio fájlalapú automatikus felderítéssel váltja fel a regisztrációs hívást: hozz létre egy mappát block.json és index.php fájllal, és a blokk automatikusan regisztrálódik.
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>
Nincs regisztrációs hívás és nincs megjelenítési visszahívás: a mappastruktúra maga a regisztráció, a mezők pedig a sablon melletti block.json fájlban találhatók. A sablon a $a változót olvassa, ahelyett, hogy meghívná a get_field() függvényt.
Blokkregisztráció
ACF
A jelenlegi ACF blokkokat egy block.json regisztrálja, amelynek acf kulcsa van (renderTemplate vagy renderCallback, valamint például blockVersion beállításokkal). Betöltésük blokkmappánként explicit register_block_type() hívással történik, jellemzően a init fájlban, az functions.php-ben vagy egy bővítményfájlban. Régebbi blokkok továbbra is használhatják az acf_register_block_type()-t, amelyet az ACF a ACF 6.0 óta elavultként dokumentál; továbbra is működik, ezért ezeket a blokkokat ugyanígy migráld.
Blockstudio
Hozz létre egy mappát a témád blockstudio/ könyvtárában (vagy a blocks/ könyvtárban, ha azt részesíted előnyben). Adj hozzá egy block.json fájlt a szabványos WordPress blokkmetaadatokkal és egy blockstudio kulccsal. Ennyi az egész.
theme/
└── blockstudio/
└── hero/
├── block.json
└── index.php
Az block.json a szabványos WordPress block.json formátumot használja, a mezők és a konfiguráció pedig az blockstudio kulcsban adhatók meg:
{
"name": "my-theme/hero",
"title": "Hero",
"category": "theme",
"icon": "cover-image",
"description": "Full-width hero section with background image.",
"blockstudio": {
"attributes": []
}
}
Mezőértékek elérése
Ez a leggyakoribb módosítás, amelyet a migráció során el kell végezned.
| ACF | Blockstudio |
|---|---|
get_field('title') |
$a['title'] |
get_field('title', $post_id) |
$a['title'] (mindig elérhető) |
the_field('title') |
<?php echo $a['title']; ?> |
have_rows('items') / the_row() |
foreach ($a['items'] as $item) |
get_sub_field('name') |
$item['name'] |
Az $a változó az $attributes rövidítése, és az aktuális blokk összes mezőértékét tartalmazza. A sablonban mindig elérhető, a szerkesztőben és a frontendben egyaránt.
Sablonváltozók
Az Blockstudio minden sablonban több változót biztosít:
| Változó | Rövidítés | Leírás |
|---|---|---|
$attributes |
$a |
Minden mezőérték |
$block |
$b |
Blokkmetaadatok (név, cím, dir, URL, postId) |
$context |
$c |
Szülőblokk kontextusa |
$content |
InnerBlocks tartalma | |
$post_id |
Aktuális bejegyzésazonosító (a szerkesztőben és a frontendben is működik; post_id vagy postId a Twig-ben) |
Mezőtípusok leképezése
A legtöbb ACF mezőtípusnak van közvetlen megfelelője az Blockstudio-ben. A JSON szintaxisa eltér, de a fogalmak jól megfeleltethetők egymásnak.
Szöveg- és tartalommezők
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" }
A blokk szerkesztőjében szerkeszthető szöveghez (nem csupán szövegbeviteli mezőhöz) használd az richtext típust az <RichText /> komponenssel:
{ "id": "heading", "type": "richtext" }
<RichText attribute="heading" tag="h1" placeholder="Enter heading" />
Kép- és fájlmezők
Az ACF image és file mezőinek az Blockstudio files típusa felel meg:
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"] }
A visszaadott objektum felépítése hasonló:
// ACF
$image = get_field('photo');
echo $image['url'];
echo $image['alt'];
// Blockstudio
echo $a['photo']['url'];
echo $a['photo']['alt'];
Elérhető tulajdonságok: ID, title, alt, caption, description, href, url, sizes. A méretek sizes formátumúak, például $a['photo']['sizes']['full-width'].
Legördülő lista, választógomb és jelölőnégyzet
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" }
]
}
Az érték és a címke lekéréséhez használd a "returnFormat": "both"-t:
echo $a['color']['value']; // "red"
echo $a['color']['label']; // "Red"
Ugyanez a megoldásminta a radio és checkbox típusokra is érvényes.
Kapcsoló és igaz/hamis
ACF:
['name' => 'show_cta', 'type' => 'true_false', 'label' => 'Show CTA']
Blockstudio:
{ "id": "showCta", "type": "toggle", "label": "Show CTA" }
Hivatkozásmező
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'];
Szín és színátmenet
ACF:
['name' => 'bgColor', 'type' => 'color_picker', 'label' => 'Background']
Blockstudio:
{ "id": "bgColor", "type": "color", "label": "Background" }
{ "id": "bgGradient", "type": "gradient", "label": "Background Gradient" }
A color típus együttműködik az WordPress színpalettájával. A gradient típus színátmenet-választót biztosít.
Szám, tartomány és dátum
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" }
Ismétlőmezők
Az ACF ismétlőmezőjének közvetlenül az Blockstudio repeater típusa felel meg. Az ACF sablonok általában a have_rows() / the_row() / get_sub_field() segítségével járják be az adatokat (az ismétlőmezőn használt get_field() is sorok tömbjét adja vissza); az Blockstudio csak az egyszerű PHP tömböt kapja meg, már $a formátumban.
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; ?>
Az Blockstudio ismétlőmezői legfeljebb 3 szintig egymásba ágyazhatók.
Csoportok
Az ACF csoportmezőjének az Blockstudio group típusa felel meg. A csoportokon belüli mezőazonosítók előtagja a csoportazonosító.
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>
Az bs_get_group() segédfüggvény eltávolítja a csoportelőtagot a mezőazonosítókból, így közvetlenül elérheted a mezőket. Nélküle a mezőkre $a['author_name'] és $a['author_role'] néven hivatkoznál.
Feltételes logika
Az ACF és az Blockstudio egyaránt támogatja a feltételes logikát: mezőértékek alapján mezők jeleníthetők meg vagy rejthetők el.
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 }]]
}
Az Blockstudio feltételei közvetlenül a mezőazonosítókra hivatkoznak, nem a mezőkulcsokra. Elérhető operátorok: ==, !=, includes, !includes, empty, !empty, <, >, <=, >=.
Az Blockstudio globális feltételeket is támogat bejegyzéstípus, bejegyzésazonosító, felhasználói szerepkör és felhasználói azonosító alapján:
{
"conditions": [[{ "type": "postType", "operator": "==", "value": "page" }]]
}
InnerBlocks
Az ACF és az Blockstudio egyaránt támogatja az InnerBlocks használatát, így egyéni blokkjukba más blokkok ágyazhatók. Ugyanazt az <InnerBlocks /> címkét, valamint ugyanazokat az allowedBlocks, template és templateLock attribútumokat használják, ezért a sablonnak ez a része rendszerint változtatás nélkül átvihető.
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>
A szerkesztőben az <InnerBlocks /> címkét az React komponens, a frontendben pedig a megjelenített blokktartalom váltja fel.
Bejegyzésmetaadatok tárolása
Alapértelmezés szerint mind a ACF Blocks, mind a Blockstudio blokkattribútumként tárolja a mezőértékeket a bejegyzés tartalmában, nem pedig a bejegyzés metaadatai között. Ez azt jelenti, hogy a mezőértékek nem kérdezhetők le a WP_Query segítségével, hacsak nem engedélyezi a metaadatok közötti tárolást.
A ACF a ACF PRO 6.3-as verziójában bevezette a blokkok bejegyzés-metaadatai közötti, választható tárolást a usePostMeta: true segítségével, oldalanként egy legfelső szintű blokk esetén. A Blockstudio mezőnként kínál választható megoldást a storage tulajdonság használatával:
{
"id": "featured",
"type": "toggle",
"label": "Featured",
"storage": {
"type": "postMeta",
"postMetaKey": "is_featured"
}
}
A metakulcs automatikusan regisztrálódik a show_in_rest segítségével. Bárhonnan elérheti a get_post_meta($post_id, 'is_featured', true) használatával.
Az egész webhelyre érvényes értékekhez (például ACF beállítási oldalakhoz) használja az opciótárolást:
{
"storage": {
"type": "option",
"optionKey": "site_company_name"
}
}
Meglévő blokkok bővítése
A ACF blokkhely-szabálya csak a ACF blokkokhoz kapcsol mezőcsoportokat; a core- vagy harmadik féltől származó blokkokhoz nem ad mezőket. A core-blokkok, például a Címsor, Bekezdés, Kép és Gomb bővítésére a ACF szolgál: a WordPress Block Bindings API meglévő blokkattribútumokat kapcsol a ACF mezőértékekhez. A Blockstudio bővítményfájlokkal bármely regisztrált blokkhoz adhat új mezőket és vezérlőket.
Hozzon létre egy bővítményfájlt a blockstudio könyvtárában:
{
"name": "core/heading",
"blockstudio": {
"extend": true,
"attributes": [
{
"id": "accentColor",
"type": "color",
"label": "Accent Color",
"set": [{ "attribute": "style", "value": "color: {attributes.accentColor}" }]
}
]
}
}
A set tulajdonság automatikusan alkalmazza a mező értékét a blokk HTML elemére. Helyettesítő karakterekkel egyszerre több blokkot is bővíthet: "name": "core/*".
Migrálási ellenőrzőlista
- Hozza létre a blokk mappáját a
theme/blockstudio/{block-name}/alatt ablock.jsonés aindex.phphasználatával. - Helyezze át a meződefiníciókat a blokk mezőcsoportjából (Local JSON,
acf_add_local_field_group()vagy beágyazottacf.fieldstömb) ablock.jsonfájlban lévőblockstudio.attributestömbbe. Módosítsa anameértékétidértékre, távolítsa el akeyelemet, és szükség szerint igazítsa a típusneveket. - Frissítse a sablonelérést
get_field('name')értékről$a['name']értékre. Cserélje le ahave_rows()ciklusokatforeach ($a['repeater'] as $item)ciklusokra. - Cserélje le a
get_sub_field()elemet közvetlen tömbelérésre:$item['fieldId']. - Adja hozzá a
useBlockPropselemet a sablon legkülső eleméhez a megfelelő szerkesztőintegráció érdekében. - Helyezze át a feltételes logikát a ACF
conditional_logiceleméből a Blockstudioconditionselemébe, és mezőkulcsok helyett mezőazonosítókra hivatkozzon. - Adjon meg tárolást minden olyan mezőhöz, amelyre korábban a
get_post_meta()segítségével kérdeztek le, vagy amelyet aWP_Queryhasznált. - Távolítsa el a ACF regisztrációs kódját: a migrált blokkok
register_block_type()hívásait ésacfkulcsait (vagyacf_register_block_type()hívásait), valamint a mezőcsoportjaikat, akár a Local JSON, aacf_add_local_field_group(), egy beágyazottacf.fieldstömb vagy az adminisztrációs felület tartalmazza őket. - Tesztelje a szerkesztőben, hogy a mezők megfelelően jelennek-e meg, majd ellenőrizze a webhely előoldalán megjelenő kimenetet.