Liigu sisu juurde

Isikupärastatud killud vahemällu salvestatud lehtedel

Staatilisest vahemälust serveeritud leht on kõigi jaoks ühesugune. Just selleks lehte vahemällu salvestataksegi, kuid siin peitub ka probleem: päis peaks ütlema sisseloginud kliendile „Tere, Ada” ja ostukorviikoon näitama kolme eset. Kui mall haruneb praeguse kasutaja järgi, salvestab vahemälu kas ühe külastaja tervituse kõigi jaoks või peab lehe täielikult vahele jätma.

Blockstudio dünaamilised saarekesed lahutavad need kaks vajadust. Vahemällu salvestatud HTML sisaldab vahemälusõbralikku kohatäitjat. Pärast lehe laadimist küsib väike käituskeskkond WordPress-lt külastaja enda päringuga isikliku fragmendi ja asendab sellega kohatäitja. Leht jääb vahemällu salvestatavaks ning dünaamiline on ainult fragment.

Selles juhendis luuakse kaks saarekest: tervitus ja ostukorvi kogus. Samuti vaadatakse läbi, mida sisaldab vahemällu salvestatud leht, milline näeb välja fragmendipäring ja kuidas otspunkt tuvastab külastaja. Juhend täiendab artiklit Serving WordPress as Static HTML.

Kuidas dünaamiline saareke toimib

  1. Plokk renderdab oma kohatäitja markerelemendi sisse. Marker sisaldab ploki nime, lubatud atribuutide loendit ja serveris loodud allkirja.
  2. Kuna renderdatud leht sisaldab markerit, lisab Blockstudio saarekese käituskeskkonna. Ilma saarekesteta lehtedel saarekese JavaScript ei laadita.
  3. Käituskeskkond kogub valmis markerid ja saadab ühe koondatud POST-i aadressile /wp-json/blockstudio/v1/island/render.
  4. Otspunkt kontrollib iga allkirja, renderdab ploki külastaja päringu kontekstis ja tagastab fragmendid.
  5. Käituskeskkond asendab iga kohatäitja ja saadab sündmused välja.

Plokiredaktoris renderdatakse plokk tavapäraselt, ilma kohatäitjata.

1. samm: tervitusplokk

Looge plokk kolme failiga:

Kood
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" muudab selle fragmendipäringuga saarekeseks. tag määrab markerelemendi, et saareke saaks asuda tekstisiseselt navigeerimisribal. attributes on lubatud plokiatribuutide loend, mis saadetakse fragmendipäringuga kaasa; loendist puuduvat ei saadeta ega allkirjastata. cache käsitletakse allpool.

Vahemällu salvestatud leht sisaldab kohatäitjat. See peab olema igale külastajale ohutu kuvada, seega ei sisalda see kasutajaandmeid. „Konto” link sobib kõigile:

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

Põhimall renderdab tegeliku fragmendi:

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

Praeguse kasutaja põhjal hargnemine on siin sobiv: see mall käivitub ainult fragmendipäringu puhul, mitte kunagi vahemällu salvestatud lehe jaoks.

Paigutage see sinna, kus päis renderdatakse:

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

Toimivad ka plokisildid: <bs:acme-greeting /> või <block name="acme/greeting" />.

2. samm: vahemällu salvestatud lehe sisu

Serveris renderdades loob plokk ainult markeri ja kohatäitja:

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>

Renderdage see kord anonüümse külastajana ja kord sisseloginud kasutajana: saadud kaks stringi on baidihaaval identsed. See ongi omadus, mida vajab staatiline eelrenderdus, kui serveLoggedIn on lubatud: ükskõik kes renderduse käivitab, salvestatud dokument on sama ja sinna ei saa sattuda isiklikke andmeid.

3. samm: fragmendipäring

Käituskeskkond saadab kõik valmis saarekesed ühe päringuga:

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

Vastus seotakse võtmega clientId. Sisseloginud külastaja puhul:

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

Kontrolli mitteläbinud kirje tagastatakse veakoodina, mitte HTML-ina, ning ülejäänud koondpäring töötab edasi. Siin muudeti teist kirjet guestLabel ilma vastava allkirjata ning kolmandas nimetati plokk, mis pole dünaamiline saareke:

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

Iga vastus sisaldab Cache-Control: no-store, no-cache, must-revalidate, max-age=0, Pragma: no-cache ja X-Robots-Tag: noindex. Otspunkt asub tee /wp-json all. Staatiline eelrenderdus jätab selle alati vahele, mistõttu ei salvesta fragmenti ei päritoluserveri vahemälu ega CDN, mis järgib päritoluserveri päiseid.

Kes on külastaja

Käituskeskkond saadab päringu koos credentials: 'same-origin'-iga, nii et brauser lisab päringule WordPress sisselogimisküpsise. WordPress REST API eirab küpsisepõhist autentimist tavaliselt ilma nonce’ita ning nonce ei saa asuda vahemällu salvestatud lehel. Saarekese otspunkt lahendab selle ise: sama päritoluga brauseripäringu korral kontrollib see küpsist logged_in ja taastab enne renderdamist kasutaja seansi.

Päritolude samasust kontrollitakse päise Sec-Fetch-Site järgi ning olemasolu korral võrreldakse päist Origin väärtusega home_url(). Teise päritoluga päring, millega juhuslikult kaasneb küpsis, renderdatakse anonüümsena. Seega ei renderda teiselt saidilt päring külastaja isiklikku fragmenti. Praktikas:

