Liigu sisu juurde

Üleminek versioonilt ACF Blocks

Kui olete loonud kohandatud WordPress plokke ACF abil (Advanced Custom Fields), on versioonile Blockstudio üleminek lihtne. Põhimõtted on sarnased: määrate väljad, kirjutate malli ja plokk ilmub redaktorisse. Erinevus seisneb selles, et Blockstudio leiab plokikaustad ise üles, deklareerib väljad oma skeemis failis block.json ja annab mallile kõik välja väärtused ühe $a massiivina.

See juhend käsitleb üleminekut sammhaaval ning võrdleb kõrvuti ACF ja Blockstudio mustreid.

Peamine erinevus

Alates versioonist ACF 6.0 on ACF plokk block.json, millel on renderdusmalli nimetav võti acf. Iga plokikaust registreeritakse eraldi väljakutsega register_block_type(). Väljad pärinevad plokile Blocki asukohareegliga seotud väljarühmast (mis luuakse halduses, sünkroonitakse Local JSON-i kaudu või registreeritakse käsuga acf_add_local_field_group()) või alates versioonist ACF PRO 6.8.1 samas block.json-is olevast tekstisisesest massiivist acf.fields. Blockstudio asendab registreerimisväljakutse failipõhise automaattuvastusega: looge kaust, kus on block.json ja index.php, ning plokk registreeritakse automaatselt.

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>

Registreerimisväljakutset ega renderdamise tagasihelistust pole vaja: kaustastruktuur määrab registreerimise ning väljad asuvad malliga samas kohas failis block.json. Mall loeb väärtuse $a, selle asemel et kutsuda välja get_field().

Ploki registreerimine

ACF

Praegused ACF plokid registreeritakse block.json-ist, millel on võti acf (renderTemplate või renderCallback koos suvanditega, näiteks blockVersion). Need laaditakse iga plokikausta kohta eraldi, tavaliselt register_block_type()-i väljakutsega failis functions.php asuvale init-ile või pluginafaili. Vanemad plokid võivad endiselt kasutada acf_register_block_type()-i, mille ACF tunnistas alates versioonist ACF 6.0 iganenuks. See töötab edasi, seega viige need plokid üle samal viisil.

Blockstudio

Looge kaust oma teema blockstudio/-kataloogi (või soovi korral blocks/-i). Lisage sinna block.json, milles on standardsed WordPress-ploki metaandmed ja võti blockstudio. Valmis.

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

block.json kasutab standardset WordPress block.json-vormingut, kus väljad ja konfiguratsioon määratakse võtmega blockstudio:

JSON
{
  "name": "my-theme/hero",
  "title": "Hero",
  "category": "theme",
  "icon": "cover-image",
  "description": "Full-width hero section with background image.",
  "blockstudio": {
    "attributes": []
  }
}

Väljade väärtustele juurdepääs

See on kõige tavalisem muudatus, mille peate üleminekul tegema.

ACF Blockstudio
get_field('title') $a['title']
get_field('title', $post_id) $a['title'] (alati saadaval)
the_field('title') <?php echo $a['title']; ?>
have_rows('items') / the_row() foreach ($a['items'] as $item)
get_sub_field('name') $item['name']

Muutuja $a on lühivorm väärtusele $attributes ja sisaldab praeguse ploki kõigi väljade väärtusi. See on mallis alati saadaval nii redaktoris kui ka kasutajaliideses.

Mallimuutujad

Blockstudio pakub igas mallis mitut muutujat:

Muutuja Lühivorm Kirjeldus
$attributes $a Kõigi väljade väärtused
$block $b Ploki metaandmed (name, title, dir, url, postId)
$context $c Ülemploki kontekst
$content InnerBlocksi sisu
$post_id Praeguse postituse ID (toimib redaktoris ja kasutajaliideses; post_id või postId asukohas Twig)

Väljatüüpide vastendamine

Enamikul ACF väljatüüpidel on Blockstudio-is otsene vaste. Süntaks JSON on erinev, kuid mõisted sobituvad hästi.

Teksti- ja sisuväljad

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

Plokiredaktoris muudetava teksti jaoks (mitte ainult tekstisisestusvälja jaoks) kasutage tüüpi richtext koos komponendiga <RichText />:

JSON
{ "id": "heading", "type": "richtext" }
PHP
<RichText attribute="heading" tag="h1" placeholder="Enter heading" />

Pildi- ja failiväljad

ACF väljad image ja file vastavad Blockstudio tüübile files:

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

Tagastatud objekti struktuur on sarnane:

PHP
// ACF
$image = get_field('photo');
echo $image['url'];
echo $image['alt'];

// Blockstudio
echo $a['photo']['url'];
echo $a['photo']['alt'];

Saadaolevad omadused: ID, title, alt, caption, description, href, url, sizes. Mõõtmed on üksuses sizes, näiteks $a['photo']['sizes']['full-width'].

Valik, raadionupp ja märkeruut

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

Kasutage "returnFormat": "both"-i, et saada nii väärtus kui ka silt:

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

Sama muster kehtib ka tüüpide radio ja checkbox puhul.

Lüliti ja tõeväärtus

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'];

Värv ja gradient

ACF:

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

Blockstudio:

JSON
{ "id": "bgColor", "type": "color", "label": "Background" }
{ "id": "bgGradient", "type": "gradient", "label": "Background Gradient" }

Tüüp color ühildub värvipaletiga WordPress. Tüüp gradient pakub gradiendi valijat.

Arv, vahemik ja kuupäev

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

Kordusväljad

ACF kordusväli vastab otse Blockstudio tüübile repeater. ACF mallid läbivad tavaliselt ridu käsuga have_rows() / the_row() / get_sub_field() (kordusvälja get_field() tagastab samuti ridade massiivi); Blockstudio-is on ainult lihtne PHP-massiiv, mis on juba kujul $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; ?>

