Vai al contenuto

Frammenti personalizzati nelle pagine memorizzate nella cache

Una pagina servita da una cache statica è uguale per tutti. È proprio questo lo scopo della cache, ma anche il problema: l’intestazione dovrebbe dire “Ciao, Ada” a un cliente connesso e l’icona del carrello dovrebbe mostrare tre articoli. Se il template mostra contenuti diversi in base all’utente corrente, la cache conserva il saluto di un visitatore per tutti oppure deve escludere del tutto la pagina.

Le isole dinamiche di Blockstudio separano questi due aspetti. Il HTML memorizzato nella cache contiene un segnaposto sicuro per la cache. Dopo il caricamento della pagina, un piccolo runtime chiede a WordPress il frammento personalizzato nella richiesta del visitatore e lo inserisce al posto del segnaposto. La pagina resta memorizzabile nella cache e solo il frammento è dinamico.

Questa guida crea due isole, un saluto e il conteggio del carrello, e illustra il contenuto della pagina memorizzata nella cache, l’aspetto della richiesta del frammento e il modo in cui l’endpoint identifica il visitatore. È complementare a Servire WordPress come pagina staticaHTML.

Come funziona un’isola dinamica

  1. Il blocco renderizza il proprio segnaposto all’interno di un elemento marcatore. Il marcatore contiene il nome del blocco, gli attributi consentiti e una firma generata dal server.
  2. Poiché la pagina renderizzata contiene un marcatore, Blockstudio inserisce il runtime delle isole. Le pagine senza isole non includono alcun runtime delle isole JavaScript.
  3. Il runtime raccoglie i marcatori pronti e invia a /wp-json/blockstudio/v1/island/render un’unica richiesta POST in batch.
  4. L’endpoint verifica ogni firma, renderizza il blocco nel contesto della richiesta del visitatore e restituisce i frammenti.
  5. Il runtime sostituisce ogni segnaposto e invia gli eventi.

Nell’editor dei blocchi, il blocco viene renderizzato normalmente, senza segnaposto.

Passaggio 1: il blocco di saluto

Create il blocco con tre file:

Codice
blocks/
└── greeting/
    ├── block.json
    ├── placeholder.php
    └── index.php
JSON
{
  "apiVersion": 3,
  "name": "acme/greeting",
  "title": "Greeting",
  "category": "widgets",
  "icon": "admin-users",
  "description": "Account link that greets signed-in visitors.",
  "blockstudio": {
    "island": {
      "mode": "dynamic",
      "tag": "span",
      "attributes": ["guestLabel"],
      "cache": {
        "ttl": 300,
        "per": "user"
      }
    },
    "attributes": [
      { "id": "guestLabel", "type": "text", "label": "Guest label", "default": "Sign in" }
    ]
  }
}

mode: "dynamic" trasforma il blocco in un’isola con una richiesta di frammento. tag imposta l’elemento marcatore, in modo che l’isola possa essere incorporata in linea in una barra di navigazione. attributes è l’elenco degli attributi del blocco consentiti che vengono trasmessi con la richiesta del frammento; tutto ciò che non è presente nell’elenco non viene né inviato né firmato. cache è descritto più avanti.

La pagina memorizzata nella cache contiene il segnaposto. Deve essere sicuro da mostrare a ogni visitatore, quindi non contiene dati dell’utente. Un link “Account” va bene per tutti:

PHP
<a href="<?php echo esc_url( home_url( '/account/' ) ); ?>">Account</a>

Il template principale renderizza il frammento effettivo:

PHP
<?php
$user = wp_get_current_user();
?>
<?php if ( $user->exists() ) : ?>
  <a href="<?php echo esc_url( home_url( '/account/' ) ); ?>">
    <?php echo esc_html( sprintf( 'Hi, %s', $user->display_name ) ); ?>
  </a>
<?php else : ?>
  <a href="<?php echo esc_url( wp_login_url() ); ?>">
    <?php echo esc_html( $a['guestLabel'] ); ?>
  </a>
<?php endif; ?>

È possibile mostrare contenuti diversi in base all’utente corrente: questo template viene eseguito solo per la richiesta del frammento, mai per la pagina memorizzata nella cache.

Inseritelo nel punto in cui viene renderizzata l’intestazione:

PHP
<?php echo bs_block( array( 'name' => 'acme/greeting' ) ); ?>

Vanno bene anche i tag dei blocchi: <bs:acme-greeting /> oppure <block name="acme/greeting" />.

Passaggio 2: il contenuto della pagina memorizzata nella cache

Renderizzato sul server, il blocco produce solo il marcatore e il segnaposto:

