Přejít k obsahu

Personalizované fragmenty na stránkách v mezipaměti

Stránka načtená ze statické mezipaměti je pro všechny stejná. Právě o to při ukládání do mezipaměti jde, ale zároveň v tom tkví problém: záhlaví chce přihlášeného zákazníka pozdravit slovy „Ahoj, Ado“ a ikona košíku chce zobrazit tři položky. Pokud se šablona větví podle aktuálního uživatele, mezipaměť buď uloží pozdrav jednoho návštěvníka pro všechny, nebo musí stránku zcela vynechat.

Dynamické ostrůvky Blockstudio oddělují tyto dva úkoly. Stránka v mezipaměti HTML obsahuje zástupný obsah bezpečný pro mezipaměť. Po načtení stránky se drobný modul runtime zeptá WordPress na osobní fragment v rámci vlastního požadavku návštěvníka a vloží jej na místo zástupného obsahu. Stránka zůstává vhodná pro ukládání do mezipaměti a aktuální je pouze fragment.

Tento průvodce vytvoří dva ostrůvky, pozdrav a počet položek v košíku, a vysvětlí, co obsahuje stránka v mezipaměti, jak vypadá požadavek na fragment a jak koncový bod určuje, kdo je návštěvník. Navazuje na průvodce Poskytování WordPress jako statického HTML.

Jak funguje dynamický ostrůvek

  1. Blok vykreslí zástupný obsah uvnitř značkovacího prvku. Značka obsahuje název bloku, povolené atributy a podpis vytvořený serverem.
  2. Protože vykreslená stránka obsahuje značku, Blockstudio vloží modul runtime ostrůvků. Stránky bez ostrůvků neposílají žádný modul runtime ostrůvků JavaScript.
  3. Modul runtime shromáždí připravené značky a odešle jeden dávkový POST do /wp-json/blockstudio/v1/island/render.
  4. Koncový bod ověří každý podpis, vykreslí blok v kontextu požadavku návštěvníka a vrátí fragmenty.
  5. Modul runtime nahradí jednotlivé zástupné obsahy a vyvolá události.

V editoru bloků se blok vykreslí běžně, bez zástupného obsahu.

Krok 1: Blok s pozdravem

Vytvořte blok se třemi soubory:

Kód
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" z tohoto bloku vytváří ostrůvek s požadavkem na fragment. tag nastavuje značkovací prvek, takže ostrůvek může být vložený v navigační liště. attributes je seznam povolených atributů bloku, které se odesílají spolu s požadavkem na fragment; cokoli, co v něm není uvedeno, se neodesílá ani nepodepisuje. cache je podrobněji vysvětleno níže.

Obsah stránky v mezipaměti tvoří zástupný obsah. Musí být bezpečný pro zobrazení všem návštěvníkům, takže nesmí obsahovat žádná uživatelská data. Odkaz „Účet“ funguje pro každého:

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

Hlavní šablona vykreslí skutečný 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; ?>

Větvení podle aktuálního uživatele je zde v pořádku: tato šablona se spouští pouze pro požadavek na fragment, nikdy pro stránku v mezipaměti.

Umístěte jej kamkoli, kde se vykresluje záhlaví:

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

Fungují i značky bloků: <bs:acme-greeting /> nebo <block name="acme/greeting" />.

Krok 2: Co obsahuje stránka v mezipaměti

Blok se vykreslí na serveru a vytvoří pouze značku a zástupný obsah:

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>

Vykreslete jej jednou jako anonymní návštěvník a podruhé jako přihlášený uživatel. Oba řetězce budou totožné po jednotlivých bajtech. Přesně to vyžaduje statické předběžné vykreslení se zapnutým serveLoggedIn: bez ohledu na to, kdo vykreslení spustí, uložený dokument je stejný a nemohou se do něj dostat žádné osobní údaje.

Krok 3: Požadavek na fragment

Modul runtime odešle všechny připravené ostrůvky v jednom požadavku:

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

Odpověď je indexována podle clientId. Pro přihlášeného návštěvníka:

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

Položka, která neprojde ověřením, vrátí chybový kód místo HTML, aniž by se zrušilo zpracování zbytku dávky. Zde se u druhé položky změnilo guestLabel bez odpovídajícího podpisu a třetí položka uváděla blok, který není dynamickým ostrůvkem:

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

Každá odpověď obsahuje Cache-Control: no-store, no-cache, must-revalidate, max-age=0, Pragma: no-cache a X-Robots-Tag: noindex. Koncový bod je umístěn pod /wp-json, které statické předběžné vykreslení vždy obchází, takže fragment neuloží ani mezipaměť původního serveru, ani CDN respektující hlavičky původního serveru.

Kdo je návštěvník

Modul runtime odesílá požadavek s credentials: 'same-origin', takže prohlížeč připojí přihlašovací cookie WordPress. WordPress REST API běžně ignoruje ověřování pomocí cookies bez nonce a nonce nelze uložit do stránky v mezipaměti. Koncový bod ostrůvků si s tím poradí sám: u požadavku prohlížeče ze stejného původu ověří cookie logged_in a před vykreslením obnoví uživatele.

Požadavek ze stejného původu se určuje podle hlavičky Sec-Fetch-Site a případné hlavičky Origin porovnané s home_url(). Požadavek z jiného původu, který náhodou obsahuje cookie, se vykreslí jako anonymní, takže požadavek z jiného webu nikdy nevykreslí osobní fragment návštěvníka. V praxi:

Požadavek Vykreslí se jako
Požadavek ze stejného původu s platnou přihlašovací cookie přihlášený uživatel
Požadavek z jiného původu se stejnou cookie anonymní návštěvník
Bez cookie anonymní návštěvník

O kterou stránku jde?

Přidejte "context": true do blockstudio.island, když fragment potřebuje identitu své stránky. Značka pak vedle atributů podepisuje ID příspěvku a typ příspěvku dotazované stránky. Ve fragmentu se $block['postId'], $block['postType'], get_the_ID() a get_queried_object_id() vztahují k této stránce. Uvnitř Query Loopu to stále znamená vnější dotazovanou stránku, nikoli položku smyčky.

Kontext stránky je volitelný a je také součástí klíče fragmentové cache. Endpoint znovu ověřuje přístup, i u fragmentů z cache, takže podepsaný marker nezpřístupní stránku, která se mezitím stala soukromou nebo chráněnou heslem. Konfiguraci a bezpečnostní podrobnosti najdete v Kontext stránky. Žádné libovolné URL ani parametry dotazu se znovu nepředávají.

Krok 4: Počet položek v košíku, který se sám obnovuje

Druhý ostrůvek ukazuje jiný styl zástupného obsahu a dvě možnosti modulu runtime. Místo samostatného souboru se zástupným obsahem šablona kontroluje $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; ?>

Stejné příznaky jsou dostupné ve všech jazycích šablon: isIsland, isIslandPlaceholder, isIslandFragment a islandPhase ("normal", "hydrate", "placeholder" nebo "fragment"). V tomto příkladu počet pochází z filtru acme/cart_count, jehož hodnotu doplňuje váš obchodní kód; když vrací 3, koncový bod odpoví takto:

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" odloží požadavek, dokud značka nevstoupí do výřezu, pomocí IntersectionObserver. Viditelné ostrůvky, které se objeví současně, se přesto spojí do jednoho požadavku. event určuje název události okna, která ostrůvek znovu načte. Po přidání do košíku tak váš skript stačí nechat tuto událost oznámit:

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

Reakce v kódu frontendu

Události se šíří od značky, takže jeden posluchač na document obslouží všechny ostrovy. event.detail.name obsahuje název bloku:

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

Po výměně runtime odešle blockstudio:island:rendered a poté blockstudio:island:hydrate. Při selhání zůstane zástupný prvek na místě a spustí se blockstudio:island:error. Hydratované ostrovy ("island": "hydrate") požadavek úplně přeskočí: jejich úplné HTML je na stránce a přijmou pouze událost hydrate, což se hodí pro interaktivní bloky bezpečné pro ukládání do mezipaměti, například karty.

Ukládání fragmentů do mezipaměti

Fragmenty se ve výchozím nastavení vykreslují při každém požadavku. Výše uvedený pozdrav využívá krátkodobou mezipaměť:

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

per: "user" rozlišuje fragmenty v mezipaměti podle ID WordPress uživatele a anonymní požadavky se do ní nikdy neukládají, takže dva anonymní návštěvníci nemohou sdílet záznam určený konkrétnímu uživateli. per: "global" sdílí jeden fragment pro stejný blok a atributy, což se hodí pro živý, ale neosobní obsah, například stav zásob. ttl má ve výchozím nastavení hodnotu 60 sekund a cache: true je globální mezipaměť s platností 60 sekund.

Model zabezpečení

Koncový bod je veřejný, ale neslouží k obecnému vykreslování bloků. Záznam vykreslí pouze tehdy, když platí všechny následující podmínky:

  • blok je zaregistrovaný, dynamický a pro island.mode má nastavenou hodnotu dynamic
  • podpis odpovídá názvu bloku a atributům, které prošly filtrem: povolené jsou pouze klíče uvedené ve schématu bloku i v seznamu povolených položek ostrova

Podpis je HMAC-SHA256 vytvořený z normalizovaného názvu bloku a atributů, jehož klíčem je sůl auth poskytujícího webu. Podpisy se vytvářejí při vykreslování na daném webu a nikdy se nevkládají přímo do šablony. Z toho vyplývají dva důsledky. Dokument vykreslený na testovacím webu obsahuje jeho podpisy, proto dokumenty vykreslujte na webu, který je bude poskytovat. A změna solí WordPress zneplatní všechny podpisy v uložených dokumentech, proto po změně soli vymažte staticky předem vykreslené stránky.

Jeden požadavek přijímá až 50 ostrovů; další vrátí HTTP 413. Limit změňte pomocí blockstudio/islands/max_per_request. Háčky pro podpisy (blockstudio/islands/signature_payload, blockstudio/islands/signature, blockstudio/islands/verify_signature) jsou k dispozici hostitelům, kteří potřebují jiné schéma.

Kdy ostrov nepoužívat

Fragmenty nejsou součástí počátečního HTML, takže je roboti vyhledávačů nevidí. Obsah důležitý pro SEO ponechte v běžném vykreslení. Dynamické ostrovy použijte pro obsah, který může dorazit až po načtení základní stránky: odkazy k účtu, stav košíku, doporučení a ovládací prvky přístupné na základě oprávnění. Pokud je celá stránka personalizovaná, například přehled účtu, uveďte její cestu v dynamicPaths a vykreslujte ji živě.

Další kroky