Vykreslování atributů
V souborech šablon lze ke všem atributům přistupovat pomocí proměnných $attributes nebo $a a příslušného ID pole.
PHP
<h1><?php echo $attributes['message']; ?></h1>
<h1><?php echo $a['message']; ?></h1>
Twig
<h1>{{ attributes.message }}</h1>
<h1>{{ a.message }}</h1>
Programové zapisování atributů
Editor ukládá hodnoty vnořené pod blockstudio.attributes. Nástroje, které zapisují blok mimo editor, například REST API, WP-CLI, migrace obsahu nebo server MCP, zjistí blok z atributů, které Blockstudio registruje v WP_Block_Type, a zapíší je na nejvyšší úrovni. Vykreslí se oba formáty:
// 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"}}} /-->' );
Načítají se pouze ID deklarovaná blokem, takže vlastní atributy WordPress, jako anchor, className, lock, metadata a style, se nikdy nepřevezmou jako hodnoty polí. Pokud se stejné ID objeví na obou místech, přednost má vnořená hodnota.
Programové čtení atributů
Kód spouštěný mimo šablonu, například strukturovaná data v save_post, exporty, indexování pro vyhledávání nebo filtr render_block, často potřebuje hodnoty uloženého bloku v podobě, v jaké je vidí šablona. bs_block_values() je vrátí bez vykreslení bloku. Zavolejte jej po registraci bloku (init nebo později) s úplným polem 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ýsledkem je pole $a šablony, indexované podle ID polí:
- Použijí se výchozí hodnoty polí a opakovač s
minobsahuje své počáteční řádky. - Sloučí se nejvyšší úroveň hodnot a
blockstudio.attributes; přednost má vnořená hodnota. Načítají se pouze deklarovaná ID z nejvyšší úrovně a WordPress zahodí nejvyšší hodnotu, která neodpovídá registrovanému typu pole, například řetězec výběru, stejně jako při vykreslování. - Zahrnou se pole odpovídajících rozšíření rozšíření včetně jejich výchozích hodnot. Rozšíření bloku jádra nebo bloku třetí strany načítá pouze
blockstudio.attributes, stejně jako při vykreslování. - Použijí se formáty návratových hodnot, takže výběr s
returnFormattypulabelvrátí štítek a pole souborů vrátí data příloh. - Zakázaná a prázdná pole jsou
false, stejně jako v šabloně.
null znamená, že blok ani rozšíření nespravuje Blockstudio. Blok Blockstudio bez polí vrací [].
Funkce spouští stejnou transformaci jako vykreslování, takže má i stejné vedlejší účinky: pole souborů načítají přílohy, pole bloku, které nevrací data, vykreslí odkazovaný blok a filtr blockstudio/blocks/attributes/render se spustí pro každou hodnotu. Vlastní šablonu bloku nevykresluje a neřeší innerBlocks; projděte je sami. Pole kódu zachovává vygenerované ID %selector%, které se mezi voláními liší.
Převod používá aktuální kontext WordPress. Metadata dostupná pouze při vykreslování, jako jsou počítadla bloků a innerBlocks, se nevytvářejí; filtry vykreslování atributů dostávají název bloku, nikoli metadata plně vykresleného bloku.
Pro uložené hodnoty bez transformace není k dispozici žádná možnost. Přečtěte přímo pole attrs nebo je ověřte pomocí bs_validate_block().
Prázdné hodnoty
Hodnoty atributů vracejí false, pokud je pole prázdné nebo není vybrána žádná možnost.
PHP
<?php if ($a['message']) : ?>
<h1><?php echo $a['message']; ?></h1>
<?php endif; ?>
Twig
{% if a.message %}
<h1>{{ a.message }}</h1>
{% endif %}
Složené typy
Soubory
Ve výchozím nastavení (bez returnFormat nebo při hodnotě "returnFormat": "object") vrací pole souborů pole s daty přílohy. S "multiple": true vrací seznam těchto polí. Soubor, jehož příloha už neexistuje, je false.
| Klíč | Popis |
|---|---|
ID |
ID přílohy. |
title |
Název přílohy. |
alt |
Alternativní text. Pokud je prázdný, použije se název přílohy. |
caption |
Popisek. |
description |
Popis. |
href |
Trvalý odkaz na stránku přílohy. |
url |
URL souboru. Při použití rozbalovací nabídky velikostí ("size": true) jde o URL vybrané velikosti. |
sizes |
URL a rozměry každé registrované velikosti obrázku; viz níže. |
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 pro každou registrovanou velikost obrázku a také full: URL pod názvem velikosti a rozměry pod <size>-width a <size>-height. Pokud se pro přílohu nevygenerovala velikost WordPress, vrátí se původní soubor s jeho rozměry. Pokud WordPress nedokáže rozpoznat obrázek nebo náhled, klíč sizes chybí. Například PDF bez vygenerovaného náhledu nemá sizes, ale PDF s metadaty náhledu může mít velikosti obrázku. sizes má hodnotu null, když nejsou registrovány žádné velikosti obrázku nebo když filtr files/sizes zakáže jejich použití. Tento filtr může mapu také zkrátit, proto před načtením rozměrů ověřte, že velikost existuje, jako v příkladech výše.
Objekt nemá klíče width, height, mime, type ani size. Rozměry načtěte z sizes nebo použijte ID s funkcemi, jako jsou wp_get_attachment_image() a get_post_mime_type().
Formáty návratových hodnot
returnFormat mění hodnotu, kterou pole vrací:
returnFormat |
Hodnota |
|---|---|
"object" (výchozí) |
Výše popsané pole. |
"id" |
ID přílohy v uložené podobě, případně seznam ID při použití "multiple": true. |
"url" |
URL jako řetězec, případně seznam URL při použití "multiple": true. Obrázky používají velikost nastavenou pomocí returnSize (výchozí full), ostatní soubory používají svou URL souboru. |
Odkaz
Pole odkazu vrací objekt s klíčem URL a atributy:
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 vrací objekt s klíči set, subSet a icon. K vykreslení SVG použijte pomocné funkce 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 přímo. bs_icon() jej vrátí jako řetězec.
Atributy
Typ pole atributů vrací pole dvojic {attribute, value}, které se vykreslí jako atributy HTML. K jejich výpisu použijte 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 atributy přímo. bs_data_attributes() vrátí řetězec.
Skupina
Pole atributů potomků skupiny opatří předponou názvu skupiny. Pomocí bs_get_group() extrahujte pole skupiny do přehledného pole:
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 se z klíčů atributů odstraní předpona skupiny. Například $a['settings_title'] se změní na $group['title'].
Pomocná funkce funguje také v případě, že skupina pochází z opakovaně použitého vlastního pole:
{
"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č
Procházejte položky opakovače:
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 %}