Zum Inhalt springen

Personalisierte Fragmente auf gecachten Seiten

Eine Seite aus einem statischen Cache wird allen Besuchern gleich ausgeliefert. Genau das ist der Zweck des Cachings, aber auch das Problem: Im Header soll bei einem angemeldeten Kunden „Hallo, Ada“ stehen, und das Warenkorbsymbol soll drei Artikel anzeigen. Verzweigt das Template je nach aktuellem Benutzer, speichert der Cache entweder die Begrüßung eines Besuchers für alle oder muss die Seite ganz aus dem Cache ausschließen.

Mit den dynamischen Inseln von Blockstudio lassen sich diese beiden Anliegen trennen. Das gecachte HTML enthält einen cache-sicheren Platzhalter. Nach dem Laden der Seite fragt eine kleine Laufzeitumgebung WordPress in der eigenen Anfrage des Besuchers nach dem persönlichen Fragment und setzt es ein. Die Seite bleibt cachebar; nur das Fragment wird live geladen.

In dieser Anleitung erstellst du zwei Inseln: eine Begrüßung und einen Warenkorbstand. Dabei erfährst du, was die gecachte Seite enthält, wie die Fragmentanfrage aussieht und wie der Endpunkt erkennt, wer der Besucher ist. Ergänzend dazu gibt es die Anleitung WordPress statisch ausliefernHTML.

So funktioniert eine dynamische Insel

  1. Der Block rendert seinen Platzhalter innerhalb eines Markierungselements. Die Markierung enthält den Blocknamen, die freigegebenen Attribute und eine serverseitig erzeugte Signatur.
  2. Da die gerenderte Seite eine Markierung enthält, bindet Blockstudio die Laufzeitumgebung für Inseln ein. Seiten ohne Inseln enthalten keine Laufzeitumgebung für Inseln JavaScript.
  3. Die Laufzeitumgebung sammelt alle bereiten Markierungen und sendet eine gebündelte POST-Anfrage an /wp-json/blockstudio/v1/island/render.
  4. Der Endpunkt prüft jede Signatur, rendert den Block im Anfragekontext des Besuchers und gibt die Fragmente zurück.
  5. Die Laufzeitumgebung setzt jeden Platzhalter ein und löst Ereignisse aus.

Im Block-Editor wird der Block normal und ohne Platzhalter gerendert.

Schritt 1: Der Begrüßungsblock

Erstelle den Block mit drei Dateien:

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" macht daraus eine Insel mit Fragmentanfrage. tag legt das Markierungselement fest, sodass die Insel inline in einer Navigationsleiste stehen kann. attributes ist die Freigabeliste der Blockattribute, die mit der Fragmentanfrage übermittelt werden. Alles, was nicht aufgeführt ist, wird weder gesendet noch signiert. cache wird weiter unten näher erläutert.

Der gecachte Seiteninhalt enthält den Platzhalter. Er muss für jeden Besucher unbedenklich sein und darf daher keine Benutzerdaten enthalten. Ein Link „Konto“ funktioniert für alle:

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

Das Haupt-Template rendert das tatsächliche Fragment:

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

Eine Verzweigung nach dem aktuellen Benutzer ist hier in Ordnung: Dieses Template wird nur für die Fragmentanfrage ausgeführt, niemals für die gecachte Seite.

Füge den Block überall dort ein, wo der Header gerendert wird:

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

Block-Tags funktionieren ebenfalls: <bs:acme-greeting /> oder <block name="acme/greeting" />.

Schritt 2: Inhalt der gecachten Seite

Serverseitig gerendert erzeugt der Block nur die Markierung und den Platzhalter:

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>

Rendere den Block einmal als anonymer Besucher und einmal als angemeldeter Benutzer. Die beiden Zeichenfolgen sind dann bytegenau identisch. Genau diese Eigenschaft braucht ein statisches Prerendering mit aktiviertem serveLoggedIn: Unabhängig davon, wer das Rendering auslöst, bleibt das gespeicherte Dokument gleich und es können keine persönlichen Daten darin landen.

