Redarea atributelor
În fișierele șablon, toate atributele pot fi accesate folosind variabilele $attributes sau $a și ID-ul corespunzător al câmpului.
PHP
<h1><?php echo $attributes['message']; ?></h1>
<h1><?php echo $a['message']; ?></h1>
Twig
<h1>{{ attributes.message }}</h1>
<h1>{{ a.message }}</h1>
Scrierea programatică a atributelor
Editorul imbrică valorile salvate sub blockstudio.attributes. Orice element care scrie un bloc în afara editorului, precum REST API, WP-CLI, o migrare de conținut sau un server MCP, descoperă blocul prin atributele înregistrate de Blockstudio în WP_Block_Type și le scrie la nivelul superior. Ambele structuri sunt redate:
// 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"}}} /-->' );
Se citesc de la nivelul superior numai ID-urile declarate de bloc, astfel încât atributele proprii ale lui WordPress, precum anchor, className, lock, metadata și style, nu sunt preluate niciodată drept valori ale câmpurilor. Dacă același ID apare în ambele locuri, prevalează valoarea imbricată.
Citirea programatică a atributelor
Codul care rulează în afara șablonului, cum ar fi datele structurate din save_post, exporturile, indexarea pentru căutare sau un filtru render_block, are adesea nevoie de valorile unui bloc salvat așa cum sunt văzute în șablon. bs_block_values() le returnează fără a randa blocul. Apelați-l după înregistrarea blocului (init sau ulterior), folosind matricea completă attrs din 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'] ?? '');
}
Rezultatul este matricea $a a șablonului, indexată după ID-ul câmpului:
- Se aplică valorile implicite ale câmpurilor, iar un repetor cu
minare rândurile inițiale. - Valorile de la nivelul superior și
blockstudio.attributessunt îmbinate, iar valoarea imbricată are prioritate. Sunt citite de la nivelul superior doar ID-urile declarate, iar WordPress elimină o valoare de la nivelul superior care nu corespunde exact tipului înregistrat al câmpului, de exemplu un șir pentru un câmp de selecție, la fel ca la randare. - Sunt incluse câmpurile extensiilor extensiilor care corespund, împreună cu valorile lor implicite. O extensie a unui bloc de bază sau terț citește doar
blockstudio.attributes, la fel ca la randare. - Se aplică formatele de returnare, astfel încât o selecție cu
returnFormatdelabelreturnează eticheta, iar un câmp pentru fișiere returnează datele atașamentului. - Câmpurile dezactivate și goale sunt
false, ca în șablon.
null înseamnă că nici blocul, nici o extensie nu sunt gestionate de Blockstudio. Un bloc Blockstudio fără câmpuri returnează [].
Funcția execută aceeași transformare ca randarea, deci are aceleași efecte secundare: câmpurile pentru fișiere interoghează atașamentele, un câmp de tip bloc care nu returnează data randează blocul referențiat, iar filtrul blockstudio/blocks/attributes/render rulează pentru fiecare valoare. Funcția nu randează șablonul propriu al blocului și nu rezolvă innerBlocks; parcurgeți-le manual. Un câmp de cod păstrează un ID %selector% generat, care diferă de la un apel la altul.
Rezolvarea folosește contextul curent WordPress. Metadatele create doar la randare, precum contoarele blocurilor și innerBlocks, nu sunt create; filtrele de randare a atributelor primesc numele blocului, nu metadatele unui bloc randat complet.
Nu există nicio opțiune pentru valorile stocate fără transformare. Citiți direct matricea attrs pentru acestea sau folosiți bs_validate_block() pentru a le verifica.
Valori goale
Valorile atributelor returnează false dacă acel câmp este gol sau nu a fost selectată nicio opțiune.
PHP
<?php if ($a['message']) : ?>
<h1><?php echo $a['message']; ?></h1>
<?php endif; ?>
Twig
{% if a.message %}
<h1>{{ a.message }}</h1>
{% endif %}
Tipuri complexe
Fișiere
În mod implicit (fără returnFormat sau cu "returnFormat": "object"), câmpul pentru fișiere returnează o matrice cu datele atașamentului. Cu "multiple": true, returnează o listă cu aceste matrice. Un fișier al cărui atașament nu mai există este false.
| Cheie | Descriere |
|---|---|
ID |
ID-ul atașamentului. |
title |
Titlul atașamentului. |
alt |
Textul alternativ. Dacă este gol, se folosește titlul atașamentului. |
caption |
Legenda. |
description |
Descrierea. |
href |
Legătura permanentă către pagina atașamentului. |
url |
URL fișierului. Cu meniul derulant pentru dimensiune ("size": true), URL dimensiunii selectate. |
sizes |
URL și dimensiunile fiecărei dimensiuni de imagine înregistrate; vedeți mai jos. |
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 are o intrare pentru fiecare dimensiune de imagine înregistrată, plus full: URL sub numele dimensiunii, iar dimensiunile sub <size>-width și <size>-height. Dacă atașamentul nu are generată o dimensiune WordPress, se folosește fișierul original împreună cu dimensiunile sale. Dacă WordPress nu poate rezolva o imagine sau o previzualizare, cheia sizes lipsește. De exemplu, un PDF fără previzualizare generată nu are sizes, dar un PDF cu metadate pentru previzualizare poate avea dimensiuni de imagine. sizes este null când nu sunt înregistrate dimensiuni de imagine sau când filtrul files/sizesfilter le dezactivează. Filtrul poate, de asemenea, să scurteze harta, așa că verificați dacă o dimensiune există înainte de a-i citi dimensiunile, ca în exemplele de mai sus.
Obiectul nu are cheile width, height, mime, type sau size. Citiți dimensiunile din sizes sau folosiți ID cu funcții precum wp_get_attachment_image() și get_post_mime_type().
Formate de returnare
returnFormat schimbă valoarea returnată de câmp:
returnFormat |
Valoare |
|---|---|
"object" (implicit) |
Matricea descrisă mai sus. |
"id" |
ID-ul atașamentului, așa cum este stocat, sau o listă de ID-uri cu "multiple": true. |
"url" |
URL ca șir sau o listă de URL-uri cu "multiple": true. Imaginile folosesc setul de dimensiuni stabilit cu returnSize (implicit full), iar celelalte fișiere folosesc propriul URL. |
Link
Câmpul link returnează un obiect cu URL și atribute:
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 %}
Pictogramă
Câmpul pentru pictogramă returnează un obiect cu cheile set, subSet și icon. Folosiți funcțiile ajutătoare bs_render_icon() și bs_icon() pentru a reda SVG-ul:
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() afișează direct SVG-ul. bs_icon() îl returnează ca șir.
Atribute
Tipul de câmp attributes returnează un tablou de perechi {attribute, value} pentru redarea ca atribute HTML. Folosiți bs_render_data_attributes() pentru a le afișa:
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() afișează direct atributele. bs_data_attributes() returnează șirul.
Grup
Câmpurile de grup adaugă numele grupului ca prefix la ID-urile atributelor copiilor. Folosiți bs_get_group() pentru a extrage câmpurile grupului într-un tablou simplu:
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>
Acest lucru elimină prefixul grupului din cheile atributelor. De exemplu, $a['settings_title'] devine $group['title'].
Funcția ajutătoare funcționează și când grupul provine dintr-un câmp personalizat reutilizat:
{
"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>
Câmp repetabil
Parcurgeți elementele câmpului repetabil:
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 %}