Blockstudio kordusväljad toetavad pesastamist kuni 3 tasemeni (kordusväli kordusvälja sees).

Rühmad

ACF rühmaväli vastab Blockstudio tüübile group. Rühma sees olevate väljade ID-dele lisatakse eesliiteks rühma ID.

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>

Abifunktsioon bs_get_group() eemaldab väljade ID-dest rühma eesliite, nii et neile pääseb puhtalt ligi. Ilma selleta pääseksite väljadele juurde kujul $a['author_name'] ja $a['author_role'].

Tingimusloogika

Nii ACF kui ka Blockstudio toetavad tingimusloogikat, millega välju teiste väljade väärtuste põhjal kuvada või peita.

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

Blockstudio tingimused viitavad otse välja ID-dele, mitte võtmetele. Saadaolevad tehtemärgid: ==, !=, includes, !includes, empty, !empty, <, >, <=, >=.

Blockstudio toetab ka üldtingimusi, mis põhinevad postituse tüübil, postituse ID-l, kasutaja rollil ja kasutaja ID-l:

JSON
{
  "conditions": [[{ "type": "postType", "operator": "==", "value": "page" }]]
}

InnerBlocks

Nii ACF kui ka Blockstudio toetavad InnerBlocksi, et paigutada kohandatud ploki sisse teisi plokke, kasutades sama <InnerBlocks /> silti ja samu atribuute allowedBlocks, template ning templateLock. Seetõttu saab selle malliosa tavaliselt muutmata üle võtta.

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>

Redaktoris asendab sildi <InnerBlocks /> komponent React; kasutajaliideses asendab selle renderdatud plokisisu.

Postituse metaandmete salvestamine

Nii ACF Blocks kui ka Blockstudio salvestavad välja väärtused vaikimisi postituse sisus ploki atribuutidena, mitte postituse metaandmetes. Seetõttu ei saa välja väärtusi pärida WP_Query abil, kui te ei luba metaandmetesse salvestamist.

ACF lisas plokkide postituse metaandmetesse salvestamise lubamise võimaluse ACF PRO versioonis 6.3 usePostMeta: true kaudu, ühe lehe ülataseme ploki jaoks. Blockstudio võimaldab seda iga välja puhul eraldi, kasutades atribuuti storage:

JSON
{
  "id": "featured",
  "type": "toggle",
  "label": "Featured",
  "storage": {
    "type": "postMeta",
    "postMetaKey": "is_featured"
  }
}

Metaandmete võti registreeritakse automaatselt show_in_rest abil. Pääsete sellele kõikjal ligi get_post_meta($post_id, 'is_featured', true) kaudu.

Kogu saidi väärtuste (näiteks ACF valikute lehtede) jaoks kasutage valikute salvestusruumi:

JSON
{
  "storage": {
    "type": "option",
    "optionKey": "site_company_name"
  }
}

Olemasolevate plokkide laiendamine

ACF ploki asukohareegel seostab väljarühmad ainult ACF plokkidega; see ei lisa välju tuumiku ega kolmanda osapoole plokkidele. Tuumiku plokkidele, näiteks pealkirjale, lõigule, pildile ja nupule, väljade lisamiseks kasutab ACF WordPress Block Bindings funktsiooni API, mis ühendab olemasolevad ploki atribuudid ACF välja väärtustega. Blockstudio saab laiendusfailide kaudu lisada uusi välju ja juhtelemente igale registreeritud plokile.

Looge laiendusfail oma blockstudio kataloogis:

JSON
{
  "name": "core/heading",
  "blockstudio": {
    "extend": true,
    "attributes": [
      {
        "id": "accentColor",
        "type": "color",
        "label": "Accent Color",
        "set": [{ "attribute": "style", "value": "color: {attributes.accentColor}" }]
      }
    ]
  }
}

Atribuut set rakendab välja väärtuse automaatselt ploki HTML-ile. Mitme ploki korraga laiendamiseks kasutage metamärke: "name": "core/*".

Migreerimise kontrollnimekiri

  1. Looge ploki kaust asukohas theme/blockstudio/{block-name}/ koos failidega block.json ja index.php.
  2. Teisaldage väljade määratlused ploki väljarühmast (Local JSON, acf_add_local_field_group() või tekstisisene acf.fields massiiv) faili block.json massiivi blockstudio.attributes. Muutke name väärtuseks id, eemaldage key ja kohandage vajaduse korral tüüpide nimetusi.
  3. Uuendage mallile ligipääsu kujult get_field('name') kujule $a['name']. Asendage have_rows() tsüklid konstruktsiooniga foreach ($a['repeater'] as $item).
  4. Asendage get_sub_field() otsese massiivile juurdepääsuga: $item['fieldId'].
  5. Lisage useBlockProps malli kõige välimisele elemendile, et tagada korrektne integratsioon redaktoriga.
  6. Teisaldage tingimusloogika ACF conditional_logic-ist Blockstudio conditions-i, kasutades välja võtmete asemel välja ID-sid.
  7. Lisage salvestusruum väljadele, mida varem päriti get_post_meta() kaudu või kasutati WP_Query-is.
  8. Eemaldage ACF registreerimiskood: migreeritud plokkide register_block_type() väljakutsed ja acf võtmed (või nende acf_register_block_type() väljakutsed) ning väljarühmad, olenemata sellest, kas need asuvad Local JSON-is, acf_add_local_field_group()-is, tekstisiseses acf.fields massiivis või halduspaneelis.
  9. Testige redaktoris, kas väljad ilmuvad õigesti, ja kontrollige seejärel esilehe väljundit.