Personoidut osat välimuistissa olevilla sivuilla
Staattisesta välimuistista tarjoiltu sivu on kaikille sama. Se on välimuistitallennuksen tarkoitus, mutta samalla myös ongelma: otsakkeessa pitäisi lukea “Hei, Ada” sisäänkirjautuneelle asiakkaalle, ja ostoskorikuvakkeen pitäisi näyttää kolme tuotetta. Jos mallipohja haarautuu nykyisen käyttäjän mukaan, välimuisti joko tallentaa yhden kävijän tervehdyksen kaikille tai koko sivu on jätettävä välimuistin ulkopuolelle.
Blockstudion dynaamiset saarekkeet erottavat nämä kaksi tarvetta toisistaan. Välimuistiin tallennettu HTML sisältää välimuistiystävällisen paikkamerkin. Sivun latauduttua pieni suoritusaikainen ympäristö pyytää WordPresslta henkilökohtaisen osan kävijän omassa pyynnössä ja korvaa paikkamerkin sillä. Sivu pysyy välimuistikelpoisena, ja vain kyseinen osa päivittyy reaaliaikaisesti.
Tässä oppaassa rakennetaan kaksi saareketta, tervehdys ja ostoskorin määrä, ja käydään läpi, mitä välimuistiin tallennettu sivu sisältää, miltä osapyyntö näyttää ja miten päätepiste tunnistaa kävijän. Opas täydentää ohjetta Staattisten WordPress-sivujen tarjoilu HTML.
Miten dynaaminen saareke toimii
- Lohko hahmonnetaan paikkamerkkinsä kanssa merkintäelementin sisälle. Merkintä sisältää lohkon nimen, sallittujen attribuuttien luettelon ja palvelimella luodun allekirjoituksen.
- Koska hahmonnetulla sivulla on merkintä, Blockstudio lisää saarekkeen suoritusaikaisen ympäristön. Sivuille, joilla ei ole saarekkeita, ei lisätä saarekkeen JavaScripta.
- Suoritusaikainen ympäristö kerää valmiit merkinnät ja lähettää yhden yhdistetyn
POSTn osoitteeseen/wp-json/blockstudio/v1/island/render. - Päätepiste tarkistaa allekirjoitukset, hahmontaa lohkon kävijän pyynnön kontekstissa ja palauttaa osat.
- Suoritusaikainen ympäristö korvaa paikkamerkit ja lähettää tapahtumat.
Lohko hahmonnetaan lohkoeditorissa normaalisti ilman paikkamerkkiä.
Vaihe 1: tervehdyslohko
Luo lohko kolmella tiedostolla:
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" }
]
}
}
mode: "dynamic" tekee tästä saarekkeen, joka lähettää osapyynnön.
tag määrittää merkintäelementin, jotta saareke voi olla tekstinsisäisesti navigointipalkissa. attributes sisältää sallittujen lohkoattribuuttien luettelon, ja nämä attribuutit lähetetään osapyynnön mukana. Luettelon ulkopuolisia tietoja ei lähetetä eikä allekirjoiteta. cache käsitellään tarkemmin jäljempänä.
Välimuistiin tallennettu sivu sisältää paikkamerkin. Sen on oltava turvallinen näytettäväksi jokaiselle kävijälle, joten se ei saa sisältää käyttäjätietoja. “Tili”-linkki toimii kaikille:
<a href="<?php echo esc_url( home_url( '/account/' ) ); ?>">Account</a>
Päämallipohja hahmontaa varsinaisen osan:
<?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; ?>
Nykyisen käyttäjän mukaan haarautuminen sopii tähän: tämä mallipohja suoritetaan vain osapyynnön yhteydessä, ei koskaan välimuistiin tallennetun sivun yhteydessä.
Lisää se kohtaan, jossa otsake hahmonnetaan:
<?php echo bs_block( array( 'name' => 'acme/greeting' ) ); ?>
Myös lohkotunnisteet toimivat: <bs:acme-greeting /> tai
<block name="acme/greeting" />.
Vaihe 2: välimuistiin tallennetun sivun sisältö
Palvelimella hahmonnettuna lohko tuottaa vain merkinnän ja paikkamerkin:
<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>
Hahmonna se kerran anonyyminä kävijänä ja kerran sisäänkirjautuneena käyttäjänä. Tuloksena saadut merkkijonot ovat täsmälleen samat tavu tavulta. Juuri tätä staattinen esihahmonnus serveLoggedInn ollessa käytössä edellyttää: riippumatta siitä, kuka käynnistää hahmonnuksen, tallennettu dokumentti on sama, eikä siihen voi päätyä mitään henkilökohtaista.
Vaihe 3: osapyyntö
Suoritusaikainen ympäristö lähettää jokaisen valmiin saarekkeen samassa pyynnössä:
{
"islands": [
{
"clientId": "a1",
"name": "acme/greeting",
"attributes": {
"guestLabel": "Sign in"
},
"signature": "a7311ba9f6abf3c993edfdd7d49d2fa23bfa068f715b96637c35ef30de8b2043"
}
]
}
Vastauksen avaimena on clientId. Sisäänkirjautuneelle kävijälle:
{
"a1": "<!--blockstudio/acme/greeting--> <a href=\"https://example.com/account/\">\n Hi, Ada </a>\n"
}
Vahvistuksessa epäonnistuva merkintä palautetaan virhekoodina HTMLn sijaan, eikä se pysäytä muun erän käsittelyä. Tässä toisessa merkinnässä guestLabel muuttui ilman vastaavaa allekirjoitusta, ja kolmannessa nimettiin lohko, joka ei ole dynaaminen saareke:
{
"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"
}
}
Jokaisen vastauksen mukana lähetetään Cache-Control: no-store, no-cache, must-revalidate, max-age=0,
Pragma: no-cache ja X-Robots-Tag: noindex. Päätepiste sijaitsee polussa /wp-json, jonka staattinen esihahmonnus aina ohittaa. Siksi osaa ei tallenna välimuistiin alkuperäpalvelimen välimuisti eikä CDN, joka noudattaa alkuperäpalvelimen otsakkeita.
Kävijän tunnistaminen
Suoritusaikainen ympäristö lähettää pyynnön credentials: 'same-origin'n kanssa, joten selain sisällyttää mukaan WordPress-kirjautumisevästeen. WordPress REST API ohittaa tavallisesti evästeisiin perustuvan tunnistautumisen, jos mukana ei ole nonce-arvoa, eikä nonce-arvo voi olla välimuistiin tallennetulla sivulla. Saarekkeen päätepiste hoitaa tämän itse: saman alkuperän selainpyynnössä se vahvistaa logged_in-evästeen ja palauttaa käyttäjän tunnistetuksi ennen hahmonnusta.
Sama alkuperä päätellään Sec-Fetch-Site-otsakkeesta sekä Origin-otsakkeesta, jos se on mukana, vertaamalla niitä arvoon home_url(). Toisesta alkuperästä tuleva pyyntö, jossa sattuu olemaan eväste, hahmonnetaan anonyyminä. Siksi toiselta sivustolta tulevassa pyynnössä ei koskaan hahmonneta kävijän henkilökohtaista osaa. Käytännössä:
| Pyyntö | Hahmonnetaan käyttäjänä |
|---|---|
| Saman alkuperän pyyntö kelvollisella kirjautumisevästeellä | sisäänkirjautunut käyttäjä |
| Eri alkuperästä tuleva pyyntö samalla evästeellä | anonyymi |
| Ei evästettä | anonyymi |
Mikä sivu tämä on?
Lisää "context": true kohteeseen blockstudio.island, kun fragmentti tarvitsee sivunsa tunnisteen. Merkki allekirjoittaa tällöin kysytyn sivun artikkelin tunnisteen ja artikkelityypin attribuuttien ohella. Fragmentissa $block['postId'], $block['postType'], get_the_ID() ja get_queried_object_id() viittaavat kyseiseen sivuun. Query Loopin sisällä tämä tarkoittaa edelleen ulompaa kysyttyä sivua, ei silmukan kohdetta.
Sivun konteksti on valinnainen, ja se on myös osa fragmenttivälimuistin avainta. Päätepiste tarkistaa käyttöoikeudet uudelleen myös välimuistissa olevien fragmenttien kohdalla, joten allekirjoitettu merkki ei paljasta sivua, joka on sittemmin muutettu yksityiseksi tai suojattu salasanalla. Katso Sivun konteksti asetuksia ja tietoturvaa koskevat tiedot. Mitään mielivaltaisia URL- tai kyselyparametreja ei toisteta.
Vaihe 4: itsensä päivittävä ostoskorin määrä
Toinen saareke näyttää toisenlaisen paikkamerkin ja kaksi suoritusaikaisen ympäristön valintaa. Erillisen paikkamerkkitiedoston sijaan mallipohja tarkistaa $isIslandPlaceholdern:
{
"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; ?>
Samat liput ovat käytössä kaikissa mallipohjakielissä: isIsland,
isIslandPlaceholder, isIslandFragment ja islandPhase ("normal",
"hydrate", "placeholder" tai "fragment"). Tässä määrä tulee acme/cart_count-suodattimesta, jonka verkkokauppakoodi täyttää. Kun se palauttaa arvon 3, päätepiste palauttaa:
{"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" lykkää pyyntöä siihen asti, että merkintä tulee näkymäalueelle, käyttäen IntersectionObservera. Samaan aikaan näkyvät saarekkeet yhdistetään silti yhdeksi pyynnöksi. event nimeää ikkunatapahtuman, joka hakee saarekkeen tiedot uudelleen. Ostoskoriin lisäämisen jälkeen skriptin tarvitsee siis vain ilmoittaa tapahtumasta:
window.dispatchEvent(new Event('acme:cart-updated'));
Reagointi käyttöliittymän koodissa
Tapahtumat kuplivat merkistä, joten yksi kuuntelija kohteessa document kattaa kaikki saarekkeet. event.detail.name sisältää lohkon nimen:
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);
});
Vaihdon jälkeen suoritusaika lähettää ensin tapahtuman blockstudio:island:rendered ja sitten tapahtuman blockstudio:island:hydrate. Jos vaihto epäonnistuu, paikkamerkki pysyy paikallaan ja tapahtuma blockstudio:island:error laukeaa. Hydratut saarekkeet ("island": "hydrate") ohittavat pyynnön kokonaan: niiden koko HTML on sivulla, ja ne vastaanottavat vain tapahtuman hydrate. Tämä sopii välimuistin kanssa yhteensopiviin interaktiivisiin lohkoihin, kuten välilehtiin.
Fragmenttien välimuistitus
Fragmentit renderöidään oletusarvoisesti jokaisella pyynnöllä. Yllä oleva tervehdys ottaa käyttöön lyhyen välimuistin:
{
"cache": {
"ttl": 300,
"per": "user"
}
}
per: "user" muuttaa välimuistissa olevan fragmentin käyttäjän WordPress ID:n mukaan, eikä anonyymejä pyyntöjä koskaan tallenneta siihen, joten kaksi anonyymiä kävijää eivät voi jakaa käyttäjälle tarkoitettua merkintää. per: "global" jakaa saman lohkon ja määritteiden kesken yhden fragmentin, mikä sopii reaaliaikaiseen mutta ei henkilökohtaiseen sisältöön, kuten varastotilanteeseen. ttl on oletusarvoisesti 60 sekuntia, ja cache: true on 60 sekunnin yleinen välimuisti.
Tietoturvamalli
Päätepiste on julkinen, mutta se ei ole yleiskäyttöinen lohkojen renderöijä. Se renderöi merkinnän vain, kun kaikki seuraavat ehdot täyttyvät:
- lohko on rekisteröity, dynaaminen ja sen
island.mode-arvoksi on asetettudynamic - allekirjoitus vastaa lohkon nimeä ja suodatuksen läpäiseviä määritteitä: mukana ovat vain avaimet, jotka ovat sekä lohkon skeemassa että saarekkeen sallittujen arvojen luettelossa
Allekirjoitus on HMAC-SHA256, joka lasketaan normalisoidusta lohkon nimestä ja määritteistä ja jonka avaimena käytetään palvelevan sivuston auth-suolaa. Allekirjoitukset luodaan renderöinnin yhteydessä kyseisellä sivustolla, eikä niitä koskaan sisällytetä teemaan. Tästä seuraa kaksi asiaa. Esikatseluympäristössä renderöity dokumentti sisältää esikatseluympäristön allekirjoitukset, joten renderöi dokumentit niitä palvelevalla sivustolla. Lisäksi WordPress-suolojen vaihtaminen mitätöi kaikki tallennettujen dokumenttien allekirjoitukset, joten tyhjennä staattinen esirenderöinti suolan vaihtamisen jälkeen.
Yksi pyyntö hyväksyy enintään 50 saareketta; suurempi määrä palauttaa HTTP 413. Muuta rajaa asetuksella blockstudio/islands/max_per_request. Allekirjoituskoukut (blockstudio/islands/signature_payload, blockstudio/islands/signature, blockstudio/islands/verify_signature) ovat käytettävissä ympäristöissä, jotka tarvitsevat toisenlaisen menetelmän.
Milloin saareketta ei kannata käyttää
Fragmentit eivät kuulu alkuperäiseen HTML-sisältöön, joten indeksoijat eivät näe niitä. Pidä SEO-kannalta olennainen sisältö tavallisessa renderöinnissä. Käytä dynaamisia saarekkeita sisältöön, joka voi saapua sivun rungon jälkeen: tililinkkeihin, ostoskorin tilaan, suosituksiin ja käyttöoikeuksin rajattuihin ohjaimiin. Kun koko sivu on henkilökohtainen, kuten tilin hallintapaneeli, lisää sen polku sen sijaan kohteeseen dynamicPaths ja renderöi sivu reaaliaikaisesti.
Seuraavat vaiheet
- Saarekkeiden viite: kaikki asetukset, paikkamerkkien hakujärjestys, PHP API ja koukut.
- Staattisen WordPress-sisällön tarjoaminenHTML: välimuisti, jota varten nämä saarekkeet on suunniteltu.
- Staattisen esirenderöinnin viite:
serveLoggedIn, dynaamiset polut ja varhainen tarjoilu. - Interaktiiviset komponentit: lohkojen asiakaspuolen toiminta, kun tarvitaan muutakin kuin kiinnitystapahtuma.