Vykresľovanie atribútov
V súboroch šablón možno pristupovať ku všetkým atribútom pomocou premenných $attributes alebo $a a príslušného ID poľa.
PHP
<h1><?php echo $attributes['message']; ?></h1>
<h1><?php echo $a['message']; ?></h1>
Twig
<h1>{{ attributes.message }}</h1>
<h1>{{ a.message }}</h1>
Programový zápis atribútov
Editor ukladá hodnoty do vnoreného poľa blockstudio.attributes. Nástroj, ktorý zapisuje blok mimo editora, napríklad REST API, WP-CLI, migrácia obsahu alebo server MCP, zistí blok podľa atribútov, ktoré Blockstudio registruje v WP_Block_Type, a zapíše ich na najvyššej úrovni. Fungujú oba tvary:
// 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"}}} /-->' );
Z najvyššej úrovne sa čítajú iba ID deklarované blokom, takže vlastné atribúty WordPress, ako sú anchor, className, lock, metadata a style, sa nikdy nepoužijú ako hodnoty polí. Ak sa rovnaké ID nachádza na oboch miestach, prednosť má vnorená hodnota.
Programové čítanie atribútov
Kód spúšťaný mimo šablóny, napríklad pri štruktúrovaných údajoch v save_post, exportoch, indexovaní vyhľadávania alebo vo filtri render_block, často potrebuje hodnoty uloženého bloku tak, ako ich vidí šablóna. Funkcia bs_block_values() ich vráti bez vykreslenia bloku. Zavolajte ju po registrácii bloku (init alebo neskôr) s úplným poľom attrs z 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'] ?? '');
}
Výsledkom je pole $a zo šablóny, indexované podľa ID poľa:
- Použijú sa predvolené hodnoty polí a opakovač s
minobsahuje počiatočné riadky. - Hodnoty najvyššej úrovne a
blockstudio.attributessa zlúčia; vnorená hodnota má prednosť. Z najvyššej úrovne sa čítajú iba deklarované ID a WordPress zahodí hodnotu najvyššej úrovne, ktorá nezodpovedá registrovanému typu poľa, napríklad reťazec pri výbere, rovnako ako pri vykreslení. - Zahrnú sa polia zodpovedajúcich rozšírení vrátane ich predvolených hodnôt. Rozšírenie základného bloku alebo bloku tretej strany číta iba
blockstudio.attributes, rovnako ako pri vykreslení. - Použijú sa formáty návratových hodnôt, takže výber s
returnFormatnastaveným nalabelvráti štítok a pole súborov vráti údaje prílohy. - Zakázané a prázdne polia sa
false, rovnako ako v šablóne.
null znamená, že blok ani rozšírenie nespravuje Blockstudio. Blok Blockstudio bez polí vracia [].
Funkcia vykonáva rovnakú transformáciu ako pri vykreslení, takže má aj rovnaké vedľajšie účinky: polia súborov vyhľadávajú prílohy, pole bloku, ktoré nevracia data, vykreslí odkazovaný blok a filter blockstudio/blocks/attributes/render sa spustí pre každú hodnotu. Vlastná šablóna bloku sa nevykreslí a innerBlocks sa nerozpoznajú; prejdite ich sami. Pole kódu si pri každom volaní zachová vygenerované ID %selector%, ktoré sa medzi volaniami líši.
Rozpoznávanie používa aktuálny kontext WordPress. Metadáta vytvárané iba pri vykreslení, ako počítadlá blokov a innerBlocks, sa nevytvárajú; filtre vykreslenia atribútov dostanú názov bloku, nie metadáta úplne vykresleného bloku.
Neexistuje možnosť získať uložené hodnoty bez transformácie. Ak ich potrebujete, čítajte priamo pole attrs alebo ich skontrolujte pomocou bs_validate_block().
Prázdne hodnoty
Hodnoty atribútov vracajú false, ak je pole prázdne alebo nie je vybraná žiadna možnosť.
PHP
<?php if ($a['message']) : ?>
<h1><?php echo $a['message']; ?></h1>
<?php endif; ?>
Twig
{% if a.message %}
<h1>{{ a.message }}</h1>
{% endif %}
Zložité typy
Súbory
Predvolene (bez returnFormat alebo pri hodnote "returnFormat": "object") vracia pole súborov pole s údajmi prílohy. Pri hodnote "multiple": true vracia zoznam takýchto polí. Súbor, ktorého príloha už neexistuje, je false.
| Kľúč | Opis |
|---|---|
ID |
ID prílohy. |
title |
Názov prílohy. |
alt |
Alternatívny text. Ak je prázdny, použije sa názov prílohy. |
caption |
Popisok. |
description |
Opis. |
href |
Trvalý odkaz na stránku prílohy. |
url |
URL súboru. Pri rozbaľovacom zozname veľkostí ("size": true) ide o URL vybranej veľkosti. |
sizes |
URL a rozmery každej registrovanej veľkosti obrázka; pozri nižšie. |
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 obsahuje jednu položku pre každú registrovanú veľkosť obrázka a navyše full: URL pod názvom veľkosti a rozmery pod <size>-width a <size>-height. Ak sa veľkosť WordPress pre prílohu nevygenerovala, použije sa pôvodný súbor a jeho rozmery. Ak WordPress nedokáže rozpoznať obrázok alebo ukážku, kľúč sizes chýba. Napríklad PDF bez vygenerovanej ukážky nemá sizes, ale PDF s metadátami ukážky môže mať veľkosti obrázka. Hodnota sizes je null, ak nie sú registrované žiadne veľkosti obrázka alebo ak ich filter files/sizes zakáže. Tento filter môže mapu aj skrátiť, preto pred čítaním rozmerov overte, či daná veľkosť existuje, ako je uvedené v príkladoch vyššie.
Objekt neobsahuje kľúče width, height, mime, type ani size. Rozmery získate z sizes alebo použite ID s funkciami, ako sú wp_get_attachment_image() a get_post_mime_type().
Formáty návratových hodnôt
returnFormat mení hodnotu, ktorú pole vracia:
returnFormat |
Hodnota |
|---|---|
"object" (predvolené) |
Pole opísané vyššie. |
"id" |
ID prílohy v uloženej podobe alebo zoznam ID pri použití "multiple": true. |
"url" |
URL ako reťazec alebo zoznam URL pri použití "multiple": true. Pri obrázkoch sa použije veľkosť nastavená pomocou returnSize (predvolene full), pri ostatných súboroch ich URL súboru. |
Odkaz
Pole odkazu vracia objekt s kľúčmi URL a atribútmi:
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 %}
Ikona
Pole ikony vracia objekt s kľúčmi set, subSet a icon. Na výstup SVG použite pomocné funkcie bs_render_icon() a 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() vypíše SVG priamo. bs_icon() ho vráti ako reťazec.
Atribúty
Typ poľa atribútov vracia pole dvojíc {attribute, value} na vykreslenie ako atribúty HTML. Na ich výstup použite 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() vypíše atribúty priamo. bs_data_attributes() vráti reťazec.
Skupina
ID atribútov vnorených polí skupiny majú ako predponu názov skupiny. Pomocou bs_get_group() vyberte polia skupiny do prehľadného poľa:
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 sa z kľúčov atribútov odstráni predpona skupiny. Napríklad $a['settings_title'] sa zmení na $group['title'].
Pomocná funkcia funguje aj vtedy, keď skupina pochádza z opakovane použitého vlastného poľa:
{
"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>
Opakovač
Prechádzajte položky opakovača:
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 %}