Ga naar de inhoud

Gepersonaliseerde fragmenten op gecachte pagina’s

Een pagina die vanuit een statische cache wordt aangeboden, is voor iedereen hetzelfde. Dat is precies de bedoeling van caching, maar ook het probleem: de koptekst moet een ingelogde klant begroeten met “Hoi, Ada” en het winkelwagenpictogram moet drie artikelen tonen. Als het sjabloon vertakkingen bevat op basis van de huidige gebruiker, slaat de cache óf de begroeting van één bezoeker voor iedereen op, óf moet de hele pagina worden overgeslagen.

De dynamische eilanden van Blockstudio scheiden die twee zaken. De gecachte HTML bevat een cacheveilige tijdelijke aanduiding. Nadat de pagina is geladen, vraagt een kleine runtime WordPress om het persoonlijke fragment in het eigen verzoek van de bezoeker en vervangt de tijdelijke aanduiding ermee. De pagina blijft geschikt voor caching; alleen het fragment is dynamisch.

Deze gids bouwt twee eilanden: een begroeting en een winkelwagenstand. Je leest wat de gecachte pagina bevat, hoe het fragmentverzoek eruitziet en hoe het endpoint bepaalt wie de bezoeker is. De gids sluit aan op Servering WordPress als statische HTML.

Hoe een dynamisch eiland werkt

  1. Het blok geeft de tijdelijke aanduiding weer in een markeerelement. De markering bevat de bloknaam, de toegestane attributen en een door de server gegenereerde handtekening.
  2. Omdat de weergegeven pagina een markering bevat, voegt Blockstudio de runtime voor eilanden toe. Pagina’s zonder eilanden bevatten geen runtime voor eilanden JavaScript.
  3. De runtime verzamelt gereedstaande markeringen en stuurt één gebundeld POST naar /wp-json/blockstudio/v1/island/render.
  4. Het endpoint controleert elke handtekening, geeft het blok weer in de verzoekcontext van de bezoeker en retourneert de fragmenten.
  5. De runtime vervangt elke tijdelijke aanduiding en verstuurt gebeurtenissen.

In de blokeditor wordt het blok normaal weergegeven, zonder tijdelijke aanduiding.

Stap 1: Het begroetingsblok

Maak het blok met drie bestanden:

Code
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" maakt hiervan een eiland met een fragmentverzoek. tag bepaalt het markeerelement, zodat het eiland inline in een navigatiebalk kan staan. attributes is de toelatingslijst van blokattributen die met het fragmentverzoek worden meegestuurd; alles wat er niet op staat, wordt niet verstuurd of ondertekend. cache wordt verderop behandeld.

De gecachte pagina bevat de tijdelijke aanduiding. Deze moet veilig zijn om aan iedere bezoeker te tonen en bevat daarom geen gebruikersgegevens. Een link met de tekst “Account” werkt voor iedereen:

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

Het hoofdsjabloon geeft het echte fragment weer:

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

Vertakkingen op basis van de huidige gebruiker zijn hier prima: dit sjabloon wordt alleen uitgevoerd voor het fragmentverzoek, nooit voor de gecachte pagina.

Plaats het waar de koptekst wordt weergegeven:

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

Bloktags werken ook: <bs:acme-greeting /> of <block name="acme/greeting" />.

Stap 2: Wat de gecachte pagina bevat

Wanneer het blok op de server wordt weergegeven, produceert het alleen de markering en de tijdelijke aanduiding:

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>

Geef het één keer weer als anonieme bezoeker en één keer als ingelogde gebruiker: de twee tekenreeksen zijn byte voor byte identiek. Dat is precies wat een statische pre-rendering met ingeschakelde serveLoggedIn nodig heeft: wie de weergave ook start, het opgeslagen document blijft hetzelfde en er kunnen geen persoonlijke gegevens in terechtkomen.

Stap 3: Het fragmentverzoek

De runtime verstuurt alle gereedstaande eilanden in één verzoek:

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

Het antwoord is gesleuteld op clientId. Voor een ingelogde bezoeker:

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

Een item dat de verificatie niet doorstaat, wordt als foutcode teruggestuurd in plaats van HTML, zonder dat de rest van de batch mislukt. Hier is bij het tweede item guestLabel gewijzigd zonder bijbehorende handtekening, en vermeldde het derde een blok dat geen dynamisch eiland is:

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"
    }
}

Elk antwoord bevat Cache-Control: no-store, no-cache, must-revalidate, max-age=0, Pragma: no-cache en X-Robots-Tag: noindex. Het endpoint staat onder /wp-json. Statische pre-rendering omzeilt dit pad altijd, zodat noch de cache op de oorsprongserver, noch een CDN die de oorsprongheaders respecteert een fragment opslaat.

Wie is de bezoeker

De runtime verstuurt het verzoek met credentials: 'same-origin', zodat de browser de inlogcookie WordPress meestuurt. De WordPress REST API negeert cookie-authenticatie normaal gesproken zonder nonce, en een nonce kan niet op een gecachte pagina staan. Het eilandendpoint regelt dit zelf: bij een browserverzoek van dezelfde oorsprong valideert het de cookie logged_in en herstelt het die gebruiker voordat het de pagina weergeeft.

Dezelfde oorsprong wordt bepaald aan de hand van de header Sec-Fetch-Site en, indien aanwezig, de header Origin, vergeleken met home_url(). Een verzoek vanaf een andere oorsprong dat toevallig de cookie meestuurt, wordt als anoniem verwerkt. Een verzoek vanaf een andere site geeft dus nooit een persoonlijk fragment van een bezoeker weer. In de praktijk:

