Vai al contenuto

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.

JSON
{
  "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.

JSON
{
  "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:

Text
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.

JSON
{
  "blockstudio": {
    "island": true
  }
}

true e "hydrate" indicano entrambi un’isola idratata. "dynamic" indica un’isola dinamica.

JSON
{
  "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:

JSON
{
  "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:

  1. il percorso esplicito island.placeholder
  2. placeholder.php
  3. placeholder.blade.php
  4. placeholder.twig
  5. placeholder.html
  6. il template normale con i flag del segnaposto
PHP
<div class="cart-count-placeholder">
  Loading cart...
</div>

Se non esiste alcun file di segnaposto, usate i flag del template nel template normale:

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

  • isIsland
  • isIslandPlaceholder
  • isIslandFragment
  • islandPhase

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:

  1. raccoglie tutti i marcatori pronti
  2. elimina le coppie duplicate di nome del blocco, attributi e firma
  3. invia un’unica richiesta REST raggruppata
  4. sostituisce ciascun segnaposto con il frammento restituito
  5. invia blockstudio:island:rendered
  6. 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:

JavaScript
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.

JSON
{
  "blockstudio": {
    "island": {
      "mode": "dynamic",
      "cache": true
    }
  }
}

true usa una cache globale di breve durata. Usate la forma oggetto per un controllo esplicito:

JSON
{
  "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:

PHP
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:

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

PHP
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:

PHP
blockstudio/islands/is_island
blockstudio/islands/mode
blockstudio/islands/attributes
blockstudio/islands/marker_tag
blockstudio/islands/marker_attributes
blockstudio/islands/placeholder

Endpoint e rendering:

PHP
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:

PHP
blockstudio/islands/endpoint_url
blockstudio/islands/loading

Firme:

PHP
blockstudio/islands/signature_payload
blockstudio/islands/signature
blockstudio/islands/verify_signature

Azioni del ciclo di vita:

PHP
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.