Isole
Le isole a blocchi consentono a un blocco di mantenere la normale pipeline di rendering Blockstudio, spostando l’output specifico della richiesta fuori dalla risposta iniziale HTML.
È utile quando una pagina deve essere memorizzata aggressivamente nella cache, ma un blocco dipende comunque dal visitatore corrente, dalla sessione, dal carrello, dalle autorizzazioni o da un altro contesto della richiesta in tempo reale.
I blocchi Blockstudio sono comunque blocchi WordPress dinamici. Le isole non li trasformano in HTML statici precompilati. Invece, Blockstudio modifica ciò che viene renderizzato alla prima richiesta:
- le isole idratate renderizzano il normale HTML sicuro per la cache e ricevono un evento di montaggio
- le isole dinamiche renderizzano prima un segnaposto sicuro per la cache, poi recuperano il frammento reale dal browser del visitatore
Modalità
Isole idratate
Usate un’isola idratata quando l’output del server è sicuro per la cache e il blocco ha bisogno solo di un segnale di montaggio nel frontend.
{
"name": "acme/tabs",
"blockstudio": {
"island": "hydrate"
}
}
Il HTML completo del blocco è presente nella risposta iniziale. Il runtime dell’isola non effettua una richiesta REST per ottenerlo. Invia blockstudio:island:hydrate sul marcatore, così il codice frontend può associarvi un comportamento.
Isole dinamiche
Usate un’isola dinamica quando l’output reale del blocco deve essere renderizzato nel contesto della richiesta del visitatore.
{
"name": "acme/cart-count",
"blockstudio": {
"island": "dynamic"
}
}
La risposta iniziale contiene solo un segnaposto. Il browser raggruppa tutte le isole dinamiche pronte in un’unica richiesta a:
POST /wp-json/blockstudio/v1/island/render
L’endpoint renderizza solo i blocchi Blockstudio registrati che sono dinamici e hanno blockstudio.island.mode impostato su dynamic.
Configurazione
Il valore island può essere una forma abbreviata o un oggetto.
{
"blockstudio": {
"island": true
}
}
true e "hydrate" indicano entrambi un’isola idratata. "dynamic" indica un’isola dinamica.
{
"blockstudio": {
"island": {
"mode": "dynamic",
"tag": "section",
"attributes": ["productId", "variant"],
"placeholder": "cart-placeholder.php",
"loading": "visible",
"event": "cart:updated",
"cache": {
"ttl": 60,
"per": "user"
}
}
}
}
| Proprietà | Tipo | Predefinito | Descrizione |
|---|---|---|---|
mode |
"hydrate" o "dynamic" |
"hydrate" |
Modalità island. |
tag |
string |
"div" |
Tag wrapper del marcatore. |
attributes |
string[] |
tutti gli attributi del blocco | Elenco di attributi consentiti inviati alle richieste dei frammenti dinamici. |
placeholder |
string |
rilevato automaticamente | Percorso relativo del modello del segnaposto. |
loading |
"eager" o "visible" |
"eager" |
Quando il runtime deve recuperare un’island dinamica. |
event |
string |
non impostato | Nome dell’evento della finestra che aggiorna un’island dinamica. |
context |
boolean |
false |
Firma e ripristino dell’ID e del tipo di articolo della pagina interrogata per i frammenti dinamici. |
cache |
boolean o object |
false |
Criterio facoltativo per la cache dei frammenti. |
Contesto della pagina
I frammenti dinamici normalmente vengono visualizzati indipendentemente dal contenitore della pagina. Scegliete di usare l’identità della pagina se il blocco legge impostazioni specifiche della pagina o contenuti correlati:
{
"blockstudio": {
"island": {
"mode": "dynamic",
"context": true,
"cache": { "ttl": 60, "per": "global" }
}
}
}
Il marcatore include postId e postType della pagina interrogata in data-bs-island-context. Entrambi i valori sono firmati con il nome del blocco e gli attributi consentiti usando il segreto del sito che fornisce il servizio. Non possono essere modificati né aggiunti a una richiesta senza invalidare la firma. Il runtime li invia con la richiesta di frammenti esistente in batch, inclusi gli aggiornamenti visibili e quelli attivati da eventi. Funziona anche con bs_render_block(), bs_block() e i tag dei blocchi.
Durante il rendering del frammento, $block['postId'], $block['postType'],
get_the_ID() e get_queried_object_id() fanno riferimento a quella pagina. WordPress le variabili globali di query
e post vengono ripristinate dopo il rendering, anche in caso di eccezione.
Questa è la pagina interrogata, non un elemento all’interno di un Query Loop. Non riproduce
parametri URL arbitrari né ripristina l’URL della richiesta originale URL. Usate
get_permalink($block['postId']) quando vi serve l’URL canonico URL della pagina HTML.
Gli archivi e i rendering senza un post interrogato non inviano alcuna identità della pagina.
Prima di consultare la cache dei frammenti, l’endpoint verifica che la pagina esista ancora, abbia il tipo di articolo firmato e sia leggibile dal visitatore corrente. Una firma valida non elude la protezione degli articoli privati o protetti da password, l’idoneità dell’island, gli elenchi di attributi consentiti o i controlli delle autorizzazioni del blocco. Quando presente, l’identità della pagina fa sempre parte della chiave della cache dei frammenti, quindi blocchi e attributi uguali su pagine diverse non condividono mai un frammento. Usate per: "user" oppure non memorizzate nella cache i frammenti se l’output dipende anche dal visitatore.
Se context viene omesso o impostato su false, i marcatori esistenti e il comportamento senza contesto restano invariati. Non inserite dati riservati nel marcatore pubblico.
Segnaposto dinamici
Le isole dinamiche devono renderizzare un segnaposto sicuro per una cache condivisa dell’intera pagina. Non includete dati specifici del visitatore nel ramo del segnaposto.
Blockstudio cerca i segnaposto in questo ordine:
- il percorso esplicito
island.placeholder placeholder.phpplaceholder.blade.phpplaceholder.twigplaceholder.html- il template normale con i flag del segnaposto
<div class="cart-count-placeholder">
Loading cart...
</div>
Se non esiste alcun file di segnaposto, usate i flag del template nel template normale:
<?php if ( $isIslandPlaceholder ) : ?>
<div class="cart-count-placeholder">Loading cart...</div>
<?php else : ?>
<div class="cart-count">
<?php echo esc_html( acme_cart_count() ); ?>
</div>
<?php endif; ?>
Gli stessi valori sono disponibili nei template PHP, Twig e Blade:
isIslandisIslandPlaceholderisIslandFragmentislandPhase
islandPhase è "normal", "hydrate", "placeholder" o "fragment".
Comportamento del runtime
Blockstudio include il runtime delle isole solo quando la pagina renderizzata contiene un marcatore di isola. Le pagine senza isole non includono risorse aggiuntive per le isole JavaScript.
Per le isole dinamiche, il runtime:
- raccoglie tutti i marcatori pronti
- elimina le coppie duplicate di nome del blocco, attributi e firma
- invia un’unica richiesta REST raggruppata
- sostituisce ciascun segnaposto con il frammento restituito
- invia
blockstudio:island:rendered - invia
blockstudio:island:hydrate
Le isole loading: "eager" vengono renderizzate non appena il runtime si avvia. Le isole loading: "visible" attendono IntersectionObserver. Se più isole visibili entrano nell’area visibile insieme, vengono raggruppate in un’unica richiesta.
event aggiorna un’isola quando si attiva l’evento window indicato:
window.dispatchEvent(new Event('cart:updated'));
In caso di errore, il segnaposto rimane al suo posto e viene inviato
blockstudio:island:error.
Endpoint dei frammenti
L’endpoint delle isole è pubblico, ma non è un’API generica per il rendering dei blocchi API.
Ogni marcatore contiene:
- il nome del blocco
- gli attributi consentiti
- una firma generata dal server
L’endpoint esegue il rendering solo quando:
- il blocco è registrato
- il blocco è un blocco WordPress dinamico
- il blocco è contrassegnato come isola dinamica Blockstudio
- gli attributi ricevuti superano i controlli dello schema del blocco e dell’elenco di attributi consentiti per l’isola
- la firma corrisponde al nome normalizzato del blocco e ai suoi attributi
Le firme vengono generate al momento del rendering sul sito WordPress che serve la richiesta, usando i salt di quel sito e il payload dell’isola. Non vengono esportate né incorporate in un tema.
Le risposte dell’endpoint sono contrassegnate come non memorizzabili nella cache. Se volete memorizzare nella cache i frammenti, usate island.cache.
Cache dei frammenti
Per impostazione predefinita, i frammenti dinamici non vengono memorizzati nella cache.
{
"blockstudio": {
"island": {
"mode": "dynamic",
"cache": true
}
}
}
true usa una cache globale di breve durata. Usate la forma oggetto per un controllo esplicito:
{
"cache": {
"ttl": 120,
"per": "user"
}
}
per: "global" condivide un frammento memorizzato nella cache per lo stesso blocco, gli stessi attributi e lo stesso contesto di pagina con attivazione esplicita.
per: "user" varia la cache in base all’ID utente WordPress corrente.
Rendering programmatico
Le isole funzionano ovunque vengano renderizzati blocchi Blockstudio:
bs_render_block([
'name' => 'acme/cart-count',
'data' => ['productId' => 42],
]);
echo bs_block([
'name' => 'acme/cart-count',
'data' => ['productId' => 42],
]);
Funzionano anche tramite i tag dei blocchi:
<bs:acme-cart-count product-id="42" />
<block name="acme/cart-count" productId="42" />
L’output iniziale è comunque il marcatore e il segnaposto dell’isola; il runtime viene incluso quando la risposta renderizzata contiene quel marcatore.
PHP API
Blockstudio\Islands::is_island('acme/cart-count');
Blockstudio\Islands::mode('acme/cart-count');
Blockstudio\Islands::registered();
Blockstudio\Islands::marker('acme/cart-count', $attributes, $html);
marker() convalida i metadati dei blocchi. I marcatori dinamici vengono creati solo per i blocchi Blockstudio dinamici registrati con island.mode impostato su dynamic.
Hook
Rilevamento e markup:
blockstudio/islands/is_island
blockstudio/islands/mode
blockstudio/islands/attributes
blockstudio/islands/marker_tag
blockstudio/islands/marker_attributes
blockstudio/islands/placeholder
Endpoint e rendering:
blockstudio/islands/allowed
blockstudio/islands/max_per_request
blockstudio/islands/request_attributes
blockstudio/islands/fragment
blockstudio/islands/max_per_request modifica il numero massimo di isole dinamiche accettate da una singola richiesta raggruppata all’endpoint. Il valore predefinito è 50.
Configurazione del runtime:
blockstudio/islands/endpoint_url
blockstudio/islands/loading
Firme:
blockstudio/islands/signature_payload
blockstudio/islands/signature
blockstudio/islands/verify_signature
Azioni del ciclo di vita:
blockstudio/islands/registered
blockstudio/islands/rendered
Quando non usare le isole
Non usate un’isola dinamica per contenuti essenziali per la SEO. I frammenti delle isole dinamiche non sono presenti nella risposta iniziale HTML e non sono destinati all’indicizzazione.
Usate il rendering normale o un’isola idratata quando il contenuto è sicuro per la cache e deve essere visibile ai crawler. Usate un’isola dinamica solo per contenuti che possono arrivare dopo lo shell della pagina, come i dati dell’account UI, lo stato del carrello, i consigli personalizzati o i controlli con accesso limitato dalle autorizzazioni.