Preskočiť na obsah

Personalizované fragmenty na stránkach vo vyrovnávacej pamäti

Stránka poskytovaná zo statickej vyrovnávacej pamäte vyzerá pre každého rovnako. V tom spočíva zmysel ukladania do vyrovnávacej pamäte, ale aj problém: hlavička má zákazníkovi po prihlásení povedať „Ahoj, Ada“ a ikona košíka má zobrazovať tri položky. Ak šablóna podmieňuje výstup aktuálnym používateľom, vyrovnávacia pamäť buď uloží pozdrav jedného návštevníka pre všetkých, alebo sa stránka nebude ukladať vôbec.

Dynamické ostrovy v Blockstudio oddeľujú tieto dve požiadavky. Stránka z vyrovnávacej pamäte HTML obsahuje zástupný prvok bezpečný pre vyrovnávaciu pamäť. Po načítaní stránky sa malý modul runtime opýta WordPress na osobný fragment v rámci požiadavky samotného návštevníka a nahradí ním zástupný prvok. Stránku možno naďalej ukladať do vyrovnávacej pamäte, zatiaľ čo živý je iba fragment.

Táto príručka vytvorí dva ostrovy: pozdrav a počet položiek v košíku. Ukáže, čo obsahuje stránka uložená vo vyrovnávacej pamäti, ako vyzerá požiadavka na fragment a ako koncový bod zisťuje, kto je návštevník. Dopĺňa príručku Poskytovanie WordPress ako statickej HTML.

Ako funguje dynamický ostrov

  1. Blok vykreslí zástupný prvok vo vnútri označovacieho prvku. Označovací prvok obsahuje názov bloku, povolené atribúty a podpis vygenerovaný serverom.
  2. Keďže vykreslená stránka obsahuje označovací prvok, Blockstudio vloží modul runtime ostrovov. Stránky bez ostrovov neposielajú žiadny kód JavaScript.
  3. Modul runtime zhromaždí pripravené označovacie prvky a odošle jednu hromadnú požiadavku POST na /wp-json/blockstudio/v1/island/render.
  4. Koncový bod overí každý podpis, vykreslí blok v kontexte požiadavky návštevníka a vráti fragmenty.
  5. Modul runtime nahradí každý zástupný prvok a odošle udalosti.

V editore blokov sa blok vykreslí bežným spôsobom bez zástupného prvku.

Krok 1: Blok s pozdravom

Vytvorte blok z troch súborov:

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 neho vytvára ostrov s požiadavkou na fragment. tag nastavuje označovací prvok, aby ostrov mohol byť vložený priamo do navigačného panela. attributes je zoznam povolených atribútov bloku, ktoré sa odosielajú spolu s požiadavkou na fragment; všetko, čo v ňom nie je uvedené, sa neodošle ani nepodpíše. cache sa podrobnejšie rozoberá nižšie.

Zástupný prvok je to, čo obsahuje stránka uložená vo vyrovnávacej pamäti. Musí byť bezpečné zobrazovať ho každému návštevníkovi, preto v ňom nie sú údaje o používateľovi. Odkaz „Účet“ funguje pre každého:

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

Hlavná šablóna vykreslí skutoč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; ?>

Tu je vetvenie podľa aktuálneho používateľa v poriadku: táto šablóna sa spúšťa iba pri požiadavke na fragment, nikdy pri vykresľovaní stránky uloženej vo vyrovnávacej pamäti.

Vložte ho všade tam, kde sa vykresľuje hlavička:

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

Fungujú aj značky blokov: <bs:acme-greeting /> alebo <block name="acme/greeting" />.

Krok 2: Obsah stránky z vyrovnávacej pamäte

Pri vykreslení na serveri blok vytvorí iba označovací a zástupný prvok:

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>

Vykreslite ju raz ako anonymný návštevník a raz ako prihlásený používateľ. Obe reťazce budú mať úplne zhodné bajty. Presne túto vlastnosť vyžaduje statické predvykreslenie so zapnutým serveLoggedIn: nech vykreslenie spustí ktokoľvek, uložený dokument bude vždy rovnaký a nedostanú sa doň žiadne osobné údaje.

