Siirry sisältöön

Siirtyminen lähteestä ACF Blocks

Jos olet rakentanut mukautettuja WordPress-lohkoja käyttäen ACF-toimintoa (Advanced Custom Fields), siirtyminen käyttämään Blockstudio-toimintoa on suoraviivaista. Käsitteet ovat samankaltaisia: määrität kentät, kirjoitat mallin ja lohko ilmestyy muokkaimeen. Erot ovat siinä, että Blockstudio löytää lohkokansiot automaattisesti, määrittää kentät omassa skeemassaan tiedostossa block.json ja välittää kunkin mallin kenttäarvot yhtenä $a-taulukkona.

Tämä opas käy siirtymisen läpi vaihe vaiheelta ja vertailee rinnakkain ACF- ja Blockstudio-malleja.

Keskeinen ero

ACF 6.0:sta lähtien ACF-lohko on block.json, jolla on renderöintimallin nimeävä acf-avain. Jokainen lohkokansio rekisteröidään omalla register_block_type()-kutsullaan. Kentät tulevat lohkoon liitetystä kenttäryhmästä, jossa käytetään Block-sijaintisääntöä (ryhmä luodaan hallintapaneelissa, synkronoidaan Local JSON-toiminnolla tai rekisteröidään acf_add_local_field_group()-toiminnolla) tai ACF PRO 6.8.1 -versiosta lähtien saman block.json-tiedoston sisältämästä acf.fields-taulukosta. Blockstudio korvaa rekisteröintikutsun tiedostopohjaisella automaattisella haulla: luo kansio, jossa on block.json ja index.php, niin lohko rekisteröidään automaattisesti.

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>

Rekisteröintikutsua tai renderöintitakaisinkutsua ei tarvita: kansiorakenne toimii rekisteröintinä, ja kentät ovat tiedostossa block.json mallin vieressä. Malli lukee arvon $a sen sijaan, että se kutsuisi toimintoa get_field().

Lohkon rekisteröinti

ACF

Nykyiset ACF-lohkot rekisteröidään block.json-tiedostosta, jossa on acf-avain (renderTemplate tai renderCallback sekä valinnaisia asetuksia, kuten blockVersion). Ne ladataan erillisellä register_block_type()-kutsulla kullekin lohkokansiolle, tavallisesti tiedostossa functions.php kohdassa init tai lisäosatiedostossa. Vanhemmissa lohkoissa voidaan yhä käyttää toimintoa acf_register_block_type(), jonka ACF on dokumentoinut vanhentuneeksi ACF 6.0:sta lähtien. Se toimii yhä, joten siirrä nämä lohkot samalla tavalla.

Blockstudio

Luo kansio teemasi blockstudio/-hakemistoon (tai halutessasi hakemistoon blocks/). Lisää tiedosto block.json, jossa on tavalliset WordPress-lohkometatiedot sekä avain blockstudio. Siinä kaikki.

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

block.json käyttää kenttien ja määritysten tallentamiseen vakiomuotoista WordPress block.json -muotoa ja avainta blockstudio:

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

Kenttäarvojen käyttö

Tämä on yleisin muutos, jonka teet siirtymisen aikana.

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

Muuttuja $a on lyhenne muodosta $attributes, ja se sisältää kaikki nykyisen lohkon kenttäarvot. Se on aina käytettävissä mallissa sekä muokkaimessa että käyttöliittymässä.

Mallimuuttujat

Blockstudio tarjoaa jokaisessa mallissa useita muuttujia:

Muuttuja Lyhenne Kuvaus
$attributes $a Kaikki kenttäarvot
$block $b Lohkon metatiedot (name, title, dir, url, postId)
$context $c Ylemmän lohkon konteksti
$content InnerBlocks-sisältö
$post_id Nykyisen julkaisun tunnus (toimii muokkaimessa ja käyttöliittymässä; post_id tai postId muodossa Twig)

Kenttätyyppien määritykset

Useimmille ACF-kenttätyypeille löytyy suora vastine Blockstudio-palvelusta. JSON-syntaksi on erilainen, mutta käsitteet vastaavat toisiaan hyvin.

Teksti- ja sisältökentät

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

Kun haluat muokattavaa tekstiä lohkomuokkaimessa (etkä pelkkää tekstikenttää), käytä tyyppiä richtext yhdessä komponentin <RichText /> kanssa:

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

Kuva- ja tiedostokentät

ACF-palvelun kentät image ja file vastaavat Blockstudio-palvelun tyyppiä 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"] }

Palautetun objektin rakenne on samankaltainen:

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

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

Käytettävissä olevat ominaisuudet: ID, title, alt, caption, description, href, url, sizes. Mitat ovat muodossa sizes, esimerkiksi $a['photo']['sizes']['full-width'].

Valinta, radio ja valintaruutu

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

Käytä "returnFormat": "both"-toimintoa saadaksesi sekä arvon että selitteen:

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

Samaa mallia käytetään myös tyypeissä radio ja checkbox.

Vaihto ja tosi/epätosi

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äri ja liukuväri

ACF:

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

Blockstudio:

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

Tyyppi color integroituu WordPress-väripalettiin. Tyyppi gradient tarjoaa liukuvärivalitsimen.

Numero, liukualue ja päivämäärä

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

Toistinkentät

ACF-palvelun toistinkenttää vastaa suoraan Blockstudio-palvelun tyyppi repeater. ACF-mallit käyvät tavallisesti silmukassa läpi arvot toiminnoilla have_rows() / the_row() / get_sub_field() (toistinkentän get_field() palauttaa myös rivitaulukon). Blockstudio sisältää vain yksinkertaisen PHP-taulukon, joka on jo muodossa $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-toistimet tukevat sisäkkäisiä toistimia enintään kolmella tasolla.

