Személyre szabott töredékek gyorsítótárazott oldalakon
A statikus gyorsítótárból kiszolgált oldal mindenki számára ugyanaz. Ez a gyorsítótárazás célja, de egyben a probléma is: a fejlécben a „Szia, Ada” üdvözlésnek kellene megjelennie a bejelentkezett ügyfélnek, a kosárikonnak pedig három tételt kellene mutatnia. Ha a sablon az aktuális felhasználó alapján választ ágat, a gyorsítótár vagy mindenki számára egy látogató üdvözlését tárolja, vagy az oldalt teljesen ki kell hagynia a gyorsítótárazásból.
A Blockstudio dinamikus szigetei különválasztják ezt a két feladatot. A gyorsítótárazott HTML egy gyorsítótár-biztos helyőrzőt tartalmaz. Az oldal betöltése után egy kis futtatókörnyezet a látogató saját kérésében lekéri a személyes töredéket a WordPress-től, majd behelyettesíti. Az oldal gyorsítótárazható marad, és csak a töredék dinamikus.
Ez az útmutató két szigetet készít: egy üdvözlést és egy kosárszámot. Bemutatja, mit tartalmaz a gyorsítótárazott oldal, hogyan néz ki a töredékre irányuló kérés, és hogyan állapítja meg a végpont a látogató kilétét. Kapcsolódik a WordPress statikus kiszolgálása HTML útmutatóhoz.
Dinamikus sziget működése
- A blokk a helyőrzőjét egy jelölőelemen belül rendereli. A jelölő tartalmazza a blokk nevét, az engedélyezési listán szereplő attribútumokat és egy szerveroldalon generált aláírást.
- Mivel a renderelt oldal jelölőt tartalmaz, a Blockstudio beilleszti a sziget futtatókörnyezetét. Azok az oldalak, amelyeken nincsenek szigetek, nem töltenek le sziget-JavaScript-t.
- A futtatókörnyezet összegyűjti a kész jelölőket, majd egyetlen kötegelt
POST-t küld a/wp-json/blockstudio/v1/island/render-nek. - A végpont ellenőrzi az egyes aláírásokat, a blokkot a látogató kérési környezetében rendereli, majd visszaküldi a töredékeket.
- A futtatókörnyezet behelyettesíti az egyes helyőrzőket, és eseményeket küld ki.
A blokkszerkesztőben a blokk rendesen, helyőrző nélkül renderelődik.
1. lépés: Az üdvözlő blokk
Hozza létre a blokkot három fájllal:
blocks/
└── greeting/
├── block.json
├── placeholder.php
└── index.php
{
"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" }
]
}
}
A mode: "dynamic" teszi ezt töredékkérést használó szigetté.
A tag állítja be a jelölőelemet, így a sziget a navigációs sávon belül is elhelyezhető. A attributes az engedélyezési lista azon blokkattribútumokhoz, amelyek a töredékkéréssel együtt továbbítódnak; ami nincs felsorolva, azt sem elküldeni, sem aláírni nem lehet. A cache beállítást később tárgyaljuk részletesebben.
A gyorsítótárazott oldal a helyőrzőt tartalmazza. Minden látogatónak biztonságosan megjeleníthetőnek kell lennie, ezért nem tartalmaz felhasználói adatokat. Egy „Fiók” hivatkozás mindenki számára megfelelő:
<a href="<?php echo esc_url( home_url( '/account/' ) ); ?>">Account</a>
A fő sablon rendereli a valódi töredéket:
<?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; ?>
Az aktuális felhasználó alapján itt nyugodtan választhat ágat: ez a sablon csak a töredékkéréshez fut le, a gyorsítótárazott oldalhoz soha.
Helyezze el ott, ahol a fejléc renderelődik:
<?php echo bs_block( array( 'name' => 'acme/greeting' ) ); ?>
A blokkcímkék is működnek: <bs:acme-greeting /> vagy
<block name="acme/greeting" />.
2. lépés: Mit tartalmaz a gyorsítótárazott oldal
A szerveren renderelve a blokk csak a jelölőt és a helyőrzőt állítja elő:
<span data-bs-island="acme/greeting" data-bs-island-mode="dynamic" data-bs-island-phase="placeholder" data-bs-island-props="{"guestLabel":"Sign in"}" data-bs-island-signature="a7311ba9f6abf3c993edfdd7d49d2fa23bfa068f715b96637c35ef30de8b2043" data-bs-island-loading="eager"><!--blockstudio/acme/greeting--><a href="https://example.com/account/">Account</a>
</span>
Renderelje egyszer névtelen látogatóként, majd bejelentkezett felhasználóként is; a két karakterlánc bájtról bájtra azonos lesz. Pontosan erre van szüksége a serveLoggedIn engedélyezésével végzett statikus előrenderelésnek: bárki indítja el a renderelést, a tárolt dokumentum ugyanaz marad, és nem kerülhet bele személyes adat.
3. lépés: A töredékkérés
A futtatókörnyezet minden kész szigetet egyetlen kérésben küld el:
{
"islands": [
{
"clientId": "a1",
"name": "acme/greeting",
"attributes": {
"guestLabel": "Sign in"
},
"signature": "a7311ba9f6abf3c993edfdd7d49d2fa23bfa068f715b96637c35ef30de8b2043"
}
]
}
A válasz kulcsa a clientId. Bejelentkezett látogató esetén:
{
"a1": "<!--blockstudio/acme/greeting--> <a href=\"https://example.com/account/\">\n Hi, Ada </a>\n"
}
Az ellenőrzésen elbukó bejegyzések a HTML helyett hibakódot kapnak, a köteg többi része azonban feldolgozódik. Itt a második bejegyzés aláírás nélkül módosította a guestLabel értékét, a harmadik pedig egy olyan blokkot nevezett meg, amely nem dinamikus sziget:
{
"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"
}
}
Minden válasz tartalmazza a Cache-Control: no-store, no-cache, must-revalidate, max-age=0, a Pragma: no-cache és a X-Robots-Tag: noindex értékét. A végpont a /wp-json alatt található, amelyet a statikus előrenderelés mindig kihagy. Így sem az eredeti kiszolgáló gyorsítótára, sem a CDN nem tárolja a töredéket, ha figyelembe veszi a kiszolgáló fejléceit.
Ki a látogató
A futtatókörnyezet a credentials: 'same-origin' használatával küldi el a kérést, ezért a böngésző mellékeli a WordPress bejelentkezési sütit. A WordPress REST API általában nonce nélkül figyelmen kívül hagyja a sütialapú hitelesítést, nonce pedig nem szerepelhet gyorsítótárazott oldalon. A sziget végpontja ezt maga kezeli: azonos eredetű böngészőkérés esetén ellenőrzi a logged_in sütit, és renderelés előtt visszaállítja a felhasználói munkamenetet.
Az azonos eredetet a Sec-Fetch-Site fejléc alapján állapítja meg, és ha jelen van, a Origin fejlécet is összeveti a home_url() értékkel. Ha egy másik eredetről érkező kérés véletlenül tartalmazza a sütit, névtelenként renderelődik, így másik webhelyről nem jeleníthető meg a látogató személyes töredéke. A gyakorlatban:
| Kérés | Megjelenítés |
|---|---|
| Azonos eredetű fetch érvényes bejelentkezési sütivel | bejelentkezett felhasználóként |
| Eltérő eredetű kérés ugyanazzal a sütivel | névtelenként |
| Nincs süti | névtelenként |
Melyik oldal ez?
Adja hozzá a "context": true elemet a blockstudio.island elemhez, ha a fragmentumnak szüksége van a saját oldalának azonosítójára. A jelölő ezután az attribútumok mellett aláírja a lekérdezett oldal bejegyzésazonosítóját és bejegyzéstípusát is. A fragmentumban a $block['postId'], a $block['postType'], a get_the_ID() és a get_queried_object_id() erre az oldalra hivatkozik. Egy Query Loop-on belül ez továbbra is a külső, lekérdezett oldalt jelenti, nem a ciklus aktuális elemét.
Az oldal kontextusa csak külön bekapcsolva érhető el, és a fragmentum-gyorsítótár kulcsának is része. A végpont a hozzáférést ismét ellenőrzi, a gyorsítótárazott fragmentumok esetében is, így az aláírt jelölő nem tesz elérhetővé olyan oldalt, amely azóta priváttá vagy jelszóval védetté vált. A konfigurációval és a biztonsági részletekkel kapcsolatban lásd: Oldalkontextus. Tetszőleges URL értékek és lekérdezési paraméterek nem kerülnek újrajátszásra.
4. lépés: Magától frissülő kosárszám
A második sziget a másik helyőrzőstílust és két futtatókörnyezeti beállítást mutatja be. Külön helyőrzőfájl helyett a sablon ellenőrzi a $isIslandPlaceholder értékét:
{
"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
$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; ?>
Minden sablonnyelvben ugyanazok a jelzők állnak rendelkezésre: isIsland, isIslandPlaceholder, isIslandFragment és islandPhase ("normal", "hydrate", "placeholder" vagy "fragment"). Itt a szám egy acme/cart_count szűrőből érkezik, amelyet az áruházkód tölt fel; ha ez 3 értéket ad vissza, a végpont ezt küldi:
{"c1":"<!--blockstudio/acme/cart-count--> <a href=\"/cart/\" class=\"cart-count\">\n Cart <span class=\"cart-count__badge\">3</span>\n </a>\n"}
A loading: "visible" elhalasztja a kérést, amíg a jelölő be nem kerül a nézetablakba, a IntersectionObserver használatával. Az egyszerre láthatóvá váló szigeteket továbbra is egyetlen kérés kötegeli. A event egy ablakeseményt nevez meg, amely újra lekéri a szigetet, így a kosárba helyezést végző hívás után a szkriptnek csak jeleznie kell az eseményt:
window.dispatchEvent(new Event('acme:cart-updated'));
Reagálás az előtér kódjában
Az események a jelölőtől indulnak tovább, így egyetlen figyelő az document elemen minden szigetet lefed. Az event.detail.name tartalmazza a blokk nevét:
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);
});
Csere után a futtatókörnyezet először az blockstudio:island:rendered, majd az blockstudio:island:hydrate eseményt küldi el. Hiba esetén a helyőrző a helyén marad, és lefut az blockstudio:island:error. A hidratált szigetek ("island": "hydrate") teljesen kihagyják a kérést: a teljes HTML már az oldalon van, és csak az hydrate eseményt kapják meg, ami jól illik a gyorsítótárazással kompatibilis interaktív blokkokhoz, például a fülekhez.
Részletek gyorsítótárazása
Alapértelmezés szerint a rendszer minden kérésnél újrarendereli a részleteket. A fenti üdvözlés rövid idejű gyorsítótárazást használ:
{
"cache": {
"ttl": 300,
"per": "user"
}
}
Az per: "user" a gyorsítótárazott részletet a felhasználó WordPress azonosítója szerint különbözteti meg, a névtelen kéréseket pedig soha nem tárolja így, ezért két névtelen látogató nem osztozhat egy felhasználónak szánt bejegyzésen. Az per: "global" ugyanahhoz a blokkhoz és attribútumokhoz egyetlen részletet használ, ami az élő, de nem személyes tartalomhoz, például a készletszinthez megfelelő. Az ttl alapértelmezett értéke 60 másodperc, az cache: true pedig 60 másodperces globális gyorsítótár.
A biztonsági modell
A végpont nyilvános, de nem általános blokk-renderelő. Csak akkor renderel egy bejegyzést, ha az alábbi feltételek mind teljesülnek:
- a blokk regisztrálva van, dinamikus, és az
island.modeértékedynamic - az aláírás egyezik a blokknévvel és a szűrő után megmaradó attribútumokkal: csak a blokk sémájában és a sziget engedélyezőlistájában egyaránt szereplő kulcsokkal
Az aláírás a normalizált blokkneven és attribútumokon számított HMAC-SHA256, amelyhez a kiszolgáló webhely auth sóját használja kulcsként. Az aláírások a webhelyen, rendereléskor jönnek létre, és soha nem kerülnek bele előre a témába. Ennek két következménye van. Az előnézeti környezetben renderelt dokumentumok az előnézeti környezet aláírásait hordozzák, ezért a dokumentumokat azon a webhelyen renderelje, amely kiszolgálja őket. A WordPress sók cseréje érvénytelenít minden aláírást a tárolt dokumentumokban, ezért a só cseréje után törölje a statikus előrenderelést.
Egy kérés legfeljebb 50 szigetet fogad; ennél több esetén HTTP 413 tér vissza. A korlát módosításához használja ezt: blockstudio/islands/max_per_request. Az aláírási horgok (blockstudio/islands/signature_payload, blockstudio/islands/signature, blockstudio/islands/verify_signature) azoknak a kiszolgálóknak állnak rendelkezésére, amelyek másik sémát igényelnek.
Mikor ne használjon szigetet
A részletek nincsenek benne a kezdeti HTML tartalomban, ezért a keresőrobotok nem látják őket. A SEO szempontjából releváns tartalmat tartsa meg a normál renderelésben. Dinamikus szigeteket használjon olyan tartalmakhoz, amelyek az oldalváz után érkezhetnek: fiókhivatkozásokhoz, kosárállapothoz, ajánlásokhoz és jogosultsághoz kötött vezérlőelemekhez. Ha az egész oldal személyre szabott, például egy fiók-irányítópult, inkább sorolja fel az útvonalát itt: dynamicPaths, és renderelje élőben.
Következő lépések
- Szigetek referencia: minden beállítás, a helyőrzők keresési sorrendje, az PHP API és a horgok.
- WordPress kiszolgálása statikus HTML-ként: az ezekhez a szigetekhez tervezett gyorsítótár.
- Statikus előrenderelés referencia:
serveLoggedIn, dinamikus útvonalak és korai kiszolgálás. - Interaktív komponensek: kliensoldali viselkedés azokhoz a blokkokhoz, amelyeknek több kell a mount eseménynél.