Schritt 3: Die Fragmentanfrage

Die Laufzeitumgebung sendet alle bereiten Inseln in einer Anfrage:

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

Die Antwort ist nach clientId indiziert. Für einen angemeldeten Besucher sieht sie so aus:

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

Ein Eintrag, dessen Prüfung fehlschlägt, wird als Fehlercode statt als HTML zurückgegeben, ohne die übrigen Einträge des Anfragepakets zu beeinträchtigen. Hier wurde beim zweiten Eintrag guestLabel ohne passende Signatur geändert, und der dritte nannte einen Block, der keine dynamische Insel ist:

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

Jede Antwort enthält Cache-Control: no-store, no-cache, must-revalidate, max-age=0, Pragma: no-cache und X-Robots-Tag: noindex. Der Endpunkt liegt unter /wp-json, das beim statischen Prerendering immer umgangen wird. Deshalb speichern weder der Origin-Cache noch ein CDN, das die Origin-Header berücksichtigt, ein Fragment.

Wer ist der Besucher?

Die Laufzeitumgebung sendet die Anfrage mit credentials: 'same-origin', sodass der Browser das Login-Cookie WordPress mitsendet. Die WordPress REST API ignoriert die Cookie-Authentifizierung normalerweise, wenn kein Nonce vorhanden ist. Ein Nonce kann jedoch nicht in einer gecachten Seite enthalten sein. Der Insel-Endpunkt übernimmt das selbst: Bei einer gleichursprünglichen Browseranfrage prüft er das logged_in-Cookie und stellt die zugehörige Benutzeridentität vor dem Rendering wieder her.

Ob eine Anfrage gleichursprünglich ist, wird anhand des Headers Sec-Fetch-Site und, sofern vorhanden, des Headers Origin im Vergleich mit home_url() ermittelt. Eine Anfrage von einem anderen Ursprung, die zufällig das Cookie enthält, wird anonym gerendert. So rendert eine Anfrage von einer anderen Website niemals das persönliche Fragment eines Besuchers. In der Praxis gilt:

Anfrage Wird gerendert als
Gleichursprüngliche Fetch-Anfrage mit gültigem Login-Cookie angemeldeter Benutzer
Ursprungsübergreifende Anfrage mit demselben Cookie anonym
Kein Cookie anonym

Um welche Seite handelt es sich?

Füge "context": true zu blockstudio.island hinzu, wenn das Fragment die Identität seiner Seite benötigt. Der Marker signiert dann neben den Attributen auch die Beitrags-ID und den Beitragstyp der abgefragten Seite. Im Fragment beziehen sich $block['postId'], $block['postType'], get_the_ID() und get_queried_object_id() auf diese Seite. Innerhalb einer Query Loop ist damit weiterhin die äußere abgefragte Seite gemeint, nicht das Loop-Element.

Der Seitenkontext ist optional und gehört auch zum Fragment-Cache-Schlüssel. Der Endpunkt prüft den Zugriff erneut, selbst bei zwischengespeicherten Fragmenten. Ein signierter Marker gibt daher keine Seite preis, die inzwischen privat oder passwortgeschützt ist. Unter Seitenkontext findest du Informationen zur Konfiguration und Sicherheit. Beliebige URL oder Abfrageparameter werden nicht erneut abgespielt.

Schritt 4: Ein Warenkorbstand, der sich selbst aktualisiert

Die zweite Insel zeigt den anderen Platzhalterstil und zwei Laufzeitoptionen. Statt einer separaten Platzhalterdatei prüft das Template $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; ?>

Dieselben Flags sind in jeder Template-Sprache verfügbar: isIsland, isIslandPlaceholder, isIslandFragment und islandPhase ("normal", "hydrate", "placeholder" oder "fragment"). Hier stammt der Warenkorbstand aus einem acme/cart_count-Filter, den dein Commerce-Code befüllt. Liefert dieser 3 zurück, antwortet der Endpunkt mit:

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" verzögert die Anfrage, bis die Markierung im Viewport erscheint, und verwendet dafür IntersectionObserver. Sichtbare Inseln, die gleichzeitig erscheinen, werden weiterhin in einer Anfrage gebündelt. event benennt ein Fensterereignis, das die Insel erneut abruft. Nach einem Aufruf zum Hinzufügen zum Warenkorb muss dein Skript also nur dieses Ereignis auslösen:

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

