Szigetek
A blokkszigetek a normál Blockstudio renderelési folyamatot használják, miközben a kérésfüggő kimenetet kiveszik a kezdeti HTML válaszból.
Ez akkor hasznos, ha egy oldalt intenzíven szeretne gyorsítótárazni, de egy blokk továbbra is függ az aktuális látogatótól, munkamenettől, kosártól, jogosultságoktól vagy más élő kéréskontextustól.
A Blockstudio blokkok továbbra is dinamikus WordPress blokkok. A szigetek nem alakítják őket előre lefordított statikus HTML-vé. Ehelyett a Blockstudio módosítja, mi jelenik meg az első kéréskor:
- a hidratált szigetek a szokásos, gyorsítótár-biztos HTML elemet jelenítik meg, és mount eseményt kapnak
- a dinamikus szigetek először gyorsítótár-biztos helyőrzőt jelenítenek meg, majd a látogató böngészőjéből lekérik a valódi részletet
Módok
Hidratált szigetek
Használjon hidratált szigetet, ha a szerver kimenete biztonságosan gyorsítótárazható, és a blokknak csak egy frontend mount jelzésre van szüksége.
{
"name": "acme/tabs",
"blockstudio": {
"island": "hydrate"
}
}
A teljes blokk HTML jelen van a kezdeti válaszban. A sziget futtatókörnyezete nem indít hozzá REST kérést. A jelölőn blockstudio:island:hydrate eseményt küld, hogy a frontend kód viselkedést társíthasson hozzá.
Dinamikus szigetek
Használjon dinamikus szigetet, ha a blokk valódi kimenetét a látogató kérési kontextusában kell renderelni.
{
"name": "acme/cart-count",
"blockstudio": {
"island": "dynamic"
}
}
A kezdeti válasz csak egy helyőrzőt tartalmaz. A böngésző az összes betöltésre kész dinamikus szigetet egyetlen kérésbe gyűjti ide:
POST /wp-json/blockstudio/v1/island/render
A végpont csak azokat a regisztrált Blockstudio blokkokat rendereli, amelyek dinamikusak, és blockstudio.island.mode értéke dynamic.
Konfiguráció
A island értéke lehet rövid forma vagy objektum.
{
"blockstudio": {
"island": true
}
}
A true és a "hydrate" egyaránt hidratált módot jelent. A "dynamic" dinamikus módot jelent.
{
"blockstudio": {
"island": {
"mode": "dynamic",
"tag": "section",
"attributes": ["productId", "variant"],
"placeholder": "cart-placeholder.php",
"loading": "visible",
"event": "cart:updated",
"cache": {
"ttl": 60,
"per": "user"
}
}
}
}
| Tulajdonság | Típus | Alapértelmezett | Leírás |
|---|---|---|---|
mode |
"hydrate" vagy "dynamic" |
"hydrate" |
Szigetmód. |
tag |
string |
"div" |
Jelölő burkolócímkéje. |
attributes |
string[] |
az összes blokk attribútuma | A dinamikus töredékek kéréseinek elküldött attribútumok engedélyezési listája. |
placeholder |
string |
automatikusan észlelve | Relatív helyőrzősablon-útvonal. |
loading |
"eager" vagy "visible" |
"eager" |
Mikor kérjen le a futtatókörnyezet egy dinamikus szigetet. |
event |
string |
nincs beállítva | Az az ablakesemény neve, amely frissít egy dinamikus szigetet. |
context |
boolean |
false |
A lekérdezett oldal bejegyzésazonosítójának és bejegyzéstípusának aláírása és visszaállítása dinamikus töredékekhez. |
cache |
boolean vagy object |
false |
Opcionális töredékgyorsítótárazási szabályzat. |
Oldalkörnyezet
A dinamikus töredékek általában az oldal keretétől függetlenül renderelődnek. Kapcsolja be az oldalazonosítást, ha a blokk oldalspecifikus beállításokat vagy kapcsolódó tartalmat olvas:
{
"blockstudio": {
"island": {
"mode": "dynamic",
"context": true,
"cache": { "ttl": 60, "per": "global" }
}
}
}
A jelölő a lekérdezett oldal postId és postType értékét tartalmazza az data-bs-island-context mezőben. Mindkét értéket a blokk nevével és az engedélyezett attribútumokkal együtt az oldalt kiszolgáló webhely titkos kulcsa írja alá. Módosításuk vagy kéréshez való hozzáadásuk érvényteleníti az aláírást. A futtatókörnyezet a már meglévő, kötegelt töredékkéréssel együtt küldi el őket, a láthatóság által és az események által kiváltott frissítéseknél is. Ez az bs_render_block(), az bs_block() és a blokkcímkék esetében is működik.
A töredék renderelésekor a $block['postId'], a $block['postType'], a get_the_ID() és a get_queried_object_id() erre az oldalra hivatkozik. A WordPress lekérdezési és bejegyzéshez kapcsolódó globális változók ezt követően visszaállnak, renderelési kivétel esetén is. Ez a lekérdezett oldal, nem pedig egy lekérdezési cikluson belüli elem. Nem játssza vissza a tetszőleges URL paramétereket, és nem állítja vissza az eredeti kérés URL értékét. Ha a HTML oldal kanonikus URL értékére van szüksége, használja a get_permalink($block['postId']) elemet. Az archívumok és a lekérdezett bejegyzés nélküli renderelések nem küldenek oldalazonosítót.
A végpont ellenőrzi, hogy az oldal még létezik-e, a bejegyzéstípus megegyezik-e az aláírttal, és az aktuális látogató elolvashatja-e, mielőtt a töredékgyorsítótárhoz fordulna. Az érvényes aláírás nem kerüli meg a privát bejegyzésekre vagy jelszavas védelemre, a sziget jogosultságára, az attribútumok engedélyezési listáira, illetve a blokk saját jogosultság-ellenőrzéseire vonatkozó szabályokat. Ha van oldalazonosító, az mindig része a töredékgyorsítótár kulcsának, ezért a különböző oldalakon található azonos blokkok és attribútumok soha nem osztanak meg töredéket. Használja a per: "user" elemet, vagy ne gyorsítótárazza a töredéket, ha a kimenet a látogatótól is függ.
Ha a context nincs megadva, vagy false értékű, a meglévő jelölők és a környezetfüggetlen működés változatlan marad. Ne helyezzen bizalmas adatokat a nyilvános jelölőbe.
Dinamikus helyőrzők
A dinamikus szigeteknek olyan helyőrzőt kell megjeleníteniük, amely biztonságos közös teljesoldalas gyorsítótárban. Ne tegyen látogatóspecifikus adatot a helyőrző ágába.
A Blockstudio a következő sorrendben keresi a helyőrzőket:
- a megadott
island.placeholderútvonal placeholder.phpplaceholder.blade.phpplaceholder.twigplaceholder.html- a normál sablon helyőrzőjelzőkkel
<div class="cart-count-placeholder">
Loading cart...
</div>
Ha nincs helyőrzőfájl, használja a normál sablon sablonjelzőit:
<?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; ?>
Ugyanezek az értékek a PHP, Twig és Blade sablonokban is elérhetők:
isIslandisIslandPlaceholderisIslandFragmentislandPhase
A islandPhase értéke "normal", "hydrate", "placeholder" vagy "fragment".
Futtatókörnyezeti viselkedés
A Blockstudio csak akkor illeszti be a sziget futtatókörnyezetét, ha a renderelt oldal tartalmaz szigetjelölőt. A szigeteket nem tartalmazó oldalakhoz nem kerül extra sziget-JavaScript.
Dinamikus szigetek esetén a futtatókörnyezet:
- összegyűjti az összes betöltésre kész jelölőt
- összevonja az azonos blokknévvel, attribútumokkal és aláíráspárral rendelkezőket
- egy összevont REST kérést küld
- minden helyőrzőt lecserél a visszakapott részletre
- elküldi a
blockstudio:island:renderedeseményt - elküldi a
blockstudio:island:hydrateeseményt
A loading: "eager" szigetek a futtatókörnyezet indulásakor azonnal megjelennek. A loading: "visible" szigetek a IntersectionObserver eseményre várnak. Ha egyszerre több látható sziget kerül a nézetbe, egyetlen kérésben gyűjtődnek össze.
A event frissíti a szigetet, amikor a megnevezett ablakesemény bekövetkezik:
window.dispatchEvent(new Event('cart:updated'));
Hiba esetén a helyőrző a helyén marad, és elküldi a következő eseményt:
blockstudio:island:error.
Részletvégpont
A sziget végpontja nyilvános, de nem általános blokkmegjelenítő API.
Minden jelölő a következőket tartalmazza:
- a blokk neve
- az engedélyezési listán szereplő attribútumok
- egy szerver által generált aláírás
A végpont csak akkor renderel, ha:
- a blokk regisztrálva van
- a blokk dinamikus WordPress blokk
- a blokk dinamikus Blockstudio szigetként van megjelölve
- a bejövő attribútumok megfelelnek a blokk sémájának és a sziget engedélyezési listájának
- az aláírás egyezik a normalizált blokknévvel és attribútumokkal
Az aláírások a kiszolgáló WordPress webhelyén, rendereléskor jönnek létre a webhely sóival és a szigetadatokkal. Nem exportálódnak és nem kerülnek beépítésre a témába.
A végpont válaszai gyorsítótárazásra nem alkalmasként vannak megjelölve. Ha részlet-gyorsítótárazásra van szüksége, használja ezt: island.cache.
Részlet-gyorsítótárazás
A dinamikus részletek alapértelmezés szerint nincsenek gyorsítótárazva.
{
"blockstudio": {
"island": {
"mode": "dynamic",
"cache": true
}
}
}
A true rövid ideig érvényes globális gyorsítótárat használ. Kifejezett vezérléshez használja az objektumformát:
{
"cache": {
"ttl": 120,
"per": "user"
}
}
per: "global" ugyanazt a gyorsítótárazott töredéket osztja meg azonos blokk, attribútumok és
engedélyezett oldalkontextus esetén.
per: "user" az aktuális WordPress felhasználói azonosító alapján változtatja a gyorsítótárat.
Programozott renderelés
A szigetek minden olyan helyen működnek, ahol Blockstudio blokkok renderelődnek:
bs_render_block([
'name' => 'acme/cart-count',
'data' => ['productId' => 42],
]);
echo bs_block([
'name' => 'acme/cart-count',
'data' => ['productId' => 42],
]);
Blokkcímkéken keresztül is működnek:
<bs:acme-cart-count product-id="42" />
<block name="acme/cart-count" productId="42" />
A kezdeti kimenet továbbra is a szigetjelölő és a helyőrző, a futtatókörnyezet pedig akkor kerül beillesztésre, ha a renderelt válasz tartalmazza ezt a jelölőt.
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);
A marker() ellenőrzi a blokk metaadatait. Dinamikus jelölők csak regisztrált dinamikus Blockstudio blokkokhoz készülnek, amelyeknél a island.mode értéke dynamic.
Hookok
Észlelés és jelölés:
blockstudio/islands/is_island
blockstudio/islands/mode
blockstudio/islands/attributes
blockstudio/islands/marker_tag
blockstudio/islands/marker_attributes
blockstudio/islands/placeholder
Végpont és renderelés:
blockstudio/islands/allowed
blockstudio/islands/max_per_request
blockstudio/islands/request_attributes
blockstudio/islands/fragment
A blockstudio/islands/max_per_request módosítja az egy összevont végpontkérésben elfogadott dinamikus szigetek maximális számát. Az alapértelmezett érték 50.
Futtatókörnyezeti konfiguráció:
blockstudio/islands/endpoint_url
blockstudio/islands/loading
Aláírások:
blockstudio/islands/signature_payload
blockstudio/islands/signature
blockstudio/islands/verify_signature
Életciklus-műveletek:
blockstudio/islands/registered
blockstudio/islands/rendered
Mikor ne használjon szigeteket
Ne használjon dinamikus szigetet olyan tartalomhoz, amelynél fontos a SEO. A dinamikus szigetrészletek nincsenek jelen a kezdeti HTML-ban, és nem indexelésre készültek.
Használjon normál renderelést vagy hidratált szigetet, ha a tartalom gyorsítótár-biztos, és a feltérképező robotok számára láthatónak kell lennie. Dinamikus szigetet csak olyan tartalomhoz használjon, amely az oldalváz betöltése után is megérkezhet, például fiók-UI, kosárállapot, személyre szabott ajánlások vagy jogosultsághoz kötött vezérlők esetén.