Selitev z ACF Blocks
Če ste izdelovali bloke WordPress po meri z ACF (Advanced Custom Fields), je selitev na Blockstudio preprosta. Koncepti so podobni: določite polja, napišete predlogo in blok se prikaže v urejevalniku. Razlike so v tem, da Blockstudio sam poišče mape blokov, polja določi v lastni shemi znotraj block.json, vsaki predlogi pa preda vrednosti polj kot eno polje $a.
Ta vodnik korak za korakom predstavi selitev s primerjavami vzorcev za ACF in Blockstudio drugo ob drugem.
Ključna razlika
Od ACF 6.0 je blok ACF objekt block.json s ključem acf, ki določa predlogo za izris, vsaka mapa bloka pa se registrira z lastnim klicem register_block_type(). Polja izvirajo iz skupine polj, povezane z blokom s pravilom lokacije Block (ustvarjene v skrbništvu, sinhronizirane prek Local JSON ali registrirane z acf_add_local_field_group()), ali pa od različice ACF PRO 6.8.1 iz polja acf.fields znotraj istega block.json. Blockstudio registracijo nadomesti s samodejnim iskanjem na podlagi datotek: ustvarite mapo z datotekama block.json in index.php, blok pa se registrira samodejno.
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>
Registracijski klic in povratni klic za izris nista potrebna: registracijo določa struktura map, polja pa so v block.json poleg predloge. Predloga bere $a, namesto da bi klicala get_field().
Registracija blokov
ACF
Trenutni bloki ACF se registrirajo iz block.json s ključem acf (renderTemplate ali renderCallback ter možnostmi, kot je blockVersion), naložijo pa se z izrecnim klicem register_block_type() za vsako mapo bloka, običajno na init v functions.php ali v datoteki vtičnika. Starejši bloki morda še uporabljajo acf_register_block_type(), ki ga je ACF od različice ACF 6.0 dokumentiral kot zastarelega; še vedno deluje, zato takšne bloke preselite na enak način.
Blockstudio
Ustvarite mapo v imeniku blockstudio/ svoje teme (ali blocks/, če vam to bolj ustreza). Dodajte block.json s standardnimi metapodatki bloka WordPress in ključem blockstudio. To je vse.
theme/
└── blockstudio/
└── hero/
├── block.json
└── index.php
block.json uporablja standardno obliko WordPress block.json, pri čemer je ključ blockstudio namenjen poljem in konfiguraciji:
{
"name": "my-theme/hero",
"title": "Hero",
"category": "theme",
"icon": "cover-image",
"description": "Full-width hero section with background image.",
"blockstudio": {
"attributes": []
}
}
Dostop do vrednosti polj
To je najpogostejša sprememba, ki jo boste izvedli med selitvijo.
| ACF | Blockstudio |
|---|---|
get_field('title') |
$a['title'] |
get_field('title', $post_id) |
$a['title'] (vedno na voljo) |
the_field('title') |
<?php echo $a['title']; ?> |
have_rows('items') / the_row() |
foreach ($a['items'] as $item) |
get_sub_field('name') |
$item['name'] |
Spremenljivka $a je okrajšava za $attributes in vsebuje vse vrednosti polj za trenutni blok. V predlogi je vedno na voljo, tako v urejevalniku kot na frontendu.
Spremenljivke predloge
Blockstudio v vsaki predlogi omogoča več spremenljivk:
| Spremenljivka | Okrajšava | Opis |
|---|---|---|
$attributes |
$a |
Vse vrednosti polj |
$block |
$b |
Metapodatki bloka (name, title, dir, url, postId) |
$context |
$c |
Kontekst nadrejenega bloka |
$content |
Vsebina InnerBlocks | |
$post_id |
ID trenutne objave (deluje v urejevalniku in na frontendu; post_id ali postId v Twig) |
Preslikava vrst polj
Večina vrst polj ACF ima neposredno ustreznico v Blockstudio. Sintaksa JSON je drugačna, vendar se koncepti dobro ujemajo.
Polja z besedilom in vsebino
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" }
Za besedilo, ki ga je mogoče urejati v urejevalniku blokov (ne zgolj za vnosno polje), uporabite vrsto richtext s komponento <RichText />:
{ "id": "heading", "type": "richtext" }
<RichText attribute="heading" tag="h1" placeholder="Enter heading" />
Polja za slike in datoteke
Polji image in file za ACF ustrezata vrsti files za 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"] }
Struktura vrnjenega objekta je podobna:
// ACF
$image = get_field('photo');
echo $image['url'];
echo $image['alt'];
// Blockstudio
echo $a['photo']['url'];
echo $a['photo']['alt'];
Razpoložljive lastnosti: ID, title, alt, caption, description, href, url, sizes. Dimenzije so v sizes, na primer $a['photo']['sizes']['full-width'].
Izbirno polje, izbirni gumbi in potrditveno polje
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" }
]
}
Za pridobitev vrednosti in oznake uporabite "returnFormat": "both":
echo $a['color']['value']; // "red"
echo $a['color']['label']; // "Red"
Enak vzorec velja za vrsti radio in checkbox.
Preklop in vrednosti true/false
ACF:
['name' => 'show_cta', 'type' => 'true_false', 'label' => 'Show CTA']
Blockstudio:
{ "id": "showCta", "type": "toggle", "label": "Show CTA" }
Polje povezave
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'];
Barva in preliv
ACF:
['name' => 'bgColor', 'type' => 'color_picker', 'label' => 'Background']
Blockstudio:
{ "id": "bgColor", "type": "color", "label": "Background" }
{ "id": "bgGradient", "type": "gradient", "label": "Background Gradient" }
Vrsta color se poveže z barvno paleto WordPress. Vrsta gradient omogoča izbirnik prelivov.
Število, obseg in datum
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" }
Ponavljajoča se polja
Ponavljajoče se polje ACF se neposredno preslika v vrsto repeater za Blockstudio. Predloge ACF običajno uporabljajo zanke z have_rows() / the_row() / get_sub_field() (get_field() pri ponavljajočem se polju vrne tudi polje vrstic); Blockstudio ima samo navadno polje PHP, že v $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; ?>
Ponavljajoča se polja Blockstudio podpirajo gnezdenje do 3 ravni.
Skupine
Skupinsko polje ACF se preslika v vrsto group za Blockstudio. ID-ji polj v skupinah imajo kot predpono ID skupine.
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>
Pomožna funkcija bs_get_group() odstrani predpono skupine iz ID-jev polj, da omogoči preprost dostop. Brez nje bi do polj dostopali kot do $a['author_name'] in $a['author_role'].
Pogojna logika
Tako ACF kot Blockstudio podpirata pogojno logiko za prikaz in skrivanje polj glede na vrednosti drugih polj.
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 }]]
}
Pogoji Blockstudio se sklicujejo neposredno na ID-je polj (ne na ključe polj). Razpoložljivi operatorji: ==, !=, includes, !includes, empty, !empty, <, >, <=, >=.
Blockstudio podpira tudi globalne pogoje glede na vrsto objave, ID objave, uporabniško vlogo in ID uporabnika:
{
"conditions": [[{ "type": "postType", "operator": "==", "value": "page" }]]
}
InnerBlocks
Tako ACF kot Blockstudio podpirata InnerBlocks za gnezdenje drugih blokov v bloku po meri, z isto oznako <InnerBlocks /> in istimi atributi allowedBlocks, template in templateLock, zato se ta del predloge običajno prenese brez sprememb.
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>
Oznako <InnerBlocks /> v urejevalniku nadomesti komponenta React, na frontendu pa izrisana vsebina bloka.
Shranjevanje metapodatkov objave
Tako ACF Blocks kot Blockstudio privzeto shranjujeta vrednosti polj kot atribute blokov v vsebini objave, ne v metapodatkih objave. To pomeni, da vrednosti polj niso dostopne za poizvedbe z WP_Query, razen če izberete shranjevanje v metapodatke.
ACF je v ACF PRO 6.3 dodal izbirno shranjevanje blokov v metapodatke objave prek usePostMeta: true, za en blok najvišje ravni na stran. Blockstudio omogoča izbirno shranjevanje za posamezno polje z uporabo lastnosti storage:
{
"id": "featured",
"type": "toggle",
"label": "Featured",
"storage": {
"type": "postMeta",
"postMetaKey": "is_featured"
}
}
Ključ metapodatkov se samodejno registrira z show_in_rest. Do njega dostopajte kjer koli z get_post_meta($post_id, 'is_featured', true).
Za vrednosti, ki veljajo za celotno spletno mesto (na primer za strani z možnostmi ACF), uporabite shranjevanje možnosti:
{
"storage": {
"type": "option",
"optionKey": "site_company_name"
}
}
Razširjanje obstoječih blokov
Pravilo za lokacijo bloka v ACF pripne skupine polj samo blokom ACF; polj ne dodaja osnovnim blokom ali blokom drugih ponudnikov. Za dodajanje polj osnovnim blokom, kot so Heading, Paragraph, Image in Button, ACF ponuja WordPress Block Bindings API, ki obstoječe atribute blokov poveže z vrednostmi polj ACF. Blockstudio lahko kateremu koli registriranemu bloku doda nova polja in kontrolnike prek razširitvenih datotek.
V imeniku blockstudio ustvarite razširitveno datoteko:
{
"name": "core/heading",
"blockstudio": {
"extend": true,
"attributes": [
{
"id": "accentColor",
"type": "color",
"label": "Accent Color",
"set": [{ "attribute": "style", "value": "color: {attributes.accentColor}" }]
}
]
}
}
Lastnost set samodejno uporabi vrednost polja za HTML bloka. Za razširitev več blokov hkrati uporabite nadomestne znake: "name": "core/*".
Kontrolni seznam za selitev
- Ustvarite mapo bloka v
theme/blockstudio/{block-name}/zblock.jsoninindex.php. - Premaknite definicije polj iz skupine polj bloka (Local JSON,
acf_add_local_field_group()ali vdelane matrikeacf.fields) v matrikoblockstudio.attributesvblock.json. Spremenitenamevid, odstranitekeyin po potrebi prilagodite imena vrst. - Posodobite dostop v predlogi iz
get_field('name')v$a['name']. Zankehave_rows()zamenjajte zforeach ($a['repeater'] as $item). - Zamenjajte
get_sub_field()z neposrednim dostopom do matrike:$item['fieldId']. - Dodajte
useBlockPropszunanjemu elementu v predlogi, da zagotovite pravilno integracijo z urejevalnikom. - Premaknite pogojno logiko iz ACF’s
conditional_logicv Blockstudio’sconditions, pri tem pa uporabite ID-je polj namesto ključev polj. - Dodajte shranjevanje za vsa polja, po katerih ste prej poizvedovali prek
get_post_meta()ali jih uporabljali vWP_Query. - Odstranite registracijsko kodo ACF: klice
register_block_type()in ključeacfpreseljenih blokov (ali njihove kliceacf_register_block_type()) ter njihove skupine polj, ne glede na to, ali so v Local JSON,acf_add_local_field_group(), vdelani matrikiacf.fieldsali skrbniškem vmesniku. - Preizkusite v urejevalniku, ali so polja prikazana pravilno, nato preverite izpis na spletnem mestu.