Ugrás a tartalomhoz

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

  1. 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.
  2. 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.
  3. 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.
  4. 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.
  5. 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:

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

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ő:

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

A fő sablon rendereli a valódi töredéket:

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

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
<?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ő:

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>

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:

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

A válasz kulcsa a clientId. Bejelentkezett látogató esetén:

JSON
{
    "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:

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

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:

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

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:

JSON
{"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:

JavaScript
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:

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

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:

JSON
{
  "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éke dynamic
  • 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