Contesto e comunicazione tra blocchi
La maggior parte dei blocchi è autonoma. Ha i propri campi e il proprio template, e non si cura di ciò che la circonda. Alcuni componenti, però, sono naturalmente gerarchici: una griglia di schede in cui il genitore controlla il numero di colonne e la spaziatura, una tabella dei prezzi in cui il genitore imposta la valuta, un wrapper di sezione che indica ai figli se usare un tema chiaro o scuro.
WordPress offre un contesto del blocco API a questo scopo. Un blocco genitore espone alcuni dei propri dati e i blocchi figlio vi si iscrivono. Quando il genitore cambia, i figli si aggiornano automaticamente. Blockstudio semplifica notevolmente il processo: non è necessario configurare providesContext. Ogni blocco Blockstudio fornisce automaticamente tutti i propri attributi come contesto. Ai blocchi figlio basta aggiungere una riga nel loro block.json per iscriversi.
Questa guida illustra quattro modelli di componenti per casi reali che usano il contesto, ciascuno dei quali mostra una diversa esigenza di comunicazione.
Come funziona il contesto in Blockstudio
In WordPress standard, è necessario associare esplicitamente ogni attributo del genitore a una chiave di contesto in providesContext, quindi elencare quelle chiavi nel usesContext del figlio. Blockstudio elimina del tutto il primo passaggio.
Blocco genitore: non è necessaria alcuna configurazione. Ogni blocco Blockstudio fornisce automaticamente tutti i propri attributi con il nome del blocco.
Blocco figlio: aggiungete usesContext con il nome del blocco genitore:
{
"usesContext": ["my-theme/parent-block"]
}
Template del blocco figlio: accedete agli attributi del genitore tramite $context (o la forma abbreviata $c):
<?php $parent = $context['my-theme/parent-block']; ?>
<p>Parent says: <?php echo esc_html( $parent['message'] ); ?></p>
Questa è tutta la configurazione. Nessun providesContext nel genitore, nessuna associazione di attributi, nessun codice di registrazione. Il figlio riceve tutti gli attributi trasformati del genitore: i campi multimediali vengono risolti nei dati degli allegati, i campi di selezione rispettano returnFormat e i ripetitori vengono espansi completamente.
Due tipi di contesto
Blockstudio mette a disposizione due variabili di contesto nei template, che servono a scopi diversi:
| Variabile | Contiene | Caso d’uso |
|---|---|---|
$context / $c |
Attributi del blocco genitore (tramite usesContext) |
Comunicazione tra componenti |
$block['context'] / $b['context'] |
Dati del ciclo WordPress (postId, postType) |
Cicli dei blocchi di query |
Il primo serve ai blocchi per comunicare con i genitori. Il secondo serve ai blocchi all’interno di un ciclo Query che devono sapere quale articolo stanno visualizzando. Questa guida si concentra sul primo tipo.
Supporto nell’editor
Gli aggiornamenti del contesto sono reattivi nell’editor. Quando un utente modifica il valore di un campo del blocco genitore, tutti i blocchi figlio iscritti al contesto di quel genitore vengono renderizzati di nuovo automaticamente con il nuovo valore. Non è necessario aggiornare manualmente.
Wrapper di sezione
Il modello di contesto più comune: un blocco wrapper che fornisce impostazioni del tema ai blocchi figlio. Il genitore ha campi per il colore di sfondo, il colore del testo e la spaziatura interna. I figli leggono questi valori per applicare uno stile coerente.
Genitore: sezione
{
"name": "my-theme/section",
"title": "Section",
"category": "design",
"icon": "align-wide",
"description": "Section wrapper with theme settings.",
"blockstudio": {
"attributes": [
{
"id": "theme",
"type": "select",
"label": "Theme",
"default": "light",
"options": [
{ "value": "light", "label": "Light" },
{ "value": "dark", "label": "Dark" },
{ "value": "accent", "label": "Accent" }
]
},
{
"id": "spacing",
"type": "select",
"label": "Spacing",
"default": "md",
"options": [
{ "value": "sm", "label": "Small" },
{ "value": "md", "label": "Medium" },
{ "value": "lg", "label": "Large" }
]
}
]
}
}
<?php
$theme_classes = array(
'light' => 'bg-white text-gray-900',
'dark' => 'bg-gray-900 text-white',
'accent' => 'bg-indigo-600 text-white',
);
$spacing_classes = array(
'sm' => 'py-8',
'md' => 'py-16',
'lg' => 'py-24',
);
$classes = ( $theme_classes[ $a['theme'] ] ?? '' ) . ' ' . ( $spacing_classes[ $a['spacing'] ] ?? '' );
?>
<div useBlockProps class="<?php echo esc_attr( $classes ); ?>">
<InnerBlocks
allowedBlocks='<?php echo esc_attr( wp_json_encode( array( 'my-theme/section-heading', 'my-theme/section-text', 'core/columns', 'core/group' ) ) ); ?>'
/>
</div>
Figlio: titolo della sezione
{
"name": "my-theme/section-heading",
"title": "Section Heading",
"category": "design",
"icon": "heading",
"description": "Heading that adapts to section theme.",
"usesContext": ["my-theme/section"],
"parent": ["my-theme/section"],
"blockstudio": {
"attributes": [
{ "id": "text", "type": "text", "label": "Heading", "default": "Section Title" },
{
"id": "size",
"type": "select",
"label": "Size",
"default": "lg",
"options": [
{ "value": "sm", "label": "Small" },
{ "value": "lg", "label": "Large" },
{ "value": "xl", "label": "Extra Large" }
]
}
]
}
}
<?php
$section = $context['my-theme/section'] ?? array();
$theme = $section['theme'] ?? 'light';
$color_class = match ( $theme ) {
'light' => 'text-gray-900',
'dark' => 'text-white',
'accent' => 'text-white',
default => 'text-gray-900',
};
$size_class = match ( $a['size'] ) {
'sm' => 'text-2xl',
'lg' => 'text-4xl',
'xl' => 'text-6xl',
default => 'text-4xl',
};
?>
<h2 useBlockProps class="<?php echo esc_attr( "$color_class $size_class font-bold" ); ?>">
<?php echo esc_html( $a['text'] ); ?>
</h2>
Cosa dimostra: il titolo non ha un proprio campo colore. Legge dal contesto il valore theme della sezione e si adatta. Quando l’utente passa da “Light” a “Dark” nell’editor, il colore del testo del titolo si aggiorna immediatamente.
La proprietà parent nel block.json del figlio limita i punti in cui è possibile inserire il blocco. Il blocco appare nell’inseritore solo quando l’utente si trova all’interno di un blocco my-theme/section. È facoltativa, ma consigliata per i blocchi che hanno senso solo all’interno di un genitore specifico.
Figlio: testo della sezione
{
"name": "my-theme/section-text",
"title": "Section Text",
"category": "design",
"icon": "text",
"description": "Body text that adapts to section theme.",
"usesContext": ["my-theme/section"],
"parent": ["my-theme/section"],
"blockstudio": {
"attributes": [
{ "id": "text", "type": "textarea", "label": "Text", "default": "Section body text." }
]
}
}
<?php
$section = $context['my-theme/section'] ?? array();
$theme = $section['theme'] ?? 'light';
$color_class = match ( $theme ) {
'dark', 'accent' => 'text-white/80',
default => 'text-gray-600',
};
?>
<p useBlockProps class="<?php echo esc_attr( "$color_class text-lg leading-relaxed" ); ?>">
<?php echo esc_html( $a['text'] ); ?>
</p>
Ora sia il titolo che il testo rispondono al tema della sezione. L’utente sceglie un tema una sola volta nel genitore e ogni figlio si adatta.
Griglia di schede
Un blocco genitore a griglia che controlla le impostazioni di layout delle schede figlio. Il genitore definisce le colonne e la spaziatura. I figli usano questi valori per comprendere il contesto del layout e adattare di conseguenza il proprio stile.
Genitore: griglia di schede
{
"name": "my-theme/card-grid",
"title": "Card Grid",
"category": "design",
"icon": "grid-view",
"description": "Responsive card grid with configurable columns.",
"blockstudio": {
"attributes": [
{
"id": "columns",
"type": "range",
"label": "Columns",
"default": 3,
"min": 1,
"max": 4,
"step": 1
},
{
"id": "gap",
"type": "select",
"label": "Gap",
"default": "md",
"options": [
{ "value": "sm", "label": "Small" },
{ "value": "md", "label": "Medium" },
{ "value": "lg", "label": "Large" }
]
},
{
"id": "cardStyle",
"type": "select",
"label": "Card Style",
"default": "elevated",
"options": [
{ "value": "elevated", "label": "Elevated (shadow)" },
{ "value": "outlined", "label": "Outlined (border)" },
{ "value": "flat", "label": "Flat (no decoration)" }
]
}
]
}
}
<?php
$gap_class = match ( $a['gap'] ) {
'sm' => 'gap-4',
'md' => 'gap-6',
'lg' => 'gap-8',
default => 'gap-6',
};
?>
<div useBlockProps class="grid grid-cols-<?php echo esc_attr( $a['columns'] ); ?> <?php echo esc_attr( $gap_class ); ?>">
<InnerBlocks
allowedBlocks='<?php echo esc_attr( wp_json_encode( array( 'my-theme/card' ) ) ); ?>'
template='<?php echo esc_attr( wp_json_encode( array(
array( 'my-theme/card', array() ),
array( 'my-theme/card', array() ),
array( 'my-theme/card', array() ),
) ) ); ?>'
/>
</div>
Figlio: scheda
{
"name": "my-theme/card",
"title": "Card",
"category": "design",
"icon": "cover-image",
"description": "Card that inherits style from its grid parent.",
"usesContext": ["my-theme/card-grid"],
"parent": ["my-theme/card-grid"],
"blockstudio": {
"attributes": [
{ "id": "image", "type": "files", "label": "Image", "multiple": false },
{ "id": "title", "type": "text", "label": "Title", "default": "Card Title" },
{ "id": "description", "type": "textarea", "label": "Description", "default": "Card description goes here." },
{ "id": "url", "type": "link", "label": "Link" }
]
}
}
<?php
$grid = $context['my-theme/card-grid'] ?? array();
$card_style = $grid['cardStyle'] ?? 'elevated';
$style_class = match ( $card_style ) {
'elevated' => 'bg-white rounded-xl shadow-md',
'outlined' => 'bg-white rounded-xl border border-gray-200',
'flat' => 'bg-gray-50 rounded-xl',
default => 'bg-white rounded-xl shadow-md',
};
?>
<div useBlockProps class="<?php echo esc_attr( "$style_class overflow-hidden" ); ?>">
<?php if ( $a['image'] ) : ?>
<img
src="<?php echo esc_url( $a['image']['url'] ); ?>"
alt="<?php echo esc_attr( $a['image']['alt'] ); ?>"
class="w-full aspect-video object-cover" />
<?php endif; ?>
<div class="p-6">
<h3 class="text-lg font-semibold"><?php echo esc_html( $a['title'] ); ?></h3>
<p class="mt-2 text-gray-600"><?php echo esc_html( $a['description'] ); ?></p>
<?php if ( $a['url'] ) : ?>
<a href="<?php echo esc_url( $a['url']['url'] ); ?>" class="mt-4 inline-block text-indigo-600 font-medium">
<?php echo esc_html( $a['url']['title'] ?: 'Learn more' ); ?>
</a>
<?php endif; ?>
</div>
</div>
Cosa dimostra: la scheda non ha un proprio campo di stile. Legge cardStyle dal blocco genitore della griglia. Quando l’utente passa da “Elevated” a “Outlined”, tutte le schede della griglia si aggiornano contemporaneamente. In questo modo le schede mantengono uno stile visivamente coerente senza che l’utente debba aggiornarle una per una.
L’attributo template su <InnerBlocks> precompila la griglia con tre schede, fornendo all’utente un punto di partenza.
Tabella dei prezzi
Un modello più avanzato in cui il genitore fornisce logiche aziendali condivise (valuta, periodo di fatturazione) che i figli usano per la visualizzazione. In questo modo si evita di duplicare gli stessi campi in ogni fascia di prezzo.
Genitore: tabella dei prezzi
{
"name": "my-theme/pricing-table",
"title": "Pricing Table",
"category": "text",
"icon": "money-alt",
"description": "Pricing comparison with shared currency and billing settings.",
"blockstudio": {
"attributes": [
{
"id": "currency",
"type": "select",
"label": "Currency",
"default": "usd",
"options": [
{ "value": "usd", "label": "USD ($)" },
{ "value": "eur", "label": "EUR (\u20ac)" },
{ "value": "gbp", "label": "GBP (\u00a3)" }
]
},
{
"id": "period",
"type": "select",
"label": "Billing Period",
"default": "month",
"options": [
{ "value": "month", "label": "Monthly" },
{ "value": "year", "label": "Yearly" }
]
}
]
}
}
<div useBlockProps class="grid grid-cols-3 gap-6 items-start">
<InnerBlocks
allowedBlocks='<?php echo esc_attr( wp_json_encode( array( 'my-theme/pricing-tier' ) ) ); ?>'
template='<?php echo esc_attr( wp_json_encode( array(
array( 'my-theme/pricing-tier', array( 'name' => 'Starter', 'price' => 9 ) ),
array( 'my-theme/pricing-tier', array( 'name' => 'Pro', 'price' => 29, 'highlighted' => true ) ),
array( 'my-theme/pricing-tier', array( 'name' => 'Enterprise', 'price' => 99 ) ),
) ) ); ?>'
/>
</div>
Figlio: fascia di prezzo
{
"name": "my-theme/pricing-tier",
"title": "Pricing Tier",
"category": "text",
"icon": "tag",
"description": "Single pricing tier that reads currency from parent.",
"usesContext": ["my-theme/pricing-table"],
"parent": ["my-theme/pricing-table"],
"blockstudio": {
"attributes": [
{ "id": "name", "type": "text", "label": "Tier Name", "default": "Plan" },
{ "id": "price", "type": "number", "label": "Price", "default": 0 },
{ "id": "highlighted", "type": "toggle", "label": "Highlighted", "default": false },
{
"id": "features",
"type": "repeater",
"label": "Features",
"attributes": [
{ "id": "text", "type": "text", "label": "Feature" }
]
}
]
}
}
<?php
$table = $context['my-theme/pricing-table'] ?? array();
$currency = $table['currency'] ?? 'usd';
$period = $table['period'] ?? 'month';
$symbols = array(
'usd' => '$',
'eur' => "\u{20AC}",
'gbp' => "\u{00A3}",
);
$symbol = $symbols[ $currency ] ?? '$';
$period_label = $period === 'year' ? '/year' : '/month';
$border_class = $a['highlighted'] ? 'border-2 border-indigo-600' : 'border border-gray-200';
?>
<div useBlockProps class="<?php echo esc_attr( "rounded-xl p-8 $border_class" ); ?>">
<h3 class="text-lg font-semibold"><?php echo esc_html( $a['name'] ); ?></h3>
<div class="mt-4">
<span class="text-4xl font-bold"><?php echo esc_html( $symbol . $a['price'] ); ?></span>
<span class="text-gray-500"><?php echo esc_html( $period_label ); ?></span>
</div>
<?php if ( ! empty( $a['features'] ) ) : ?>
<ul class="mt-6 space-y-3">
<?php foreach ( $a['features'] as $feature ) : ?>
<li class="flex items-center gap-2">
<span class="text-indigo-600">✓</span>
<?php echo esc_html( $feature['text'] ); ?>
</li>
<?php endforeach; ?>
</ul>
<?php endif; ?>
</div>
Cosa dimostra: il simbolo della valuta e il periodo di fatturazione vengono definiti una sola volta nella tabella dei prezzi ed ereditati da ogni fascia. Quando l’utente passa da USD a EUR, il simbolo della valuta si aggiorna contemporaneamente in tutte e tre le fasce. Senza il contesto, sarebbe necessario duplicare il campo valuta in ogni fascia e mantenerlo sincronizzato manualmente.
Contesto del ciclo Query
Esiste un tipo di contesto distinto che WordPress fornisce all’interno dei cicli dei blocchi Query. Quando un blocco viene renderizzato all’interno di un ciclo, $block['context'] (o $b['context']) contiene i dati dell’articolo dell’iterazione corrente:
<?php
$loop_post_id = $block['context']['postId'];
$loop_post_type = $block['context']['postType'];
?>
<article useBlockProps>
<h2><?php echo esc_html( get_the_title( $loop_post_id ) ); ?></h2>
<p><?php echo esc_html( get_the_excerpt( $loop_post_id ) ); ?></p>
<a href="<?php echo esc_url( get_permalink( $loop_post_id ) ); ?>">Read more</a>
</article>
È diverso dal contesto del blocco genitore ($context / $c). Il contesto del ciclo è fornito dal core di WordPress e contiene solo postId e postType. Per questo non serve usesContext nel proprio block.json. Blockstudio iscrive automaticamente ogni blocco a postId e postType.
Quando è utile il contesto del ciclo: schede di articoli personalizzate all’interno di blocchi Query, blocchi che mostrano i metadati degli articoli o qualsiasi blocco che deve essere renderizzato in modo diverso per ogni articolo del ciclo.
È possibile accedere anche ai dati dell’articolo della pagina esterna, indipendentemente dal contesto del ciclo:
$outer_post_id = $block['postId']; // always the current page
$loop_post_id = $block['context']['postId']; // current loop iteration
Contesto annidato
Il contesto si propaga attraverso l’intero albero dei blocchi, non solo di un livello. Se il blocco A contiene il blocco B e quest’ultimo contiene il blocco C, C può iscriversi al contesto di A. Questo è possibile perché WordPress propaga il contesto a ogni livello di InnerBlocks.
my-theme/section (theme: "dark")
└── core/columns
└── core/column
└── my-theme/section-heading (reads section context)
Il titolo non deve essere un figlio diretto della sezione. Può essere annidato all’interno di blocchi core (colonne, gruppi e così via) e ricevere comunque il contesto della sezione. L’iscrizione a usesContext funziona a qualsiasi profondità.
Più genitori
Un figlio può iscriversi a più genitori:
{
"usesContext": ["my-theme/section", "my-theme/card-grid"]
}
<?php
$section = $context['my-theme/section'] ?? array();
$grid = $context['my-theme/card-grid'] ?? array();
$theme = $section['theme'] ?? 'light';
$cardStyle = $grid['cardStyle'] ?? 'elevated';
?>
Se un genitore non si trova nell’albero degli antenati, la relativa chiave sarà assente da $context. Quando leggete i valori di contesto, usate sempre l’operatore di coalescenza dei valori nulli (??) oppure verificate isset(), nel caso in cui il blocco venga usato al di fuori del genitore previsto.
Programmazione difensiva
I blocchi che usano il contesto dovrebbero sempre gestire il caso in cui il genitore sia assente. Un utente potrebbe inserire il blocco al di fuori del genitore previsto oppure il blocco genitore potrebbe non avere un valore impostato per un determinato campo.
<?php
// Always provide defaults
$section = $context['my-theme/section'] ?? array();
$theme = $section['theme'] ?? 'light';
$spacing = $section['spacing'] ?? 'md';
?>
Se volete imporre che un figlio appaia solo all’interno del suo genitore, aggiungete la proprietà parent:
{
"parent": ["my-theme/section"]
}
Questo rimuove il blocco dall’inseritore quando l’utente non si trova all’interno di un blocco my-theme/section. Senza parent, il blocco appare ovunque e spetta al vostro template gestire con attenzione l’assenza del contesto.
Usate parent per i blocchi privi di significato al di fuori del loro contenitore (fasce di prezzo, elementi della griglia di schede). Evitatelo per i blocchi che funzionano da soli ma beneficiano di uno stile aggiuntivo fornito da un genitore (titoli di sezione che si possono usare anche in modo indipendente).
Suggerimenti
Il contesto è di sola lettura. I figli non possono modificare gli attributi del genitore tramite il contesto. I dati fluiscono verso il basso, mai verso l’alto. Se un figlio deve comunicare qualcosa al genitore, serve un approccio diverso (ad esempio uno stato condiviso lato server tramite l’API Interattività o i metadati dell’articolo).
Vengono forniti tutti gli attributi. Blockstudio fornisce tutti gli attributi del blocco genitore, non solo quelli selezionati. Ciò significa che il figlio può accedere a qualsiasi campo definito dal genitore. Se in seguito il genitore aggiunge un nuovo campo, i figli vi accedono automaticamente senza modifiche alla configurazione.
Valori trasformati. I valori di contesto passano attraverso la pipeline di trasformazione degli attributi di Blockstudio. I campi file contengono tutti i dati dell’allegato (url, alt, width, height), i campi di selezione rispettano returnFormat e i ripetitori vengono espansi ricorsivamente. Si ottiene la stessa struttura dati di $a nel template del genitore.
Reattività nell’editor. Quando un utente modifica un campo del genitore nell’editor, i blocchi figlio vengono renderizzati di nuovo automaticamente. Questo sfrutta la propagazione del contesto integrata di WordPress con un React useEffect che rileva i cambiamenti di contesto e attiva un nuovo rendering lato server del figlio.
Mantenete snello il contesto. Sebbene Blockstudio fornisca automaticamente tutti gli attributi del genitore, i figli dovrebbero leggere solo i valori di cui hanno effettivamente bisogno. Non è una questione di prestazioni (i dati sono già presenti), ma di chiarezza del codice. Documentate i campi del genitore da cui dipende un figlio, affinché i futuri sviluppatori conoscano la relazione.
Passaggi successivi
- Riferimento al contesto: variabili dei template, contesto dei cicli e struttura dati
$block. - InnerBlocks: il componente
<InnerBlocks />,allowedBlocks, i template e il filtro wrapper del frontend. - Guida all’interattività: per la reattività lato client tra blocchi (l’API Interattività gestisce ciò che il contesto non può fare: comunicazione dal figlio al genitore, stato condiviso tra blocchi e aggiornamenti avviati dall’utente).