Preskočiť na obsah

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.

JSON
{
  "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.

JSON
{
  "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:

Text
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.

JSON
{
  "blockstudio": {
    "island": true
  }
}

true aj "hydrate" znamenajú hydratovaný režim. "dynamic" znamená dynamický režim.

JSON
{
  "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:

JSON
{
  "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í:

  1. výslovná cesta island.placeholder
  2. placeholder.php
  3. placeholder.blade.php
  4. placeholder.twig
  5. placeholder.html
  6. bežná šablóna s príznakmi zástupného prvku
PHP
<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
<?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:

  • isIsland
  • isIslandPlaceholder
  • isIslandFragment
  • islandPhase

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:

  1. zhromaždí všetky pripravené značky
  2. odstráni duplicitné dvojice rovnakého názvu bloku, atribútov a podpisu
  3. odošle jednu zoskupenú požiadavku REST
  4. nahradí každý zástupný prvok vráteným fragmentom
  5. vyvolá blockstudio:island:rendered
  6. 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:

JavaScript
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.

JSON
{
  "blockstudio": {
    "island": {
      "mode": "dynamic",
      "cache": true
    }
  }
}

true používa krátkodobú globálnu vyrovnávaciu pamäť. Na výslovné nastavenie použite objektovú podobu:

JSON
{
  "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:

PHP
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:

HTML
<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

PHP
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:

PHP
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:

PHP
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:

PHP
blockstudio/islands/endpoint_url
blockstudio/islands/loading

Podpisy:

PHP
blockstudio/islands/signature_payload
blockstudio/islands/signature
blockstudio/islands/verify_signature

Akcie životného cyklu:

PHP
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.