Attribuuttien renderöinti
Mallipohjatiedostoissa kaikkiin attribuutteihin pääsee käsiksi muuttujien $attributes tai $a sekä kentän tunnisteen avulla.
PHP
<h1><?php echo $attributes['message']; ?></h1>
<h1><?php echo $a['message']; ?></h1>
Twig
<h1>{{ attributes.message }}</h1>
<h1>{{ a.message }}</h1>
Attribuuttien kirjoittaminen ohjelmallisesti
Editorissa tallennetut arvot sijoitetaan blockstudio.attributes-avaimen alle. Editorin ulkopuolella lohkoon tietoja kirjoittava toiminto, kuten REST API, WP-CLI, sisällön siirto tai MCP-palvelin, selvittää lohkon Blockstudio-arvoista, jotka WP_Block_Type rekisteröi, ja kirjoittaa ne ylimmälle tasolle. Molemmat rakenteet renderöityvät:
// Top level, as a programmatic writer produces it.
echo do_blocks( '<!-- wp:acme/hero {"visual_type":"media"} /-->' );
// Nested, as the editor saves it.
echo do_blocks( '<!-- wp:acme/hero {"blockstudio":{"attributes":{"visual_type":"media"}}} /-->' );
Vain lohkon määrittämät tunnisteet luetaan ylimmältä tasolta, joten lohkon WordPress omia attribuutteja, kuten anchor, className, lock, metadata ja style, ei koskaan tulkita kenttäarvoiksi. Jos sama tunniste esiintyy molemmissa paikoissa, sisäkkäinen arvo voittaa.
Attribuuttien lukeminen ohjelmallisesti
Mallin ulkopuolella suoritettava koodi, kuten kohteen save_post rakenteinen data,
viennit, hakemistoindeksointi tai render_block-suodatin, tarvitsee usein tallennetun
lohkon arvot sellaisina kuin malli ne näkee. bs_block_values() palauttaa arvot
renderöimättä lohkoa. Kutsu sitä lohkon rekisteröinnin jälkeen (init tai
myöhemmin) käyttäen koko attrs-taulukkoa kohteesta parse_blocks():
foreach (parse_blocks($post->post_content) as $block) {
if ($block['blockName'] === null) {
continue;
}
$a = bs_block_values($block['blockName'], $block['attrs']);
if ($a === null) {
// Not a Blockstudio block, and no extension applies.
continue;
}
echo esc_html($a['title'] ?? '');
}
Tuloksena on mallin $a-taulukko, jonka avaimina ovat kenttätunnukset:
- Kenttien oletusarvot otetaan käyttöön, ja toistimella, jolla on
min, on alkuperäiset rivinsä. - Ylätason arvot yhdistetään arvoihin
blockstudio.attributes, ja sisäkkäinen arvo voittaa. Vain määritettyjen tunnusten arvot luetaan ylätasolta, ja WordPress poistaa ylätason arvon, joka ei vastaa kentän rekisteröityä tyyppiä, esimerkiksi valinnan merkkijonoa, aivan kuten renderöinnissä. - Vastaavien laajennusten kentät oletusarvoineen sisällytetään. Ydinlohkon tai kolmannen osapuolen lohkon laajennus lukee vain
blockstudio.attributes, kuten renderöinnissä. - Palautusmuotoja käytetään, joten valinta, jonka
returnFormatonlabel, antaa selitteen ja tiedostokenttä antaa liitteen tiedot. - Käytöstä poistetut ja tyhjät kentät ovat
false, kuten mallissa.
null tarkoittaa, ettei lohkoa eikä laajennusta hallinnoi Blockstudio.
Blockstudio-lohko, jossa ei ole kenttiä, palauttaa arvon [].
Funktio suorittaa saman muunnoksen kuin renderöinti, joten sillä on samat
sivuvaikutukset: tiedostokentät hakevat liitteet, lohkokenttä, joka ei palauta
arvoa data, renderöi viitatun lohkon, ja
blockstudio/blocks/attributes/render-suodatin suoritetaan jokaiselle arvolle. Funktio ei
renderöi lohkon omaa mallia eikä ratkaise arvoja innerBlocks; käy ne läpi itse. Koodikentän
luoma %selector%-tunnus vaihtelee kutsujen välillä.
Ratkaisu käyttää nykyistä WordPress-kontekstia. Vain renderöinnissä käytettäviä metatietoja,
kuten lohkolaskureita ja innerBlocks, ei luoda; attribuutin renderöintisuodattimet
saavat lohkon nimen, eivät täysin renderöidyn lohkon metatietoja.
Tallennetuille arvoille ei ole muunnoksen ohittavaa vaihtoehtoa. Lue ne suoraan
attrs-taulukosta tai tarkista ne funktiolla
bs_validate_block().
Tyhjät arvot
Attribuuttiarvo palauttaa false, jos kenttä on tyhjä tai mitään vaihtoehtoa ei ole valittu.
PHP
<?php if ($a['message']) : ?>
<h1><?php echo $a['message']; ?></h1>
<?php endif; ?>
Twig
{% if a.message %}
<h1>{{ a.message }}</h1>
{% endif %}
Monimutkaiset tyypit
Tiedostot
Oletusarvoisesti (ilman arvoa returnFormat tai arvolla "returnFormat": "object") tiedostokenttä
palauttaa taulukon, joka sisältää liitteen tiedot. Arvolla "multiple": true se
palauttaa luettelon tällaisista taulukoista. Tiedosto, jonka liitettä ei enää ole,
on false.
| Avain | Kuvaus |
|---|---|
ID |
Liitteen tunnus. |
title |
Liitteen otsikko. |
alt |
Vaihtoehtoinen teksti. Jos se on tyhjä, käytetään liitteen otsikkoa. |
caption |
Kuvateksti. |
description |
Kuvaus. |
href |
Liitesivun pysyvä linkki. |
url |
Tiedoston URL. Koon pudotusvalikolla ("size": true) näytetään valitun koon URL. |
sizes |
Jokaisen rekisteröidyn kuvakoon URL ja mitat, katso alta. |
PHP
<?php if ($a['image']) :
$image = $a['image'];
$sizes = $image['sizes'] ?? [];
?>
<img
src="<?php echo esc_url($sizes['large'] ?? $image['url']); ?>"
alt="<?php echo esc_attr($image['alt']); ?>"
<?php if (isset($sizes['large-width'], $sizes['large-height'])) : ?>
width="<?php echo esc_attr($sizes['large-width']); ?>"
height="<?php echo esc_attr($sizes['large-height']); ?>"
<?php endif; ?>
/>
<?php endif; ?>
Twig
{% if a.image %}
<img
src="{{ (a.image.sizes.large ?? a.image.url)|e('html_attr') }}"
alt="{{ a.image.alt|e('html_attr') }}"
{% if a.image.sizes['large-width'] is defined and a.image.sizes['large-height'] is defined %}
width="{{ a.image.sizes['large-width']|e('html_attr') }}"
height="{{ a.image.sizes['large-height']|e('html_attr') }}"
{% endif %}
/>
{% endif %}
sizes sisältää yhden merkinnän kutakin rekisteröityä kuvakokoa kohden sekä full: URL kokoluokan nimen alla ja mitat kohdissa <size>-width ja <size>-height. Jos liitteelle ei ole luotu kokoluokan WordPress, se viittaa alkuperäiseen tiedostoon mittoineen. Jos WordPress ei pysty ratkaisemaan kuvaa tai esikatselua, sizes-avain puuttuu. Esimerkiksi PDF-tiedostolla, jolle ei ole luotu esikatselua, ei ole sizes-arvoa, mutta esikatselun metatiedot sisältävällä PDF-tiedostolla voi olla kuvakokoja. sizes on null, kun rekisteröityjä kuvakokoja ei ole tai kun suodatin files/sizes poistaa ne käytöstä. Suodatin voi myös lyhentää karttaa, joten tarkista esimerkkien tapaan, että koko on olemassa, ennen kuin luet sen mitat.
Objektilla ei ole avaimia width, height, mime, type eikä size. Lue mitat kohteesta
sizes tai käytä kohdetta ID funktioiden, kuten
wp_get_attachment_image() ja get_post_mime_type(), kanssa.
Palautusmuodot
returnFormat muuttaa kentän palauttamaa arvoa:
returnFormat |
Arvo |
|---|---|
"object" (oletus) |
Edellä kuvattu taulukko. |
"id" |
Tallennettu liitteen tunnus tai tunnusten luettelo, kun käytössä on "multiple": true. |
"url" |
URL merkkijonona tai URL-osoitteiden luettelo, kun käytössä on "multiple": true. Kuvissa käytetään koolla returnSize määritettyä kokoa (oletus full); muissa tiedostoissa käytetään niiden tiedoston URL. |
Linkki
Linkkikenttä palauttaa objektin, jossa on URL ja attribuutit:
PHP
<?php if ($a['link']) : ?>
<a
href="<?php echo $a['link']['url']; ?>"
target="<?php echo $a['link']['target']; ?>"
>
<?php echo $a['link']['title']; ?>
</a>
<?php endif; ?>
Twig
{% if a.link %}
<a href="{{ a.link.url }}" target="{{ a.link.target }}">
{{ a.link.title }}
</a>
{% endif %}
Kuvake
Kuvakekenttä palauttaa objektin, jossa on avaimet set, subSet ja icon. Tulosta SVG käyttämällä apufunktioita bs_render_icon() ja bs_icon():
PHP
<?php if ($a['icon']) : ?>
<div class="icon">
<?php bs_render_icon($a['icon']); ?>
</div>
<?php endif; ?>
Twig
{% if a.icon %}
<div class="icon">
{{ bs_icon(a.icon) }}
</div>
{% endif %}
bs_render_icon() tulostaa SVG:n suoraan. bs_icon() palauttaa sen merkkijonona.
Attribuutit
Attribuuttikenttätyyppi palauttaa {attribute, value}-parien taulukon, joka voidaan renderöidä HTML-attribuutteina. Tulosta ne komennolla bs_render_data_attributes():
PHP
<div <?php bs_render_data_attributes($a['attributes']); ?>>
Content
</div>
Twig
<div {{ fn('bs_render_data_attributes', a.attributes) }}>
Content
</div>
bs_render_data_attributes() tulostaa attribuutit suoraan. bs_data_attributes() palauttaa merkkijonon.
Ryhmä
Ryhmäkentissä lapsiattribuuttien tunnisteiden eteen lisätään ryhmän nimi. Poimi ryhmäkentät siistiin taulukkoon komennolla bs_get_group():
PHP
<?php $group = bs_get_group($a, 'settings'); ?>
<h1><?php echo $group['title']; ?></h1>
<p><?php echo $group['description']; ?></p>
Twig
{% set group = fn('bs_get_group', a, 'settings') %}
<h1>{{ group.title }}</h1>
<p>{{ group.description }}</p>
Tämä poistaa ryhmän etuliitteen attribuuttiavaimista. Esimerkiksi $a['settings_title'] muuttuu muotoon $group['title'].
Apufunktio toimii myös silloin, kun ryhmä tulee uudelleenkäytetystä mukautetusta kentästä:
{
"name": "section-header",
"attributes": [
{
"id": "section-header",
"type": "group",
"attributes": [
{ "id": "kicker", "type": "text" },
{ "id": "title", "type": "text" }
]
}
]
}
{
"blockstudio": {
"attributes": [
{ "type": "custom/section-header" }
]
}
}
{% set sectionHeader = fn('bs_get_group', a, 'section-header') %}
<p>{{ sectionHeader.kicker }}</p>
<h2>{{ sectionHeader.title }}</h2>
Toistin
Käy toistimen kohteet läpi:
PHP
<?php foreach ($a['items'] as $item) : ?>
<div class="item">
<h3><?php echo $item['title']; ?></h3>
<p><?php echo $item['description']; ?></p>
</div>
<?php endforeach; ?>
Twig
{% for item in a.items %}
<div class="item">
<h3>{{ item.title }}</h3>
<p>{{ item.description }}</p>
</div>
{% endfor %}