Krok 3: Požiadavka na fragment

Modul runtime odošle všetky pripravené ostrovy v jednej požiadavke:

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

Odpoveď je označená kľúčom clientId. Pre prihláseného návštevníka:

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

Položka, ktorej overenie zlyhá, vráti chybový kód namiesto HTML, pričom ostatné položky hromadnej požiadavky sa spracujú. Druhá položka tu zmenila guestLabel bez zodpovedajúceho podpisu a tretia uviedla názov bloku, ktorý nie je dynamickým ostrovom:

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á odpoveď obsahuje Cache-Control: no-store, no-cache, must-revalidate, max-age=0, Pragma: no-cache a X-Robots-Tag: noindex. Koncový bod sa nachádza pod /wp-json, ktorú statické predvykreslenie vždy obchádza. Preto fragment neuloží ani vyrovnávacia pamäť na pôvodnom serveri, ani CDN, ktoré rešpektuje hlavičky pôvodného servera.

Kto je návštevník

Modul runtime odosiela požiadavku s credentials: 'same-origin', takže prehliadač priloží prihlasovací súbor cookie WordPress. WordPress REST API štandardne ignoruje overovanie pomocou súboru cookie bez nonce, no nonce nemožno uložiť do stránky vo vyrovnávacej pamäti. Koncový bod ostrova to rieši sám: pri požiadavke z prehliadača na rovnakom pôvode overí súbor cookie logged_in a obnoví prihlásenie používateľa ešte pred vykreslením.

O tom, či požiadavka pochádza z rovnakého pôvodu, sa rozhoduje na základe hlavičky Sec-Fetch-Site a, ak je prítomná, hlavičky Origin, ktoré sa porovnajú s home_url(). Požiadavka z iného pôvodu, ktorá náhodou obsahuje súbor cookie, sa vykreslí ako anonymná, takže požiadavka z inej stránky nikdy nevykreslí osobný fragment návštevníka. V praxi:

Požiadavka Vykreslí sa ako
Načítanie z rovnakého pôvodu s platným prihlasovacím súborom cookie prihlásený používateľ
Požiadavka z iného pôvodu s rovnakým súborom cookie anonymný používateľ
Bez súboru cookie anonymný používateľ

Ktorá stránka je to?

Ak fragment potrebuje identitu svojej stránky, pridajte "context": true do blockstudio.island. Značka potom spolu s atribútmi podpisuje ID príspevku a typ príspevku dopytovanej stránky. Vo fragmente sa $block['postId'], $block['postType'], get_the_ID() a get_queried_object_id() vzťahujú na túto stránku. V rámci slučky Query Loop to naďalej znamená nadradenú dopytovanú stránku, nie položku slučky.

Kontext stránky je voliteľný a je tiež súčasťou kľúča vyrovnávacej pamäte fragmentov. Koncový bod znova overí prístup aj pri fragmentoch uložených vo vyrovnávacej pamäti, takže podpísaný marker nesprístupní stránku, ktorá sa medzitým stala súkromnou alebo chránenou heslom. Informácie o konfigurácii a zabezpečení nájdete v časti Kontext stránky. Žiadne ľubovoľné URL ani parametre dopytu sa znova nepoužijú.

Krok 4: Počet položiek v košíku, ktorý sa sám aktualizuje

Druhý ostrov ukazuje ďalší štýl zástupného prvku a dve možnosti modulu runtime. Namiesto samostatného súboru zástupného prvku šablóna 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; ?>

