Preskoči na vsebino

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:

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>

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.

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

block.json uporablja standardno obliko WordPress block.json, pri čemer je ključ blockstudio namenjen poljem in konfiguraciji:

JSON
{
  "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:

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

Za besedilo, ki ga je mogoče urejati v urejevalniku blokov (ne zgolj za vnosno polje), uporabite vrsto richtext s komponento <RichText />:

JSON
{ "id": "heading", "type": "richtext" }
PHP
<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:

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

Struktura vrnjenega objekta je podobna:

PHP
// 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:

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

Za pridobitev vrednosti in oznake uporabite "returnFormat": "both":

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

Enak vzorec velja za vrsti radio in checkbox.

Preklop in vrednosti 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'];

Barva in preliv

ACF:

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

Blockstudio:

JSON
{ "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:

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

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:

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; ?>

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:

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>

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:

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

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:

JSON
{
  "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:

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>

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:

JSON
{
  "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:

JSON
{
  "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:

JSON
{
  "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

  1. Ustvarite mapo bloka v theme/blockstudio/{block-name}/ z block.json in index.php.
  2. Premaknite definicije polj iz skupine polj bloka (Local JSON, acf_add_local_field_group() ali vdelane matrike acf.fields) v matriko blockstudio.attributes v block.json. Spremenite name v id, odstranite key in po potrebi prilagodite imena vrst.
  3. Posodobite dostop v predlogi iz get_field('name') v $a['name']. Zanke have_rows() zamenjajte z foreach ($a['repeater'] as $item).
  4. Zamenjajte get_sub_field() z neposrednim dostopom do matrike: $item['fieldId'].
  5. Dodajte useBlockProps zunanjemu elementu v predlogi, da zagotovite pravilno integracijo z urejevalnikom.
  6. Premaknite pogojno logiko iz ACF’s conditional_logic v Blockstudio’s conditions, pri tem pa uporabite ID-je polj namesto ključev polj.
  7. Dodajte shranjevanje za vsa polja, po katerih ste prej poizvedovali prek get_post_meta() ali jih uporabljali v WP_Query.
  8. Odstranite registracijsko kodo ACF: klice register_block_type() in ključe acf preseljenih blokov (ali njihove klice acf_register_block_type()) ter njihove skupine polj, ne glede na to, ali so v Local JSON, acf_add_local_field_group(), vdelani matriki acf.fields ali skrbniškem vmesniku.
  9. Preizkusite v urejevalniku, ali so polja prikazana pravilno, nato preverite izpis na spletnem mestu.