Ostrovy
Blokové ostrovy zachovávajú bežný vykresľovací postup Blockstudio bloku a zároveň presúvajú výstup špecifický pre požiadavku mimo úvodnej odpovede HTML.
Je to užitočné, keď sa má stránka intenzívne ukladať do vyrovnávacej pamäte, no jeden blok stále závisí od aktuálneho návštevníka, relácie, košíka, oprávnení alebo iného živého kontextu požiadavky.
Bloky Blockstudio sú stále dynamické bloky WordPress. Ostrovy ich nemenia na predkompilované statické HTML. Menia však to, čo sa vykreslí pri prvej požiadavke Blockstudio:
- hydratované ostrovy vykreslia bežný výstup HTML bezpečný pre vyrovnávaciu pamäť a prijmú udalosť pripojenia
- dynamické ostrovy najprv vykreslia zástupný prvok bezpečný pre vyrovnávaciu pamäť a potom načítajú skutočný fragment z prehliadača návštevníka
Režimy
Hydratované ostrovy
Použite hydratovaný ostrov, keď je výstup servera bezpečný pre vyrovnávaciu pamäť a blok potrebuje iba signál na pripojenie frontendu.
{
"name": "acme/tabs",
"blockstudio": {
"island": "hydrate"
}
}
Celý blok HTML je súčasťou úvodnej odpovede. Runtime ostrovov preň nevykoná požiadavku REST. Na značke vyvolá blockstudio:island:hydrate, aby k nej kód frontendu mohol pripojiť správanie.
Dynamické ostrovy
Dynamický ostrov použite vtedy, keď sa skutočný výstup bloku musí vykresliť v kontexte požiadavky návštevníka.
{
"name": "acme/cart-count",
"blockstudio": {
"island": "dynamic"
}
}
Úvodná odpoveď obsahuje iba zástupný prvok. Prehliadač zoskupí všetky pripravené dynamické ostrovy do jednej požiadavky na:
POST /wp-json/blockstudio/v1/island/render
Koncový bod vykresľuje iba registrované bloky Blockstudio, ktoré sú dynamické a majú hodnotu dynamic pre blockstudio.island.mode.
Konfigurácia
Hodnotou island môže byť skrátený zápis alebo objekt.
{
"blockstudio": {
"island": true
}
}
true aj "hydrate" znamenajú hydratovaný režim. "dynamic" znamená dynamický režim.
{
"blockstudio": {
"island": {
"mode": "dynamic",
"tag": "section",
"attributes": ["productId", "variant"],
"placeholder": "cart-placeholder.php",
"loading": "visible",
"event": "cart:updated",
"cache": {
"ttl": 60,
"per": "user"
}
}
}
}
| Vlastnosť | Typ | Predvolená hodnota | Opis |
|---|---|---|---|
mode |
"hydrate" alebo "dynamic" |
"hydrate" |
Režim ostrova. |
tag |
string |
"div" |
Značka obalu. |
attributes |
string[] |
všetky atribúty bloku | Povolený zoznam atribútov odosielaných v požiadavkách na dynamické fragmenty. |
placeholder |
string |
automaticky zistená | Relatívna cesta k šablóne zástupného symbolu. |
loading |
"eager" alebo "visible" |
"eager" |
Kedy má runtime načítať dynamický ostrov. |
event |
string |
nenastavené | Názov udalosti okna, ktorá obnoví dynamický ostrov. |
context |
boolean |
false |
Podpíše a obnoví ID príspevku a typ príspevku dopytovanej stránky pre dynamické fragmenty. |
cache |
boolean alebo object |
false |
Voliteľná politika vyrovnávacej pamäte fragmentov. |
Kontext stránky
Dynamické fragmenty sa zvyčajne vykresľujú nezávisle od obalu stránky. Ak váš blok číta nastavenia špecifické pre stránku alebo súvisiaci obsah, povoľte používanie identity stránky:
{
"blockstudio": {
"island": {
"mode": "dynamic",
"context": true,
"cache": { "ttl": 60, "per": "global" }
}
}
}
Značka obsahuje postId a postType dopytovanej stránky v data-bs-island-context. Obe hodnoty sú podpísané názvom bloku a povolenými atribútmi pomocou tajného kľúča obsluhujúcej stránky. Bez zneplatnenia podpisu ich nemožno zmeniť ani pridať do požiadavky. Runtime ich odosiela spolu s existujúcou dávkovou požiadavkou na fragmenty vrátane obnovení pri zobrazení a pri udalosti. Funguje to aj s bs_render_block(), bs_block() a značkami blokov.
Počas vykresľovania fragmentu sa $block['postId'], $block['postType'], get_the_ID() a get_queried_object_id() vzťahujú na danú stránku. Globálne premenné WordPress pre dopyt a príspevok sa obnovia po dokončení, a to aj po výnimke pri vykresľovaní. Ide o dopytovanú stránku, nie o položku v rámci Query Loop. Ľubovoľné parametre URL sa znova nespracujú a pôvodná požiadavka URL sa neobnoví. Ak potrebujete kanonické URL stránky HTML, použite get_permalink($block['postId']). Archívy a vykreslenia bez dopytovaného príspevku neposielajú identitu stránky.
Koncový bod pred kontrolou vyrovnávacej pamäte fragmentov overí, či stránka stále existuje, či má podpísaný typ príspevku a či si ju aktuálny návštevník môže prečítať. Platný podpis neobchádza ochranu súkromných príspevkov ani ochranu heslom, oprávnenosť ostrova, povolené zoznamy atribútov či vlastné kontroly oprávnení vášho bloku. Ak je identita stránky prítomná, vždy tvorí súčasť kľúča vyrovnávacej pamäte fragmentu, takže rovnaký blok a atribúty na rôznych stránkach nikdy nezdieľajú fragment. Ak výstup závisí aj od návštevníka, použite per: "user" alebo vyrovnávaciu pamäť fragmentov vypnite.
Ak vynecháte context alebo použijete false, existujúce značky a správanie nezávislé od kontextu zostanú nezmenené. Do verejnej značky nevkladajte dôverné údaje.
Dynamické zástupné prvky
Dynamické ostrovy majú vykresliť zástupný prvok bezpečný pre zdieľanú vyrovnávaciu pamäť celej stránky. Do vetvy zástupného prvku nevkladajte údaje špecifické pre návštevníka.
Blockstudio hľadá zástupné prvky v tomto poradí:
- výslovná cesta
island.placeholder placeholder.phpplaceholder.blade.phpplaceholder.twigplaceholder.html- bežná šablóna s príznakmi zástupného prvku
<div class="cart-count-placeholder">
Loading cart...
</div>
Ak súbor zástupného prvku neexistuje, použite príznaky šablóny v bežnej šablóne:
<?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; ?>
Rovnaké hodnoty sú dostupné v šablónach PHP, Twig a Blade:
isIslandisIslandPlaceholderisIslandFragmentislandPhase
islandPhase je "normal", "hydrate", "placeholder" alebo "fragment".
Správanie runtime
Blockstudio vloží runtime ostrovov iba vtedy, keď vykreslená stránka obsahuje značku ostrova. Stránky bez ostrovov nenačítajú žiadny ďalší kód JavaScript pre ostrovy.
Pri dynamických ostrovoch runtime:
- zhromaždí všetky pripravené značky
- odstráni duplicitné dvojice rovnakého názvu bloku, atribútov a podpisu
- odošle jednu zoskupenú požiadavku REST
- nahradí každý zástupný prvok vráteným fragmentom
- vyvolá
blockstudio:island:rendered - vyvolá
blockstudio:island:hydrate
Ostrovy loading: "eager" sa vykreslia hneď po spustení runtime. Ostrovy loading: "visible" čakajú na IntersectionObserver. Ak sa naraz zobrazí vo výreze obrazovky viac ostrovov, zoskupia sa do jednej požiadavky.
event obnoví ostrov, keď sa vyvolá pomenovaná udalosť okna:
window.dispatchEvent(new Event('cart:updated'));
Pri zlyhaní zostane zástupný prvok na mieste a vyvolá sa blockstudio:island:error.
Koncový bod fragmentov
Koncový bod ostrovov je verejný, nejde však o všeobecné API na vykresľovanie blokov.
Každá značka obsahuje:
- názov bloku
- atribúty z povoleného zoznamu
- podpis vygenerovaný serverom
Koncový bod vykresľuje obsah iba vtedy, keď:
- blok je zaregistrovaný
- blok je dynamický blok WordPress
- blok je označený ako dynamický ostrov Blockstudio
- prichádzajúce atribúty spĺňajú schému bloku a povolený zoznam pre ostrov
- podpis zodpovedá normalizovanému názvu bloku a atribútom
Podpisy sa generujú pri vykresľovaní na obsluhujúcej lokalite WordPress z jej saltov a údajov ostrova. Neexportujú sa ani nevkladajú do témy.
Odpovede koncového bodu sú označené ako nevhodné na ukladanie do vyrovnávacej pamäte. Ak chcete ukladať fragmenty do vyrovnávacej pamäte, použite island.cache.
Ukladanie fragmentov do vyrovnávacej pamäte
Dynamické fragmenty sa predvolene neukladajú do vyrovnávacej pamäte.
{
"blockstudio": {
"island": {
"mode": "dynamic",
"cache": true
}
}
}
true používa krátkodobú globálnu vyrovnávaciu pamäť. Na výslovné nastavenie použite objektovú podobu:
{
"cache": {
"ttl": 120,
"per": "user"
}
}
per: "global" zdieľa jednu fragmentovú vyrovnávaciu pamäť pre rovnaký blok, atribúty a kontext stránky s povoleným opt-in.
per: "user" mení vyrovnávaciu pamäť podľa aktuálneho ID používateľa WordPress.
Programové vykresľovanie
Ostrovy fungujú všade, kde sa vykresľujú bloky Blockstudio:
bs_render_block([
'name' => 'acme/cart-count',
'data' => ['productId' => 42],
]);
echo bs_block([
'name' => 'acme/cart-count',
'data' => ['productId' => 42],
]);
Fungujú aj prostredníctvom značiek blokov:
<bs:acme-cart-count product-id="42" />
<block name="acme/cart-count" productId="42" />
Úvodný výstup stále obsahuje značku ostrova a zástupný prvok; runtime sa vloží, keď vykreslená odpoveď obsahuje túto značku.
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() overuje metadáta bloku. Dynamické značky sa vytvárajú iba pre zaregistrované dynamické bloky Blockstudio s hodnotou dynamic pre island.mode.
Háčiky
Zisťovanie a značenie:
blockstudio/islands/is_island
blockstudio/islands/mode
blockstudio/islands/attributes
blockstudio/islands/marker_tag
blockstudio/islands/marker_attributes
blockstudio/islands/placeholder
Koncový bod a vykresľovanie:
blockstudio/islands/allowed
blockstudio/islands/max_per_request
blockstudio/islands/request_attributes
blockstudio/islands/fragment
blockstudio/islands/max_per_request mení maximálny počet dynamických ostrovov prijatých v jednej zoskupenej požiadavke na koncový bod. Predvolená hodnota je 50.
Konfigurácia runtime:
blockstudio/islands/endpoint_url
blockstudio/islands/loading
Podpisy:
blockstudio/islands/signature_payload
blockstudio/islands/signature
blockstudio/islands/verify_signature
Akcie životného cyklu:
blockstudio/islands/registered
blockstudio/islands/rendered
Kedy ostrovy nepoužívať
Dynamický ostrov nepoužívajte pre obsah, ktorý je dôležitý pre SEO. Fragmenty dynamických ostrovov nie sú súčasťou úvodného HTML a nie sú určené na indexovanie.
Ak je obsah bezpečný pre vyrovnávaciu pamäť a má byť viditeľný pre prehľadávače, použite bežné vykresľovanie alebo hydratovaný ostrov. Dynamický ostrov použite iba pre obsah, ktorý sa môže načítať po obale stránky, napríklad UI účtu, stav košíka, personalizované odporúčania alebo ovládacie prvky obmedzené oprávneniami.