Verzoek Wordt weergegeven als
Ophalen vanaf dezelfde oorsprong met een geldige inlogcookie de ingelogde gebruiker
Verzoek vanaf een andere oorsprong met dezelfde cookie anoniem
Geen cookie anoniem

Om welke pagina gaat het?

Voeg "context": true toe aan blockstudio.island wanneer het fragment de identiteit van de bijbehorende pagina nodig heeft. De markering ondertekent vervolgens naast de attributen ook het bericht-ID en berichttype van de opgevraagde pagina. In het fragment verwijzen $block['postId'], $block['postType'], get_the_ID() en get_queried_object_id() naar die pagina. Binnen een Query Loop verwijst dit nog steeds naar de buitenste opgevraagde pagina, niet naar het lusitem.

Pagina-context is opt-in en maakt ook deel uit van de fragmentcache-sleutel. Het endpoint controleert de toegang opnieuw, zelfs bij gecachte fragmenten, zodat een ondertekende marker geen pagina toont die inmiddels privé of met een wachtwoord beveiligd is. Zie Pagina-context voor de configuratie- en beveiligingsdetails. Willekeurige URL- of queryparameters worden niet opnieuw afgespeeld.

Stap 4: Een winkelwagenstand die zichzelf vernieuwt

Het tweede eiland laat de andere stijl voor tijdelijke aanduidingen en twee runtimeopties zien. In plaats van een afzonderlijk bestand voor de tijdelijke aanduiding controleert het sjabloon $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; ?>

Dezelfde opties bestaan in elke sjabloontaal: isIsland, isIslandPlaceholder, isIslandFragment en islandPhase ("normal", "hydrate", "placeholder" of "fragment"). Hier komt de stand uit een filter acme/cart_count dat je webwinkelcode invult. Als dit 3 retourneert, geeft het endpoint het volgende terug:

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" stelt het verzoek uit totdat de markering in beeld komt, met IntersectionObserver. Zichtbare eilanden die tegelijk verschijnen, worden nog steeds in één verzoek gebundeld. event noemt een vensterevenement dat het eiland opnieuw ophaalt. Na het toevoegen aan de winkelwagen hoeft je script dit dus alleen aan te kondigen:

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

Reageren in frontendcode

Gebeurtenissen borrelen omhoog vanaf de markering, dus één listener op document dekt elk eiland. event.detail.name bevat de bloknaam:

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);
});

Na een vervanging verzendt de runtime blockstudio:island:rendered en daarna blockstudio:island:hydrate. Bij een fout blijft de tijdelijke aanduiding staan en wordt blockstudio:island:error geactiveerd. Eilanden die al zijn gehydrateerd ("island": "hydrate") slaan het verzoek helemaal over: hun volledige HTML staat op de pagina en ze ontvangen alleen de gebeurtenis hydrate. Dat is geschikt voor cachebestendige interactieve blokken, zoals tabbladen.

Fragmenten cachen

Fragmenten worden standaard bij elk verzoek gerenderd. De begroeting hierboven schakelt een korte cache in:

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

per: "user" varieert het gecachete fragment op basis van de gebruikers-ID van WordPress. Anonieme verzoeken worden hierbij nooit gecachet, zodat twee anonieme bezoekers geen vermelding delen die voor een gebruiker bedoeld is. per: "global" deelt één fragment voor hetzelfde blok en dezelfde attributen. Dat is geschikt voor actuele, maar niet persoonlijke content, zoals een voorraadniveau. ttl staat standaard op 60 seconden en cache: true is een globale cache van 60 seconden.

Het beveiligingsmodel

Het endpoint is openbaar, maar is geen algemene blokrenderer. Het rendert een vermelding alleen als aan al deze voorwaarden is voldaan:

  • het blok is geregistreerd, dynamisch en heeft island.mode ingesteld op dynamic
  • de handtekening komt overeen met de bloknaam en de attributen die de filter doorstaan: alleen sleutels die zowel in het blokschema als in de toegestane lijst van het eiland staan

De handtekening is een HMAC-SHA256 over de genormaliseerde bloknaam en attributen, ondertekend met de auth-salt van de site die de content aanbiedt. Handtekeningen worden tijdens het renderen op die site aangemaakt en nooit in een thema ingebakken. Dit heeft twee gevolgen. Een document dat op staging is gerenderd, bevat staging-handtekeningen, dus render documenten op de site die ze aanbiedt. En als u de WordPress-salts roteert, worden alle handtekeningen in opgeslagen documenten ongeldig. Wis daarom de statische prerender na een saltrotatie.

Eén verzoek accepteert maximaal 50 eilanden; bij meer eilanden retourneert het HTTP 413. Wijzig de limiet met blockstudio/islands/max_per_request. Er zijn handtekeninghooks (blockstudio/islands/signature_payload, blockstudio/islands/signature, blockstudio/islands/verify_signature) voor hosts die een ander schema nodig hebben.

Wanneer u geen eiland moet gebruiken

Fragmenten staan niet in de initiële HTML, dus crawlers zien ze niet. Houd content die relevant is voor SEO in de normale render. Gebruik dynamische eilanden voor content die na de paginaschil kan binnenkomen: accountlinks, winkelwagenstatus, aanbevelingen en bedieningselementen waarvoor toestemming nodig is. Als de hele pagina persoonlijk is, zoals een accountdashboard, vermeld het pad dan in dynamicPaths en render de pagina live.

Volgende stappen