HTML
<span data-bs-island="acme/greeting" data-bs-island-mode="dynamic" data-bs-island-phase="placeholder" data-bs-island-props="{&quot;guestLabel&quot;:&quot;Sign in&quot;}" data-bs-island-signature="a7311ba9f6abf3c993edfdd7d49d2fa23bfa068f715b96637c35ef30de8b2043" data-bs-island-loading="eager"><!--blockstudio/acme/greeting--><a href="https://example.com/account/">Account</a>
</span>

Renderizzate il blocco una volta come visitatore anonimo e una volta come utente connesso: le due stringhe sono identiche a livello di byte. Questa è proprio la proprietà richiesta da una prerenderizzazione statica con serveLoggedIn attivato: chiunque avvii il rendering, il documento memorizzato resta uguale e non può contenere dati personali.

Passaggio 3: la richiesta del frammento

Il runtime invia tutte le isole pronte in un’unica richiesta:

JSON
{
    "islands": [
        {
            "clientId": "a1",
            "name": "acme/greeting",
            "attributes": {
                "guestLabel": "Sign in"
            },
            "signature": "a7311ba9f6abf3c993edfdd7d49d2fa23bfa068f715b96637c35ef30de8b2043"
        }
    ]
}

La risposta è indicizzata per clientId. Per un visitatore connesso:

JSON
{
    "a1": "<!--blockstudio/acme/greeting-->  <a href=\"https://example.com/account/\">\n    Hi, Ada  </a>\n"
}

Una voce che non supera la verifica restituisce un codice di errore al posto di HTML, senza interrompere il resto del batch. In questo caso, la seconda voce ha modificato guestLabel senza una firma corrispondente e la terza ha indicato un blocco che non è un’isola dinamica:

JSON
{
    "a1": "<!--blockstudio/acme/greeting-->  <a href=\"https://example.com/wp-login.php\">\n    Sign in  </a>\n",
    "a2": {
        "error": "blockstudio_island_invalid_signature"
    },
    "a3": {
        "error": "blockstudio_island_not_allowed"
    }
}

Ogni risposta include Cache-Control: no-store, no-cache, must-revalidate, max-age=0, Pragma: no-cache e X-Robots-Tag: noindex. L’endpoint si trova sotto /wp-json, che la prerenderizzazione statica esclude sempre, perciò né la cache dell’origine né una CDN che rispetti le intestazioni dell’origine memorizzeranno un frammento.

Chi è il visitatore

Il runtime invia la richiesta con credentials: 'same-origin', quindi il browser include il cookie di accesso WordPress. Normalmente, WordPress REST API ignora l’autenticazione tramite cookie senza un nonce, che non può essere incluso in una pagina memorizzata nella cache. L’endpoint delle isole gestisce direttamente questo caso: per una richiesta browser dalla stessa origine, convalida il cookie logged_in e ripristina l’utente prima del rendering.

L’origine viene determinata dall’intestazione Sec-Fetch-Site e, se presente, dall’intestazione Origin confrontata con home_url(). Una richiesta proveniente da un’altra origine che contiene per caso il cookie viene renderizzata come anonima, quindi una richiesta da un altro sito non renderizza mai il frammento personale di un visitatore. In pratica:

Richiesta Viene renderizzata come
Richiesta fetch dalla stessa origine con cookie di accesso valido utente connesso
Richiesta cross-origin con lo stesso cookie anonimo
Nessun cookie anonimo

Di quale pagina si tratta?

Aggiungete "context": true a blockstudio.island quando il frammento ha bisogno dell’identità della propria pagina. Il marker firma quindi l’ID e il tipo di post della pagina oggetto della query insieme agli attributi. Nel frammento, $block['postId'], $block['postType'], get_the_ID() e get_queried_object_id() fanno riferimento a quella pagina. All’interno di un Query Loop si tratta comunque della pagina esterna oggetto della query, non dell’elemento del loop.

Il contesto della pagina è facoltativo ed è incluso anche nella chiave della cache dei frammenti. L’endpoint verifica di nuovo l’accesso, anche per i frammenti memorizzati nella cache, quindi un contrassegno firmato non espone una pagina che nel frattempo è diventata privata o protetta da password. Consultate Contesto della pagina per i dettagli sulla configurazione e sulla sicurezza. Non vengono riprodotti parametri URL arbitrari né parametri di query.

Passaggio 4: un conteggio del carrello che si aggiorna da solo

La seconda isola mostra l’altro stile di segnaposto e due opzioni del runtime. Invece di usare un file separato per il segnaposto, il template verifica $isIslandPlaceholder:

JSON
{
  "apiVersion": 3,
  "name": "acme/cart-count",
  "title": "Cart Count",
  "category": "widgets",
  "icon": "cart",
  "description": "Number of items in the visitor's cart.",
  "blockstudio": {
    "island": {
      "mode": "dynamic",
      "loading": "visible",
      "event": "acme:cart-updated"
    },
    "attributes": []
  }
}
PHP
<?php
$count = (int) apply_filters( 'acme/cart_count', 0 );
?>
<?php if ( $isIslandPlaceholder ) : ?>
  <a href="/cart/" class="cart-count">Cart</a>
