Prilagojeni fragmenti na predpomnjenih straneh
Stran, ki jo streže statični predpomnilnik, je za vse enaka. To je namen predpomnjenja, hkrati pa tudi težava: glava želi prijavljenega kupca pozdraviti z »Živjo, Ada«, ikona košarice pa prikazati tri izdelke. Če se predloga razveji glede na trenutnega uporabnika, predpomnilnik shrani pozdrav enega obiskovalca za vse ali pa mora stran v celoti izpustiti.
Dinamični otočki v Blockstudio ločijo ti dve skrbi. Predpomnjeni HTML vsebuje nadomestno vsebino, varno za predpomnjenje. Ko se stran naloži, majhna izvajalna komponenta od WordPress zahteva osebni fragment v okviru zahteve obiskovalca in ga vstavi na ustrezno mesto. Stran ostane primerna za predpomnjenje, v živo pa se naloži samo fragment.
V tem vodniku ustvarimo dva otočka, pozdrav in število izdelkov v košarici, ter pokažemo, kaj vsebuje predpomnjena stran, kako je videti zahteva za fragment in kako končna točka ugotovi, kdo je obiskovalec. Vodnik se dopolnjuje z vodnikom Streženje WordPress kot statičnega HTML.
Kako deluje dinamični otoček
- Blok upodobi svojo nadomestno vsebino znotraj označevalnega elementa. Označevalnik vsebuje ime bloka, dovoljene atribute in podpis, ustvarjen na strežniku.
- Ker upodobljena stran vsebuje označevalnik, Blockstudio vstavi izvajalno komponento otočkov. Strani brez otočkov ne vključujejo kode za otočke JavaScript.
- Izvajalna komponenta zbere pripravljene označevalnike in pošlje en združen
POSTna/wp-json/blockstudio/v1/island/render. - Končna točka preveri vsak podpis, upodobi blok v kontekstu zahteve obiskovalca in vrne fragmente.
- Izvajalna komponenta zamenja nadomestno vsebino in sproži dogodke.
V urejevalniku blokov se blok upodobi običajno, brez nadomestne vsebine.
1. korak: blok pozdrava
Ustvarite blok s tremi datotekami:
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" omogoča otoček z zahtevo za fragment.
tag nastavi označevalni element, tako da je otoček lahko del vrstice v navigacijski vrstici. attributes je seznam dovoljenih atributov bloka, ki se pošljejo skupaj z zahtevo za fragment; nič, česar ni na seznamu, se ne pošlje ali podpiše. cache je podrobneje obravnavan v nadaljevanju.
Predpomnjena stran vsebuje nadomestno vsebino. Varna mora biti za prikaz vsakemu obiskovalcu, zato ne vsebuje uporabniških podatkov. Povezava »Račun« deluje za vse:
<a href="<?php echo esc_url( home_url( '/account/' ) ); ?>">Account</a>
Glavna predloga upodobi pravi fragment:
<?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; ?>
Razvejanje glede na trenutnega uporabnika je tu ustrezno: ta predloga se zažene samo za zahtevo za fragment, nikoli pa za predpomnjeno stran.
Vstavite ga, kamor koli se upodablja glava:
<?php echo bs_block( array( 'name' => 'acme/greeting' ) ); ?>
Delujejo tudi oznake blokov: <bs:acme-greeting /> ali
<block name="acme/greeting" />.
2. korak: vsebina predpomnjene strani
Ko blok upodobimo na strežniku, ustvari samo označevalnik in nadomestno vsebino:
<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>
Upodobite ga enkrat kot anonimni obiskovalec in enkrat kot prijavljeni uporabnik; dobljena niza sta enaka do zadnjega bajta. To je lastnost, ki jo potrebuje statično predhodno upodabljanje z omogočenim serveLoggedIn: ne glede na to, kdo sproži upodabljanje, je shranjeni dokument enak in v njem ne morejo končati osebni podatki.
3. korak: zahteva za fragment
Izvajalna komponenta v eni zahtevi pošlje vsak pripravljeni otoček:
{
"islands": [
{
"clientId": "a1",
"name": "acme/greeting",
"attributes": {
"guestLabel": "Sign in"
},
"signature": "a7311ba9f6abf3c993edfdd7d49d2fa23bfa068f715b96637c35ef30de8b2043"
}
]
}
Odgovor je razvrščen po ključu clientId. Za prijavljenega obiskovalca:
{
"a1": "<!--blockstudio/acme/greeting--> <a href=\"https://example.com/account/\">\n Hi, Ada </a>\n"
}
Vnos, ki ne prestane preverjanja, se vrne kot koda napake namesto HTML, ne da bi se preostali del skupine zahtev obravnaval kot neuspešen. Tu je bil pri drugem vnosu spremenjen guestLabel brez ustreznega podpisa, tretji pa je navedel blok, ki ni dinamični otoček:
{
"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"
}
}
Vsak odgovor vsebuje Cache-Control: no-store, no-cache, must-revalidate, max-age=0, Pragma: no-cache in X-Robots-Tag: noindex. Končna točka je pod /wp-json, ki jo statično predhodno upodabljanje vedno zaobide, zato niti izvorni predpomnilnik niti CDN, ki upošteva glave izvora, ne bo shranil fragmenta.
Kdo je obiskovalec
Izvajalna komponenta pošlje zahtevo z credentials: 'same-origin', zato brskalnik vključi prijavni piškotek WordPress. WordPress REST API običajno prezre avtentikacijo s piškotkom brez nonce, nonce pa ne more biti na predpomnjeni strani. Končna točka otočka to obravnava sama: pri zahtevi brskalnika z istega izvora preveri piškotek logged_in in pred upodabljanjem obnovi uporabniško sejo.
Isti izvor se določi na podlagi glave Sec-Fetch-Site in, kadar je prisotna, glave Origin v primerjavi z home_url(). Zahteva z drugega izvora, ki slučajno vsebuje piškotek, se upodobi kot anonimna, zato zahteva z drugega spletnega mesta nikoli ne upodobi osebnega fragmenta obiskovalca. V praksi:
| Zahteva | Upodobi kot |
|---|---|
| Zahteva fetch z istega izvora z veljavnim prijavnim piškotkom | prijavljeni uporabnik |
| Zahteva z drugega izvora z istim piškotkom | anonimni uporabnik |
| Brez piškotka | anonimni uporabnik |
Katera stran je to?
V blockstudio.island dodajte "context": true, kadar fragment potrebuje identiteto svoje strani. Oznaka nato poleg atributov podpiše ID objave in vrsto objave poizvedene strani. V fragmentu se $block['postId'], $block['postType'], get_the_ID() in get_queried_object_id() nanašajo na to stran. Znotraj zanke Query Loop to še vedno pomeni zunanjo poizvedeno stran, ne elementa zanke.
Kontekst strani je treba izrecno omogočiti in je tudi del ključa predpomnilnika fragmentov. Končna točka znova preveri dostop, tudi pri predpomnjenih fragmentih, zato podpisana oznaka ne razkrije strani, ki je medtem postala zasebna ali zaščitena z geslom. Za podrobnosti o konfiguraciji in varnosti glejte Kontekst strani. Samovoljni URL ali parametri poizvedbe se ne ponovijo.
4. korak: število izdelkov v košarici, ki se osvežuje samo
Drugi otoček prikazuje drug slog nadomestne vsebine in dve možnosti izvajalne komponente. Namesto ločene datoteke za nadomestno vsebino predloga preveri $isIslandPlaceholder:
{
"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; ?>
Enake zastavice so na voljo v vseh jezikih predlog: isIsland, isIslandPlaceholder, isIslandFragment in islandPhase ("normal", "hydrate", "placeholder" ali "fragment"). V tem primeru število izvira iz filtra acme/cart_count, ki ga napolni vaša prodajna koda; ko vrne 3, končna točka vrne:
{"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ži zahtevo, dokler označevalnik ne vstopi v vidno polje, pri čemer uporabi IntersectionObserver. Vidni otočki, ki se pojavijo hkrati, se še vedno združijo v eno zahtevo. event določa ime dogodka window, ki znova pridobi otoček, zato mora vaša skripta po klicu za dodajanje v košarico samo še sprožiti dogodek:
window.dispatchEvent(new Event('acme:cart-updated'));
Odzivanje v kodi vmesnika
Dogodki se širijo od označevalnika, zato en poslušalnik na document pokrije vsak otok. event.detail.name vsebuje ime bloka:
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 zamenjavi izvajalno okolje sproži blockstudio:island:rendered, nato pa blockstudio:island:hydrate. Ob napaki nadomestni element ostane na mestu in sproži se blockstudio:island:error. Hidrirani otoki ("island": "hydrate") zahtevo v celoti preskočijo: njihov celoten HTML je že na strani, prejmejo pa samo dogodek hydrate, kar ustreza interaktivnim blokom, varnim za predpomnjenje, kot so zavihki.
Predpomnjenje fragmentov
Fragmenti se privzeto upodobijo ob vsaki zahtevi. Zgornji pozdrav uporablja kratko predpomnjenje:
{
"cache": {
"ttl": 300,
"per": "user"
}
}
per: "user" spreminja predpomnjeni fragment glede na ID uporabnika WordPress, anonimne zahteve pa se nikoli ne predpomnijo na ta način, zato si dva anonimna obiskovalca ne moreta deliti vnosa, namenjenega uporabniku. per: "global" deli en fragment za isti blok in atribute, kar ustreza vsebini, ki je aktualna, a ni osebna, kot je stanje zaloge. ttl je privzeto nastavljeno na 60 sekund, cache: true pa je globalni predpomnilnik za 60 sekund.
Varnostni model
Končna točka je javna, vendar ne gre za splošni upodabljalnik blokov. Vnos upodobi samo, če so izpolnjeni vsi naslednji pogoji:
- blok je registriran, dinamičen in ima
island.modenastavljeno nadynamic - podpis se ujema z imenom bloka in atributi, ki ostanejo po filtriranju: samo ključi, prisotni tako v shemi bloka kot na seznamu dovoljenih za otok
Podpis je HMAC-SHA256 za normalizirano ime bloka in atribute, ustvarjen s soljo auth spletnega mesta, ki vsebino streže. Podpisi se ustvarijo ob upodabljanju na tem spletnem mestu in nikoli niso vnaprej vključeni v temo. Iz tega sledita dve posledici. Dokument, upodobljen na pripravljalnem okolju, vsebuje podpise tega okolja, zato dokumente upodabljajte na spletnem mestu, ki jih streže. Z rotacijo soli WordPress postanejo vsi podpisi v shranjenih dokumentih neveljavni, zato po rotaciji soli počistite statično predhodno upodobljeno vsebino.
Ena zahteva sprejme do 50 otokov; pri večjem številu vrne HTTP 413. Omejitev spremenite z blockstudio/islands/max_per_request. Kavlji za podpise (blockstudio/islands/signature_payload, blockstudio/islands/signature, blockstudio/islands/verify_signature) so na voljo gostiteljem, ki potrebujejo drugačno shemo.
Kdaj ne uporabiti otoka
Fragmentov ni v začetnem HTML, zato jih pajki ne vidijo. Vsebino, pomembno za SEO, ohranite v običajnem upodabljanju. Dinamične otoke uporabite za vsebino, ki se lahko naloži po ogrodju strani: povezave do računov, stanje košarice, priporočila in kontrolnike, omejene z dovoljenji. Če je celotna stran osebna, kot je nadzorna plošča računa, namesto tega navedite njeno pot v dynamicPaths in jo upodobite sproti.
Naslednji koraki
- Referenca za otoke: vse možnosti, vrstni red iskanja nadomestnih vrednosti, PHP API in kavlji.
- Streženje WordPress kot statični HTML: predpomnilnik, za katerega so ti otoki zasnovani.
- Referenca za statično predhodno upodabljanje:
serveLoggedIn, dinamične poti in zgodnje streženje. - Interaktivne komponente: vedenje blokov na strani odjemalca, ki potrebujejo več kot le dogodek ob namestitvi.