Auf Code im Frontend reagieren

Ereignisse steigen von der Markierung aus im DOM-Baum auf. Ein einzelner Listener auf document deckt daher alle Inseln ab. event.detail.name enthält den Blocknamen:

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

Nach dem Einsetzen löst die Laufzeitumgebung zuerst blockstudio:island:rendered und dann blockstudio:island:hydrate aus. Schlägt der Vorgang fehl, bleibt der Platzhalter bestehen und blockstudio:island:error wird ausgelöst. Hydrierte Inseln ("island": "hydrate") überspringen die Anfrage vollständig: Ihr vollständiger Inhalt aus HTML ist bereits auf der Seite, und sie erhalten nur das Ereignis hydrate. Das eignet sich für interaktive, cache-sichere Blöcke wie Tabs.

Fragment-Caching

Fragmente werden standardmäßig bei jeder Anfrage gerendert. Die Begrüßung oben verwendet einen kurzen Cache-Zeitraum:

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

per: "user" variiert das gecachte Fragment anhand der Benutzer-ID WordPress. Anonyme Anfragen werden dabei nie gecacht, sodass zwei anonyme Besucher keinen Eintrag teilen, der für einen bestimmten Benutzer bestimmt ist. per: "global" verwendet dasselbe Fragment für denselben Block und dieselben Attribute. Das eignet sich für aktuelle, aber nicht persönliche Inhalte wie einen Lagerbestand. ttl ist standardmäßig auf 60 Sekunden eingestellt; cache: true bezeichnet einen globalen Cache mit 60 Sekunden Laufzeit.

Das Sicherheitsmodell

Der Endpunkt ist öffentlich, aber kein allgemeiner Block-Renderer. Er rendert einen Eintrag nur, wenn alle folgenden Bedingungen erfüllt sind:

  • Der Block ist registriert, dynamisch und hat island.mode auf dynamic gesetzt.
  • Die Signatur stimmt mit dem Blocknamen und den Attributen überein, die den Filter passieren: Es sind nur Schlüssel erlaubt, die sowohl im Blockschema als auch in der Freigabeliste der Insel stehen.

Die Signatur ist ein HMAC-SHA256 über den normalisierten Blocknamen und die Attribute, signiert mit dem auth-Salt der ausliefernden Website. Signaturen werden zur Renderzeit auf dieser Website erstellt und niemals in ein Theme eingebettet. Daraus folgen zwei Dinge: Ein auf der Staging-Website gerendertes Dokument enthält Staging-Signaturen. Rendere Dokumente also auf der Website, die sie ausliefert. Und wenn du die WordPress-Salts änderst, werden alle Signaturen in gespeicherten Dokumenten ungültig. Leere daher nach einer Salt-Änderung den Cache des statischen Prerenderings.

Eine Anfrage akzeptiert bis zu 50 Inseln; bei mehr wird der Fehlercode HTTP 413 zurückgegeben. Passe das Limit mit blockstudio/islands/max_per_request an. Für Hosts, die ein anderes Verfahren benötigen, gibt es Signatur-Hooks (blockstudio/islands/signature_payload, blockstudio/islands/signature, blockstudio/islands/verify_signature).

Wann du keine Insel verwenden solltest

Fragmente sind nicht im initialen HTML enthalten und werden daher von Crawlern nicht gesehen. Lass für SEO relevante Inhalte normal rendern. Verwende dynamische Inseln für Inhalte, die nach dem Seiten-Grundgerüst geladen werden können: Kontolinks, Warenkorbstatus, Empfehlungen und zugriffsbeschränkte Steuerelemente. Wenn die ganze Seite personalisiert ist, etwa ein Konto-Dashboard, trage ihren Pfad stattdessen in dynamicPaths ein und rendere sie live.

Nächste Schritte