Ryhmät

ACF-palvelun ryhmäkenttää vastaa Blockstudio-palvelun tyyppi group. Ryhmien sisällä olevien kenttien tunnuksiin lisätään ryhmän tunnus etuliitteeksi.

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>

Apuohjelma bs_get_group() poistaa kenttien tunnuksista ryhmän etuliitteen, jolloin niitä on helppo käyttää. Ilman sitä kenttiin viitattaisiin muodossa $a['author_name'] ja $a['author_role'].

Ehdollinen logiikka

Sekä ACF että Blockstudio tukevat ehdollista logiikkaa, jolla kenttiä näytetään tai piilotetaan muiden kenttien arvojen perusteella.

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-ehdoissa viitataan suoraan kenttien tunnuksiin (ei kenttäavaimiin). Käytettävissä olevat operaattorit: ==, !=, includes, !includes, empty, !empty, <, >, <=, >=.

Blockstudio tukee myös yleisiä ehtoja, jotka perustuvat sisältötyyppiin, sisällön tunnukseen, käyttäjän rooliin ja käyttäjän tunnukseen:

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

InnerBlocks

Sekä ACF että Blockstudio tukevat InnerBlocks-ominaisuutta, jolla mukautettuun lohkoon voi sisäkkäin lisätä muita lohkoja. Käytössä ovat sama <InnerBlocks />-tunniste sekä samat attribuutit allowedBlocks, template ja templateLock, joten tämä osa mallista säilyy yleensä ennallaan.

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>

Tunniste <InnerBlocks /> korvataan muokkaimessa komponentilla React ja käyttöliittymässä renderöidyllä lohkosisällöllä.

Julkaisumetatietojen tallennus

Sekä ACF Blocks että Blockstudio tallentavat kenttien arvot oletusarvoisesti lohkon määritteiksi artikkelin sisältöön, eivät artikkelin metatietoihin. Siksi kenttien arvoja ei voi hakea WP_Query-toiminnolla, ellet ota käyttöön metatietotallennusta.

ACF lisäsi lohkoille valinnaisen artikkelin metatietotallennuksen versiossa ACF PRO 6.3 usePostMeta: true-toiminnon kautta, yhdelle ylätason lohkolle sivua kohden. Blockstudio tarjoaa kenttäkohtaisen valintamahdollisuuden storage-ominaisuuden avulla:

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

Metatietoavain rekisteröidään automaattisesti show_in_rest-toiminnolla. Käytä sitä missä tahansa get_post_meta($post_id, 'is_featured', true)-toiminnolla.

Sivustonlaajuisiin arvoihin (kuten ACF-asetussivuihin) käytä asetustallennusta:

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

Olemassa olevien lohkojen laajentaminen

ACFn lohkon sijaintisääntö liittää kenttäryhmät vain ACF-lohkoihin; se ei lisää kenttiä ytimen tai kolmannen osapuolen lohkoihin. ACFn tapa lisätä kenttiä ydilohkoihin, kuten Otsikko-, Kappale-, Kuva- ja Painike-lohkoihin, on WordPress Block Bindings API, joka yhdistää olemassa olevat lohkomääritteet ACFn kenttäarvoihin. Blockstudio voi lisätä uusia kenttiä ja ohjaimia mihin tahansa rekisteröityyn lohkoon laajennustiedostojen avulla.

Luo laajennustiedosto blockstudio-hakemistoosi:

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

set-ominaisuus liittää kentän arvon automaattisesti lohkon HTML-elementtiin. Laajenna useita lohkoja kerralla jokerimerkeillä: "name": "core/*".

Siirron tarkistuslista

  1. Luo lohkokansio hakemistoon theme/blockstudio/{block-name}/ käyttäen tiedostoja block.json ja index.php.
  2. Siirrä kenttämäärittelyt lohkon kenttäryhmästä (Local JSON, acf_add_local_field_group() tai inline-acf.fields-taulukko) tiedoston block.json blockstudio.attributes-taulukkoon. Muuta name muotoon id, poista key ja muuta tyypin nimiä tarvittaessa.
  3. Päivitä mallipohjan käyttö muodosta get_field('name') muotoon $a['name']. Korvaa have_rows()-silmukat muodolla foreach ($a['repeater'] as $item).
  4. Korvaa get_sub_field() suoran taulukon käytöllä: $item['fieldId'].
  5. Lisää useBlockProps mallipohjan uloimpaan elementtiin, jotta editori-integraatio toimii oikein.
  6. Siirrä ehdollinen logiikka kohteen ACF conditional_logic-osiosta kohteen Blockstudio conditions-osioon ja käytä kenttätunnuksia kenttäavainten sijaan.
  7. Lisää tallennus kentille, joita aiemmin haettiin get_post_meta()-toiminnolla tai käytettiin WP_Query-toiminnossa.
  8. Poista ACFn rekisteröintikoodi: siirrettyjen lohkojen register_block_type()-kutsut ja acf-avaimet (tai niiden acf_register_block_type()-kutsut) sekä niiden kenttäryhmät riippumatta siitä, ovatko ne Local JSONssa, acf_add_local_field_group()ssa, inline-acf.fields-taulukossa vai hallintapaneelissa.
  9. Testaa editorissa, että kentät näkyvät oikein, ja tarkista sitten käyttöliittymän tuloste.