Všetky šablónové jazyky podporujú rovnaké príznaky: isIsland, isIslandPlaceholder, isIslandFragment a islandPhase ("normal", "hydrate", "placeholder" alebo "fragment"). Počet položiek tu pochádza z filtra acme/cart_count, ktorému dodáva údaje váš obchodný kód. Keď vráti hodnotu 3, koncový bod odpovie 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žiadavku, kým sa označovací prvok nedostane do oblasti zobrazenia, a použije IntersectionObserver. Viditeľné ostrovy, ktoré sa objavia súčasne, sa aj tak odošlú v jednej požiadavke. event označuje udalosť okna, pri ktorej sa ostrov načíta znova. Po pridaní do košíka tak váš skript musí iba oznámiť túto udalosť:

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

Reakcia v kóde frontendu

Udalosti sa šíria od značky, takže jeden poslucháč na document pokrýva každý ostrov. event.detail.name obsahuje názov 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ýmene runtime odošle blockstudio:island:rendered a potom blockstudio:island:hydrate. Pri zlyhaní zostane zástupný prvok na mieste a spustí sa blockstudio:island:error. Hydratované ostrovy ("island": "hydrate") požiadavku úplne preskočia: ich úplné HTML je na stránke a dostanú iba udalosť hydrate, čo sa hodí pre interaktívne bloky bezpečné pre vyrovnávaciu pamäť, napríklad karty.

Ukladanie fragmentov do vyrovnávacej pamäte

Fragmenty sa predvolene vykresľujú pri každej požiadavke. Vyššie uvedený pozdrav využíva krátkodobú vyrovnávaciu pamäť:

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

per: "user" rozlišuje fragment vo vyrovnávacej pamäti podľa ID používateľa WordPress a anonymné požiadavky sa podľa neho nikdy neukladajú do vyrovnávacej pamäte, takže dvaja anonymní návštevníci nemôžu zdieľať položku určenú používateľovi. per: "global" zdieľa jeden fragment pre rovnaký blok a atribúty, čo sa hodí pre aktuálny, ale nie osobný obsah, napríklad stav zásob. Predvolené trvanie ttl je 60 sekúnd a cache: true je globálna vyrovnávacia pamäť na 60 sekúnd.

Model zabezpečenia

Koncový bod je verejný, ale nejde o všeobecný vykresľovač blokov. Položku vykreslí iba vtedy, keď platia všetky tieto podmienky:

  • blok je zaregistrovaný, dynamický a má island.mode nastavené na dynamic
  • podpis zodpovedá názvu bloku a atribútom, ktoré prešli filtrom: iba kľúče prítomné v schéme bloku aj v zozname povolených ostrovov

Podpis je HMAC-SHA256 vytvorený z normalizovaného názvu bloku a atribútov, ktorého kľúčom je soľ auth obsluhujúcej lokality. Podpisy sa vytvárajú pri vykresľovaní na danej lokalite a nikdy nie sú vložené do témy. Z toho vyplývajú dva dôsledky. Dokument vykreslený na testovacom prostredí obsahuje podpisy tohto prostredia, preto dokumenty vykresľujte na lokalite, ktorá ich bude obsluhovať. A zmena solí WordPress zneplatní všetky podpisy v uložených dokumentoch, preto po zmene soli vymažte statický predbežný výstup.

Jedna požiadavka prijme až 50 ostrovov; pri vyššom počte vráti HTTP 413. Limit zmeníte pomocou blockstudio/islands/max_per_request. Háčiky pre podpisy (blockstudio/islands/signature_payload, blockstudio/islands/signature, blockstudio/islands/verify_signature) sú k dispozícii pre hostiteľov, ktorí potrebujú inú schému.

Kedy ostrov nepoužívať

Fragmenty nie sú súčasťou počiatočného HTML, takže ich prehľadávače neuvidia. Obsah dôležitý pre SEO ponechajte v bežnom vykreslení. Dynamické ostrovy používajte pre obsah, ktorý môže prísť až po obale stránky: odkazy na účty, stav košíka, odporúčania a ovládacie prvky obmedzené oprávneniami. Ak je celá stránka osobná, napríklad prehľad účtu, namiesto toho uveďte jej cestu v dynamicPaths a vykreslite ju priebežne.

Ďalšie kroky