Otočki
Otočki blokov ohranijo običajni upodabljalni cevovod Blockstudio, medtem ko izhod, specifičen za zahtevo, premaknejo iz začetnega odgovora HTML.
To je uporabno, kadar mora biti stran intenzivno predpomnjena, vendar je en blok še vedno odvisen od trenutnega obiskovalca, seje, košarice, dovoljenj ali drugega konteksta sprotne zahteve.
Bloki Blockstudio so še vedno dinamični bloki WordPress. Otočki jih ne pretvorijo v vnaprej prevedene statične HTML. Namesto tega Blockstudio spremeni to, kar se izriše ob prvi zahtevi:
- hidrirani otočki izrišejo običajni izhod HTML, varen za predpomnjenje, in prejmejo dogodek priklopa
- dinamični otočki najprej izrišejo nadomestni element, varen za predpomnjenje, nato pa iz brskalnika obiskovalca pridobijo pravi fragment
Načini
Hidrirani otočki
Hidrirani otoček uporabite, kadar je strežniški izhod varen za predpomnjenje in blok potrebuje le signal za priklop v sprednjem delu.
{
"name": "acme/tabs",
"blockstudio": {
"island": "hydrate"
}
}
Celoten blok HTML je prisoten v začetnem odgovoru. Izvajalno okolje otočkov zanj ne pošlje zahteve REST. Na označevalniku sproži blockstudio:island:hydrate, da lahko koda sprednjega dela doda vedenje.
Dinamični otočki
Dinamični otoček uporabite, kadar je treba pravi izhod bloka izrisati v kontekstu zahteve obiskovalca.
{
"name": "acme/cart-count",
"blockstudio": {
"island": "dynamic"
}
}
Začetni odgovor vsebuje samo nadomestni element. Brskalnik združi vse pripravljene dinamične otočke v eno zahtevo na:
POST /wp-json/blockstudio/v1/island/render
Končna točka izriše samo registrirane bloke Blockstudio, ki so dinamični in imajo blockstudio.island.mode nastavljeno na dynamic.
Konfiguracija
Vrednost island je lahko okrajšana oblika ali objekt.
{
"blockstudio": {
"island": true
}
}
true in "hydrate" pomenita hidrirano. "dynamic" pomeni dinamično.
{
"blockstudio": {
"island": {
"mode": "dynamic",
"tag": "section",
"attributes": ["productId", "variant"],
"placeholder": "cart-placeholder.php",
"loading": "visible",
"event": "cart:updated",
"cache": {
"ttl": 60,
"per": "user"
}
}
}
}
| Lastnost | Vrsta | Privzeto | Opis |
|---|---|---|---|
mode |
"hydrate" ali "dynamic" |
"hydrate" |
Način otoka. |
tag |
string |
"div" |
Ovojna oznaka označevalnika. |
attributes |
string[] |
vsi atributi bloka | Seznam dovoljenih atributov, poslanih zahtevam za dinamične fragmente. |
placeholder |
string |
samodejno zaznano | Relativna pot do predloge nadomestnega mesta. |
loading |
"eager" ali "visible" |
"eager" |
Kdaj naj izvajalno okolje pridobi dinamični otok. |
event |
string |
ni nastavljeno | Ime dogodka okna, ki osveži dinamični otok. |
context |
boolean |
false |
Podpiše in obnovi ID objave ter vrsto objave poizvedene strani za dinamične fragmente. |
cache |
boolean ali object |
false |
Izbirna politika predpomnjenja fragmentov. |
Kontekst strani
Dinamični fragmenti se običajno upodabljajo neodvisno od ogrodja strani. Če vaš blok bere nastavitve, značilne za stran, ali povezano vsebino, omogočite uporabo njene identitete:
{
"blockstudio": {
"island": {
"mode": "dynamic",
"context": true,
"cache": { "ttl": 60, "per": "global" }
}
}
}
Označevalnik vključuje postId in postType poizvedene strani v data-bs-island-context. Obe vrednosti sta podpisani z imenom bloka in dovoljenimi atributi s skrivnostjo spletnega mesta, ki streže vsebino. Brez neveljavnosti podpisa ju ni mogoče spremeniti ali dodati zahtevi. Izvajalno okolje ju pošlje skupaj z obstoječo paketno zahtevo za fragmente, tudi pri vidnih osvežitvah in osvežitvah na podlagi dogodkov. To deluje tudi z bs_render_block(), bs_block() in oznakami blokov.
Med upodabljanjem fragmenta se $block['postId'], $block['postType'], get_the_ID() in get_queried_object_id() nanašajo na to stran. Po upodabljanju se obnovijo poizvedba WordPress in globalne spremenljivke objave, tudi če med upodabljanjem pride do izjeme. To je poizvedena stran, ne element znotraj zanke poizvedbe. Ne ponovi poljubnih parametrov URL in ne obnovi izvirnega URL zahteve. Če potrebujete kanonični URL strani HTML, uporabite get_permalink($block['postId']). Arhivi in upodabljanja brez poizvedene objave ne pošljejo identitete strani.
Končna točka preveri, ali stran še obstaja, ali ima podpisano vrsto objave in ali jo trenutni obiskovalec lahko bere, preden preveri predpomnilnik fragmentov. Veljaven podpis ne obide zaščite zasebnih objav ali z geslom zaščitenih objav, upravičenosti otoka, seznamov dovoljenih atributov ali lastnih preverjanj dovoljenj vašega bloka. Ko je identiteta strani na voljo, je vedno del ključa predpomnilnika fragmentov, zato isti blok z enakimi atributi na različnih straneh nikoli ne deli fragmenta. Če je izhod odvisen tudi od obiskovalca, uporabite per: "user" ali onemogočite predpomnjenje fragmentov.
Če je context izpuščen ali je false, obstoječi označevalniki in vedenje brez konteksta ostanejo nespremenjeni. V javni označevalnik ne vstavljajte zaupnih podatkov.
Dinamični nadomestni elementi
Dinamični otočki morajo izrisati nadomestni element, varen za skupni predpomnilnik celotne strani. V vejo za nadomestni element ne vključujte podatkov, specifičnih za obiskovalca.
Blockstudio išče nadomestne elemente v tem vrstnem redu:
- izrecno navedena pot
island.placeholder placeholder.phpplaceholder.blade.phpplaceholder.twigplaceholder.html- običajna predloga z zastavicami za nadomestne elemente
<div class="cart-count-placeholder">
Loading cart...
</div>
Če datoteka za nadomestni element ne obstaja, uporabite zastavice predloge v običajni predlogi:
<?php if ( $isIslandPlaceholder ) : ?>
<div class="cart-count-placeholder">Loading cart...</div>
<?php else : ?>
<div class="cart-count">
<?php echo esc_html( acme_cart_count() ); ?>
</div>
<?php endif; ?>
Iste vrednosti so na voljo v predlogah PHP, Twig in Blade:
isIslandisIslandPlaceholderisIslandFragmentislandPhase
islandPhase je "normal", "hydrate", "placeholder" ali "fragment".
Delovanje izvajalnega okolja
Blockstudio vstavi izvajalno okolje otočkov samo, če izrisana stran vsebuje označevalnik otočka. Strani brez otočkov ne vsebujejo dodatne kode JavaScript za otočke.
Za dinamične otočke izvajalno okolje:
- zbere vse pripravljene označevalnike
- odstrani podvojene pare enakega imena bloka, atributov in podpisa
- pošlje eno združeno zahtevo REST
- vsak nadomestni element zamenja z vrnjenim fragmentom
- sproži
blockstudio:island:rendered - sproži
blockstudio:island:hydrate
Otočki loading: "eager" se izrišejo takoj, ko se zažene izvajalno okolje. Otočki loading: "visible" čakajo na IntersectionObserver. Če v vidno polje hkrati vstopi več vidnih otočkov, so združeni v eno zahtevo.
event osveži otoček, ko se sproži imenovani dogodek okna:
window.dispatchEvent(new Event('cart:updated'));
Ob napakah nadomestni element ostane na mestu in sproži se
blockstudio:island:error.
Končna točka za fragmente
Končna točka za otočke je javna, vendar ni splošni API za izris blokov.
Vsak označevalnik vsebuje:
- ime bloka
- atribute s seznama dovoljenih
- podpis, ustvarjen na strežniku
Končna točka izriše vsebino samo, kadar:
- je blok registriran
- je blok dinamični blok WordPress
- je blok označen kot dinamični otoček Blockstudio
- vhodni atributi ustrezajo shemi bloka in seznamu dovoljenih atributov otočka
- se podpis ujema z normaliziranim imenom bloka in atributi
Podpisi se ustvarijo med izrisom na strežniškem spletnem mestu WordPress na podlagi skrivnih vrednosti tega mesta in vsebine otočka. Niso izvoženi ali vgrajeni v temo.
Odgovori končne točke so označeni kot nepredpomnljivi. Za predpomnjenje fragmentov uporabite island.cache.
Predpomnjenje fragmentov
Dinamični fragmenti privzeto niso predpomnjeni.
{
"blockstudio": {
"island": {
"mode": "dynamic",
"cache": true
}
}
}
true uporablja kratek globalni predpomnilnik. Za izrecen nadzor uporabite obliko objekta:
{
"cache": {
"ttl": 120,
"per": "user"
}
}
per: "global" deli en predpomnjeni fragment za isti blok, atribute in
kontekst strani, če je ta možnost omogočena.
per: "user" predpomnilnik prilagodi trenutnemu ID-ju uporabnika WordPress.
Programski izris
Otočki delujejo povsod, kjer se izrisujejo bloki Blockstudio:
bs_render_block([
'name' => 'acme/cart-count',
'data' => ['productId' => 42],
]);
echo bs_block([
'name' => 'acme/cart-count',
'data' => ['productId' => 42],
]);
Delujejo tudi prek oznak blokov:
<bs:acme-cart-count product-id="42" />
<block name="acme/cart-count" productId="42" />
Začetni izhod še vedno vsebuje označevalnik otočka in nadomestni element, izvajalno okolje pa se vstavi, ko izrisani odgovor vsebuje ta označevalnik.
PHP API
Blockstudio\Islands::is_island('acme/cart-count');
Blockstudio\Islands::mode('acme/cart-count');
Blockstudio\Islands::registered();
Blockstudio\Islands::marker('acme/cart-count', $attributes, $html);
marker() preverja metapodatke bloka. Dinamični označevalniki se ustvarijo samo za registrirane dinamične bloke Blockstudio z island.mode, nastavljenim na dynamic.
Kavlji
Zaznavanje in označevalna koda:
blockstudio/islands/is_island
blockstudio/islands/mode
blockstudio/islands/attributes
blockstudio/islands/marker_tag
blockstudio/islands/marker_attributes
blockstudio/islands/placeholder
Končna točka in izris:
blockstudio/islands/allowed
blockstudio/islands/max_per_request
blockstudio/islands/request_attributes
blockstudio/islands/fragment
blockstudio/islands/max_per_request spremeni največje število dinamičnih otočkov, sprejetih v eni združeni zahtevi končne točke. Privzeta vrednost je 50.
Konfiguracija izvajalnega okolja:
blockstudio/islands/endpoint_url
blockstudio/islands/loading
Podpisi:
blockstudio/islands/signature_payload
blockstudio/islands/signature
blockstudio/islands/verify_signature
Dejanja življenjskega cikla:
blockstudio/islands/registered
blockstudio/islands/rendered
Kdaj ne uporabljati otočkov
Dinamičnega otočka ne uporabljajte za vsebino, ki je ključna za SEO. Fragmenti dinamičnega otočka niso prisotni v začetnem HTML in niso namenjeni indeksiranju.
Uporabite običajni izris ali hidrirani otoček, kadar je vsebina varna za predpomnjenje in mora biti vidna pajkom. Dinamični otoček uporabite samo za vsebino, ki se lahko naloži po ogrodju strani, na primer podatke o računu UI, stanje košarice, prilagojena priporočila ali kontrolnike, omejene z dovoljenji.