Päring Renderdatakse kui
Sama päritoluga fetch kehtiva sisselogimisküpsisega sisseloginud kasutaja
Teise päritoluga päring sama küpsisega anonüümne
Küpsis puudub anonüümne

Milline leht see on?

Lisage "context": true valikule blockstudio.island, kui fragment vajab selle lehe identiteeti. Marker allkirjastab seejärel päritud lehe postituse ID ja postituse tüübi koos atribuutidega. Fragmendis viitavad $block['postId'], $block['postType'], get_the_ID() ja get_queried_object_id() sellele lehele. Query Loop’i sees tähendab see endiselt välist päritud lehte, mitte tsükli elementi.

Lehe kontekst on valikuline ja kuulub ka fragmendi vahemälu võtmesse. Lõpp-punkt kontrollib ligipääsu uuesti, isegi vahemällu salvestatud fragmentide puhul, seega allkirjastatud marker ei paljasta lehte, mis on vahepeal muudetud privaatseks või parooliga kaitstuks. Konfigureerimise ja turvalisuse üksikasju vaadake jaotisest Lehe kontekst. Suvalisi URL ega päringuparameetreid uuesti ei kasutata.

4. samm: ise värskenduv ostukorvi kogus

Teine saareke näitab teistsugust kohatäitja stiili ja kahte käituskeskkonna valikut. Eraldi kohatäitjafaili asemel kontrollib mall tingimust $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; ?>

Kõigis mallikeeltes on samad lipud: isIsland, isIslandPlaceholder, isIslandFragment ja islandPhase ("normal", "hydrate", "placeholder" või "fragment"). Siin saadakse kogus filtrist acme/cart_count, mille täidab teie kaubanduskood. Kui filter tagastab 3, tagastab otspunkt:

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" lükkab päringu edasi, kuni marker jõuab vaatealasse, kasutades IntersectionObserver-i. Samal ajal nähtavale ilmuvad saarekesed koondatakse ikkagi ühte päringusse. event määrab aknasündmuse, mis hangib saarekese uuesti, nii et pärast ostukorvi lisamise kutset peab teie skript sellest vaid teada andma:

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

Esiotsa koodis reageerimine

Sündmused liiguvad markerist ülespoole, nii et üks kuulaja document-il hõlmab kõiki saari. event.detail.name sisaldab ploki nime:

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

Pärast vahetust väljastab käituskeskkond blockstudio:island:rendered ja seejärel blockstudio:island:hydrate. Tõrke korral jääb kohatäide oma kohale ja käivitub blockstudio:island:error. Hüdreeritud saared ("island": "hydrate") jätavad päringu täielikult vahele: kogu nende HTML on lehel olemas ja need saavad ainult sündmuse hydrate, mis sobib vahemäluga ühilduvatele interaktiivsetele plokkidele, näiteks vahekaartidele.

Fragmentide vahemällu salvestamine

Vaikimisi renderdatakse fragmendid iga päringu korral. Eespool olev tervitus kasutab lühiajalist vahemälu:

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

per: "user" eristab vahemällu salvestatud fragmenti WordPress kasutaja ID järgi ning anonüümseid päringuid selle alusel kunagi vahemällu ei salvestata, nii et kaks anonüümset külastajat ei saa jagada kirjet, mis on mõeldud kasutajale. per: "global" jagab sama ploki ja atribuutide korral üht fragmenti, mis sobib reaalajas muutuvale, kuid mitte isiklikule sisule, näiteks laoseisule. ttl vaikimisi kestus on 60 sekundit ja cache: true on 60-sekundiline globaalne vahemälu.

Turvamudel

Lõpp-punkt on avalik, kuid see pole üldotstarbeline plokirenderdaja. Kirje renderdatakse ainult siis, kui täidetud on kõik järgmised tingimused:

  • plokk on registreeritud ja dünaamiline ning sellel on island.mode väärtuseks dynamic
  • allkiri vastab ploki nimele ja filtrist läbi pääsenud atribuutidele: lubatud on ainult võtmed, mis on nii ploki skeemis kui ka saare lubatud loendis

Allkiri on HMAC-SHA256, mis arvutatakse normaliseeritud ploki nime ja atribuutide põhjal ning mille võtmeks on saiti teenindav auth sool. Allkirjad luuakse renderdamise ajal sellel saidil ja neid ei lisata kunagi teemasse. Sellest tuleneb kaks asja. Etapikeskkonnas renderdatud dokument sisaldab etapikeskkonna allkirju, seega renderdage dokumendid neid teenindaval saidil. WordPress soolade vahetamine muudab kõik salvestatud dokumentide allkirjad kehtetuks, seega tühjendage staatilise eeltöötluse vahemälu pärast soola vahetamist.

Ühes päringus saab olla kuni 50 saart; suurema arvu korral tagastatakse HTTP 413. Piirangut saab muuta valikuga blockstudio/islands/max_per_request. Allkirjakonksud (blockstudio/islands/signature_payload, blockstudio/islands/signature, blockstudio/islands/verify_signature) on saadaval hostidele, kes vajavad teistsugust skeemi.

Millal saart mitte kasutada

Fragmendid ei kuulu esialgsesse HTML-i, seega roomajad neid ei näe. Hoidke SEO-iga seotud sisu tavapärases renderduses. Kasutage dünaamilisi saari sisu jaoks, mis võib saabuda pärast lehe kesta: kontolinkide, ostukorvi oleku, soovituste ja õigustega piiratud juhtelementide jaoks. Kui kogu leht on isiklik, näiteks konto juhtpaneel, lisage selle tee hoopis faili dynamicPaths ja renderdage leht reaalajas.

Järgmised sammud