Migrácia z ACF Blocks
Ak ste vytvárali vlastné bloky WordPress pomocou ACF (Advanced Custom Fields), migrácia na Blockstudio je jednoduchá. Koncepty sú podobné: definujete polia, napíšete šablónu a blok sa zobrazí v editore. Rozdiely sú v tom, že Blockstudio samo vyhľadáva priečinky blokov, deklaruje polia vo vlastnej schéme v block.json a každej šablóne odovzdá hodnoty polí ako jedno pole $a.
Táto príručka vás krok za krokom prevedie migráciou a ponúkne porovnania vzorov ACF a Blockstudio vedľa seba.
Hlavný rozdiel
Od verzie ACF 6.0 je blok ACF objektom block.json s kľúčom acf, ktorý určuje jeho vykresľovaciu šablónu, a každý priečinok bloku sa registruje vlastným volaním register_block_type(). Polia pochádzajú zo skupiny polí priradenej k bloku pravidlom umiestnenia bloku (vytvorenej v administrácii, synchronizovanej cez Local JSON alebo registrovanej pomocou acf_add_local_field_group()), prípadne od verzie ACF PRO 6.8.1 z vloženého poľa acf.fields v tom istom block.json. Blockstudio nahrádza registračné volanie automatickým vyhľadávaním súborov: vytvorte priečinok so súborom block.json a index.php a blok sa zaregistruje automaticky.
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>
Žiadne registračné volanie ani spätné volanie vykreslenia: registráciu tvorí štruktúra priečinkov a polia sa nachádzajú v block.json vedľa šablóny. Šablóna číta $a namiesto volania get_field().
Registrácia bloku
ACF
Aktuálne bloky ACF sa registrujú z block.json s kľúčom acf (renderTemplate alebo renderCallback a možnosťami, ako je blockVersion), ktorý sa načíta explicitným volaním register_block_type() pre každý priečinok bloku, zvyčajne v súbore init v functions.php alebo v súbore pluginu. Staršie bloky môžu stále používať acf_register_block_type(), ktorý ACF od verzie ACF 6.0 dokumentuje ako zastaraný; naďalej funguje, preto tieto bloky migrujte rovnakým spôsobom.
Blockstudio
Vytvorte priečinok v adresári blockstudio/ svojej témy (alebo v blocks/, ak vám to viac vyhovuje). Pridajte súbor block.json so štandardnými metadátami bloku WordPress a kľúčom blockstudio. To je všetko.
theme/
└── blockstudio/
└── hero/
├── block.json
└── index.php
Súbor block.json používa štandardný formát WordPress block.json s kľúčom blockstudio pre polia a konfiguráciu:
{
"name": "my-theme/hero",
"title": "Hero",
"category": "theme",
"icon": "cover-image",
"description": "Full-width hero section with background image.",
"blockstudio": {
"attributes": []
}
}
Prístup k hodnotám polí
Toto je najčastejšia zmena, ktorú budete počas migrácie vykonávať.
| ACF | Blockstudio |
|---|---|
get_field('title') |
$a['title'] |
get_field('title', $post_id) |
$a['title'] (vždy dostupné) |
the_field('title') |
<?php echo $a['title']; ?> |
have_rows('items') / the_row() |
foreach ($a['items'] as $item) |
get_sub_field('name') |
$item['name'] |
Premenná $a je skráteným zápisom $attributes a obsahuje všetky hodnoty polí aktuálneho bloku. V šablóne je vždy dostupná v editore aj na frontende.
Premenné šablóny
Blockstudio poskytuje v každej šablóne niekoľko premenných:
| Premenná | Skrátený zápis | Opis |
|---|---|---|
$attributes |
$a |
Všetky hodnoty polí |
$block |
$b |
Metadáta bloku (názov, názov v administrácii, adresár, URL, ID príspevku) |
$context |
$c |
Kontext nadradeného bloku |
$content |
Obsah InnerBlocks | |
$post_id |
Aktuálne ID príspevku (funguje v editore aj na frontende; post_id alebo postId v Twig) |
Mapovanie typov polí
Väčšina typov polí ACF má priamy ekvivalent v Blockstudio. Syntax JSON sa líši, no koncepty sa dajú jednoducho mapovať.
Textové a obsahové polia
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" }
Na upraviteľný text v editore blokov (nielen textový vstup) použite typ richtext s komponentom <RichText />:
{ "id": "heading", "type": "richtext" }
<RichText attribute="heading" tag="h1" placeholder="Enter heading" />
Polia obrázkov a súborov
Polia image a file v ACF zodpovedajú typu files v 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"] }
Štruktúra vráteného objektu je podobná:
// ACF
$image = get_field('photo');
echo $image['url'];
echo $image['alt'];
// Blockstudio
echo $a['photo']['url'];
echo $a['photo']['alt'];
Dostupné vlastnosti: ID, title, alt, caption, description, href, url, sizes. Rozmery sú v sizes, napríklad $a['photo']['sizes']['full-width'].
Výber, prepínač a začiarkavacie políčko
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" }
]
}
Použite "returnFormat": "both", aby ste získali hodnotu aj označenie:
echo $a['color']['value']; // "red"
echo $a['color']['label']; // "Red"
Rovnaký vzor platí pre typy radio a checkbox.
Prepínač a pravda/nepravda
ACF:
['name' => 'show_cta', 'type' => 'true_false', 'label' => 'Show CTA']
Blockstudio:
{ "id": "showCta", "type": "toggle", "label": "Show CTA" }
Pole odkazu
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'];
Farba a prechod
ACF:
['name' => 'bgColor', 'type' => 'color_picker', 'label' => 'Background']
Blockstudio:
{ "id": "bgColor", "type": "color", "label": "Background" }
{ "id": "bgGradient", "type": "gradient", "label": "Background Gradient" }
Typ color sa integruje s paletou farieb WordPress. Typ gradient poskytuje výber farby prechodu.
Číslo, rozsah a 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" }
Opakovacie polia
Opakovacie pole v ACF sa priamo mapuje na typ repeater v Blockstudio. Šablóny ACF zvyčajne používajú cykly have_rows() / the_row() / get_sub_field() (aj get_field() pri opakovacom poli vracia pole riadkov); Blockstudio má iba obyčajné pole PHP, už vo formáte $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; ?>
Opakovacie polia Blockstudio podporujú vnáranie až do 3 úrovní.
Skupiny
Skupinové pole v ACF sa mapuje na typ group v Blockstudio. ID polí v skupinách majú ako predponu ID skupiny.
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>
Pomocná funkcia bs_get_group() odstráni predponu skupiny z ID polí a umožní k nim jednoduchý prístup. Bez nej by ste k poliam pristupovali ako k $a['author_name'] a $a['author_role'].
Podmienená logika
ACF aj Blockstudio podporujú podmienenú logiku na zobrazovanie a skrývanie polí podľa hodnôt iných polí.
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 }]]
}
Podmienky Blockstudio odkazujú priamo na ID polí (nie na kľúče polí). Dostupné operátory: ==, !=, includes, !includes, empty, !empty, <, >, <=, >=.
Blockstudio podporuje aj globálne podmienky založené na type príspevku, ID príspevku, roli používateľa a ID používateľa:
{
"conditions": [[{ "type": "postType", "operator": "==", "value": "page" }]]
}
InnerBlocks
ACF aj Blockstudio podporujú InnerBlocks na vnáranie ďalších blokov do vášho vlastného bloku. Používajú rovnakú značku <InnerBlocks /> a rovnaké atribúty allowedBlocks, template a templateLock, takže táto časť šablóny sa zvyčajne prenesie bez zmien.
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>
Značku <InnerBlocks /> v editore nahradí komponent React a na frontende vykreslený obsah bloku.
Ukladanie metaúdajov príspevku
ACF Blocks aj Blockstudio predvolene ukladajú hodnoty polí ako atribúty bloku v obsahu príspevku, nie v metadátach príspevku. To znamená, že hodnoty polí nemožno vyhľadávať pomocou WP_Query, pokiaľ nezvolíte ukladanie do meta.
ACF pridal voliteľné ukladanie do meta príspevku pre bloky v ACF PRO 6.3 prostredníctvom usePostMeta: true, a to pre jeden blok najvyššej úrovne na stránku. Blockstudio ponúka možnosť zapnúť túto funkciu pre jednotlivé polia pomocou vlastnosti storage:
{
"id": "featured",
"type": "toggle",
"label": "Featured",
"storage": {
"type": "postMeta",
"postMetaKey": "is_featured"
}
}
Kľúč meta sa automaticky zaregistruje pomocou show_in_rest. Prístup k nemu získate odkiaľkoľvek pomocou get_post_meta($post_id, 'is_featured', true).
Pre hodnoty platné pre celý web (napríklad stránky s nastaveniami ACF) použite ukladanie medzi možnosti:
{
"storage": {
"type": "option",
"optionKey": "site_company_name"
}
}
Rozšírenie existujúcich blokov
Pravidlo umiestnenia blokov v ACF pripája skupiny polí iba k blokom ACF; nepridáva polia do základných ani blokov tretích strán. V ACF slúžia na prácu so základnými blokmi, ako sú Nadpis, Odsek, Obrázok a Tlačidlo, WordPress Väzby blokov API, ktoré prepájajú existujúce atribúty blokov s hodnotami polí ACF. Blockstudio môže pomocou rozširujúcich súborov pridať nové polia a ovládacie prvky do ľubovoľného zaregistrovaného bloku.
Vytvorte rozširujúci súbor v adresári blockstudio:
{
"name": "core/heading",
"blockstudio": {
"extend": true,
"attributes": [
{
"id": "accentColor",
"type": "color",
"label": "Accent Color",
"set": [{ "attribute": "style", "value": "color: {attributes.accentColor}" }]
}
]
}
}
Vlastnosť set automaticky priradí hodnotu poľa vlastnosti bloku HTML. Pomocou zástupných znakov rozšírite viacero blokov naraz: "name": "core/*".
Kontrolný zoznam migrácie
- Vytvorte priečinok bloku v
theme/blockstudio/{block-name}/pomocoublock.jsonaindex.php. - Presuňte definície polí zo skupiny polí bloku (Local JSON,
acf_add_local_field_group()alebo vloženého poľaacf.fields) do poľablockstudio.attributesvblock.json. Zmeňtenamenaid, odstráňtekeya podľa potreby upravte názvy typov. - Aktualizujte prístup v šablóne z
get_field('name')na$a['name']. Nahraďte cyklyhave_rows()výrazomforeach ($a['repeater'] as $item). - Nahraďte
get_sub_field()priamym prístupom k poľu:$item['fieldId']. - Pridajte
useBlockPropsdo najvonkajšieho prvku v šablóne, aby sa zabezpečila správna integrácia s editorom. - Presuňte podmienenú logiku z ACF
conditional_logicdo Blockstudioconditionsa namiesto kľúčov polí používajte ich ID. - Pridajte ukladanie všetkých polí, ktoré sa predtým vyhľadávali cez
get_post_meta()alebo používali vWP_Query. - Odstráňte registračný kód ACF: volania
register_block_type()a kľúčeacfmigrovaných blokov (alebo ich volaniaacf_register_block_type()) aj ich skupiny polí bez ohľadu na to, či sa nachádzajú v Local JSON,acf_add_local_field_group(), vloženom poliacf.fieldsalebo v administrácii. - Otestujte to v editore, aby ste overili správne zobrazenie polí, a potom skontrolujte výstup na frontende.