Vai al contenuto

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

PHP
<h1><?php echo $attributes['message']; ?></h1>
<h1><?php echo $a['message']; ?></h1>

Twig

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:

PHP
// 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():

PHP
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 min contiene le righe iniziali.
  • I valori di primo livello e blockstudio.attributes vengono 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 returnFormat pari a label restituisce 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
<?php if ($a['message']) : ?>
  <h1><?php echo $a['message']; ?></h1>
<?php endif; ?>

Twig

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
<?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

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.

Il campo link restituisce un oggetto con URL e gli attributi:

PHP

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

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
<?php if ($a['icon']) : ?>
  <div class="icon">
    <?php bs_render_icon($a['icon']); ?>
  </div>
<?php endif; ?>

Twig

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

PHP
<div <?php bs_render_data_attributes($a['attributes']); ?>>
  Content
</div>

Twig

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
<?php $group = bs_get_group($a, 'settings'); ?>
<h1><?php echo $group['title']; ?></h1>
<p><?php echo $group['description']; ?></p>

Twig

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:

JSON
{
  "name": "section-header",
  "attributes": [
    {
      "id": "section-header",
      "type": "group",
      "attributes": [
        { "id": "kicker", "type": "text" },
        { "id": "title", "type": "text" }
      ]
    }
  ]
}
JSON
{
  "blockstudio": {
    "attributes": [
      { "type": "custom/section-header" }
    ]
  }
}
Twig
{% 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
<?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

Twig
{% for item in a.items %}
  <div class="item">
    <h3>{{ item.title }}</h3>
    <p>{{ item.description }}</p>
  </div>
{% endfor %}

Ricettario dei modelli di campo