Renderizzare gli attributi
Nei file template, è possibile accedere a tutti gli attributi usando le variabili $attributes o $a e l’ID del campo corrispondente.
PHP
<h1><?php echo $attributes['message']; ?></h1>
<h1><?php echo $a['message']; ?></h1>
Twig
<h1>{{ attributes.message }}</h1>
<h1>{{ a.message }}</h1>
Scrivere attributi a livello di codice
L’editor annida i valori salvati sotto blockstudio.attributes. Qualsiasi sistema che scrive un blocco al di fuori dell’editor, come REST API, WP-CLI, una migrazione dei contenuti o un server MCP, individua il blocco dagli attributi registrati da Blockstudio su WP_Block_Type e li scrive al livello superiore. Entrambe le strutture vengono renderizzate:
// 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"}}} /-->' );
Vengono letti dal livello superiore solo gli ID dichiarati dal blocco, quindi gli attributi propri di WordPress, come anchor, className, lock, metadata e style, non vengono mai adottati come valori dei campi. Se lo stesso ID compare in entrambe le posizioni, prevale il valore annidato.
Lettura programmatica degli attributi
Il codice eseguito al di fuori del template, ad esempio per i dati strutturati su save_post, le esportazioni, l’indicizzazione di ricerca o un filtro render_block, spesso ha bisogno dei valori salvati di un blocco così come vengono visualizzati nel template. bs_block_values() li restituisce senza eseguire il rendering del blocco. Chiamatela dopo la registrazione del blocco (init o in seguito) passando l’array completo di attrs da 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'] ?? '');
}
Il risultato è l’array $a del template, indicizzato per ID campo:
- Vengono applicati i valori predefiniti dei campi e un ripetitore con
mincontiene le righe iniziali. - I valori di primo livello e
blockstudio.attributesvengono uniti e prevale il valore annidato. Vengono letti dal primo livello solo gli ID dichiarati e WordPress scarta un valore di primo livello che non corrisponde al tipo registrato del campo, ad esempio una stringa per un campo di selezione, proprio come nel rendering. - Sono inclusi i campi delle estensioni corrispondenti, con i relativi valori predefiniti. Un’estensione di un blocco principale o di terze parti legge solo
blockstudio.attributes, come nel rendering. - Vengono applicati i formati di restituzione: quindi una selezione con
returnFormatpari alabelrestituisce l’etichetta e un campo file restituisce i dati dell’allegato. - I campi disabilitati e vuoti sono
false, come nel template.
null significa che né il blocco né un’estensione sono gestiti da Blockstudio. Un blocco Blockstudio senza campi restituisce [].
La funzione esegue la stessa trasformazione del rendering e ha quindi gli stessi effetti collaterali: i campi file interrogano gli allegati, un campo blocco che non restituisce data esegue il rendering del blocco referenziato e il filtro blockstudio/blocks/attributes/render viene eseguito per ogni valore. La funzione non esegue il rendering del template del blocco stesso e non risolve innerBlocks: esplorateli voi. Un campo codice conserva un ID %selector% generato, che varia da una chiamata all’altra.
La risoluzione usa il contesto corrente di WordPress. I metadati disponibili solo durante il rendering, come i contatori dei blocchi e innerBlocks, non vengono creati; i filtri di rendering degli attributi ricevono il nome del blocco, non i metadati di un blocco completamente renderizzato.
Non c’è un’opzione per ottenere i valori memorizzati senza trasformazione. Leggete direttamente l’array attrs per recuperarli oppure usate bs_validate_block() per verificarli.
Valori vuoti
I valori degli attributi restituiscono false se il campo è vuoto o non è stata selezionata alcuna opzione.
PHP
<?php if ($a['message']) : ?>
<h1><?php echo $a['message']; ?></h1>
<?php endif; ?>
Twig
{% if a.message %}
<h1>{{ a.message }}</h1>
{% endif %}
Tipi complessi
File
Per impostazione predefinita (senza returnFormat o con "returnFormat": "object"), il campo file restituisce un array con i dati dell’allegato. Con "multiple": true restituisce un elenco di questi array. Un file il cui allegato non esiste più è false.
| Chiave | Descrizione |
|---|---|
ID |
L’ID dell’allegato. |
title |
Il titolo dell’allegato. |
alt |
Il testo alternativo. Se vuoto, viene usato il titolo dell’allegato. |
caption |
La didascalia. |
description |
La descrizione. |
href |
Il permalink della pagina dell’allegato. |
url |
Il URL del file. Con il menu a discesa delle dimensioni ("size": true), il URL della dimensione selezionata. |
sizes |
Il URL e le dimensioni di ogni formato immagine registrato; vedi sotto. |
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 ha una voce per ogni formato immagine registrato, più full: il URL sotto il nome del formato e le dimensioni sotto <size>-width e <size>-height. Se per un allegato non è stato generato un formato WordPress, viene restituito il file originale con le sue dimensioni. Se WordPress non riesce a risolvere un’immagine o un’anteprima, la chiave sizes è assente. Ad esempio, un PDF senza anteprima generata non ha sizes, mentre un PDF con metadati di anteprima può avere formati immagine. sizes è null quando non è registrato alcun formato immagine o quando il filtro files/sizes li disabilita. Questo filtro può anche ridurre la mappa: verificate quindi che un formato esista prima di leggerne le dimensioni, come negli esempi sopra.
L’oggetto non contiene chiavi width, height, mime, type o size. Leggete le dimensioni da sizes oppure usate ID con funzioni come wp_get_attachment_image() e get_post_mime_type().
Formati di restituzione
returnFormat modifica il valore restituito dal campo:
returnFormat |
Valore |
|---|---|
"object" (predefinito) |
L’array descritto sopra. |
"id" |
L’ID dell’allegato così come è memorizzato, oppure un elenco di ID con "multiple": true. |
"url" |
URL come stringa, oppure un elenco di URL con "multiple": true. Per le immagini viene usato il formato impostato con returnSize (predefinito full); per gli altri file, il loro URL. |
Link
Il campo link restituisce un oggetto con URL e gli attributi:
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 %}
Icona
Il campo icona restituisce un oggetto con le chiavi set, subSet e icon. Usate le funzioni helper bs_render_icon() e bs_icon() per generare l’SVG:
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() stampa direttamente l’SVG. bs_icon() lo restituisce come stringa.
Attributi
Il tipo di campo degli attributi restituisce un array di coppie {attribute, value} da renderizzare come attributi HTML. Usate bs_render_data_attributes() per stamparli:
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() stampa direttamente gli attributi. bs_data_attributes() restituisce la stringa.
Gruppo
I campi gruppo antepongono il nome del gruppo agli ID degli attributi secondari. Usate bs_get_group() per estrarre i campi del gruppo in un array ordinato:
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>
Rimuove il prefisso del gruppo dalle chiavi degli attributi. Ad esempio, $a['settings_title'] diventa $group['title'].
L’helper funziona anche quando il gruppo proviene da un campo personalizzato riutilizzato:
{
"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>
Ripetitore
Scorre gli elementi del ripetitore:
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 %}