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:
{
"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>
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.
theme/
└── blockstudio/
└── hero/
├── block.json
└── index.php
block.json käyttää kenttien ja määritysten tallentamiseen vakiomuotoista WordPress block.json -muotoa ja avainta blockstudio:
{
"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:
['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" }
Kun haluat muokattavaa tekstiä lohkomuokkaimessa (etkä pelkkää tekstikenttää), käytä tyyppiä richtext yhdessä komponentin <RichText /> kanssa:
{ "id": "heading", "type": "richtext" }
<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:
['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"] }
Palautetun objektin rakenne on samankaltainen:
// 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:
[
'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" }
]
}
Käytä "returnFormat": "both"-toimintoa saadaksesi sekä arvon että selitteen:
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:
['name' => 'show_cta', 'type' => 'true_false', 'label' => 'Show CTA']
Blockstudio:
{ "id": "showCta", "type": "toggle", "label": "Show CTA" }
Linkkikenttä
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'];
Väri ja liukuväri
ACF:
['name' => 'bgColor', 'type' => 'color_picker', 'label' => 'Background']
Blockstudio:
{ "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:
['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" }
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:
['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; ?>
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:
['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>
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:
['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 }]]
}
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:
{
"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:
<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:
{
"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:
{
"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:
{
"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
- Luo lohkokansio hakemistoon
theme/blockstudio/{block-name}/käyttäen tiedostojablock.jsonjaindex.php. - Siirrä kenttämäärittelyt lohkon kenttäryhmästä (Local JSON,
acf_add_local_field_group()tai inline-acf.fields-taulukko) tiedostonblock.jsonblockstudio.attributes-taulukkoon. Muutanamemuotoonid, poistakeyja muuta tyypin nimiä tarvittaessa. - Päivitä mallipohjan käyttö muodosta
get_field('name')muotoon$a['name']. Korvaahave_rows()-silmukat muodollaforeach ($a['repeater'] as $item). - Korvaa
get_sub_field()suoran taulukon käytöllä:$item['fieldId']. - Lisää
useBlockPropsmallipohjan uloimpaan elementtiin, jotta editori-integraatio toimii oikein. - Siirrä ehdollinen logiikka kohteen ACF
conditional_logic-osiosta kohteen Blockstudioconditions-osioon ja käytä kenttätunnuksia kenttäavainten sijaan. - Lisää tallennus kentille, joita aiemmin haettiin
get_post_meta()-toiminnolla tai käytettiinWP_Query-toiminnossa. - Poista ACFn rekisteröintikoodi: siirrettyjen lohkojen
register_block_type()-kutsut jaacf-avaimet (tai niidenacf_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. - Testaa editorissa, että kentät näkyvät oikein, ja tarkista sitten käyttöliittymän tuloste.