<?php else : ?>
  <a href="/cart/" class="cart-count">
    Cart <span class="cart-count__badge"><?php echo esc_html( (string) $count ); ?></span>
  </a>
<?php endif; ?>

Gli stessi flag sono disponibili in tutti i linguaggi dei template: isIsland, isIslandPlaceholder, isIslandFragment e islandPhase ("normal", "hydrate", "placeholder" o "fragment"). In questo caso, il conteggio proviene da un filtro acme/cart_count valorizzato dal codice del vostro negozio; con valore 3, l’endpoint restituisce:

JSON
{"c1":"<!--blockstudio/acme/cart-count-->  <a href=\"/cart/\" class=\"cart-count\">\n    Cart <span class=\"cart-count__badge\">3</span>\n  </a>\n"}

loading: "visible" rimanda la richiesta finché il marcatore non entra nel viewport, usando IntersectionObserver. Le isole visibili contemporaneamente vengono comunque raggruppate in un’unica richiesta. event specifica un evento della finestra che recupera nuovamente l’isola, quindi dopo una chiamata per aggiungere un articolo al carrello, allo script basta inviare una notifica:

JavaScript
window.dispatchEvent(new Event('acme:cart-updated'));

Reagire nel codice frontend

Gli eventi risalgono dal marker, quindi un solo listener su document copre tutte le isole. event.detail.name contiene il nome del blocco:

JavaScript
document.addEventListener('blockstudio:island:rendered', (event) => {
  if (event.detail.name !== 'acme/cart-count') return;
  event.target.querySelector('.cart-count__badge')?.classList.add('is-fresh');
});

document.addEventListener('blockstudio:island:error', (event) => {
  console.warn('Island failed', event.detail.name, event.detail.error);
});

Dopo uno scambio, il runtime invia blockstudio:island:rendered, quindi blockstudio:island:hydrate. In caso di errore, il placeholder resta al suo posto e viene attivato blockstudio:island:error. Le isole idratate ("island": "hydrate") saltano del tutto la richiesta: il loro HTML completo è già nella pagina e ricevono solo l’evento hydrate, ideale per blocchi interattivi compatibili con la cache, come le schede.

Caching dei frammenti

Per impostazione predefinita, i frammenti vengono renderizzati a ogni richiesta. Il saluto qui sopra attiva una cache di breve durata:

JSON
{
  "cache": {
    "ttl": 300,
    "per": "user"
  }
}

per: "user" distingue il frammento memorizzato nella cache in base all’ID utente WordPress, e le richieste anonime non vengono mai memorizzate con questa impostazione, quindi due visitatori anonimi non possono condividere una voce destinata a un utente. per: "global" condivide un frammento per lo stesso blocco e gli stessi attributi, ideale per contenuti aggiornati ma non personali, come il livello delle scorte. ttl ha una durata predefinita di 60 secondi, mentre cache: true è una cache globale di 60 secondi.

Il modello di sicurezza

L’endpoint è pubblico, ma non è un renderer generico di blocchi. Esegue il rendering di una voce solo se sono soddisfatte tutte queste condizioni:

  • il blocco è registrato, dinamico e ha island.mode impostato su dynamic
  • la firma corrisponde al nome del blocco e agli attributi che superano il filtro: solo le chiavi presenti sia nello schema del blocco sia nella lista di autorizzazione dell’isola

La firma è un HMAC-SHA256 calcolato sul nome normalizzato del blocco e sui suoi attributi, con il salt auth del sito che esegue il rendering come chiave. Le firme vengono create durante il rendering su quel sito e non vengono mai incorporate in un tema. Ne conseguono due cose. Un documento renderizzato in staging contiene firme di staging, quindi eseguite il rendering dei documenti sul sito che li serve. La rotazione dei salt WordPress invalida ogni firma nei documenti archiviati, quindi svuotate il prerendering statico dopo aver ruotato un salt.

Una richiesta accetta fino a 50 isole; oltre questo limite restituisce HTTP 413. Modificate il limite con blockstudio/islands/max_per_request. Sono disponibili hook per le firme (blockstudio/islands/signature_payload, blockstudio/islands/signature, blockstudio/islands/verify_signature) per gli ambienti che necessitano di uno schema diverso.

Quando non usare un’isola

I frammenti non fanno parte dell’HTML iniziale, quindi i crawler non li vedono. Mantenete i contenuti rilevanti per la SEO nel rendering normale. Usate le isole dinamiche per ciò che può essere caricato dopo lo scheletro della pagina: link all’account, stato del carrello, consigli e controlli soggetti ad autorizzazioni. Se l’intera pagina è personale, come una dashboard dell’account, elencatene invece il percorso in dynamicPaths e renderizzatela dinamicamente.

Passaggi successivi