Přejít k obsahu

Ostrovy

Blokové ostrovy umožňují bloku zachovat běžný vykreslovací proces Blockstudio a zároveň přesunout výstup závislý na požadavku mimo počáteční odpověď HTML.

Hodí se to, když má být stránka intenzivně ukládána do cache, ale jeden blok přesto závisí na aktuálním návštěvníkovi, relaci, košíku, oprávněních nebo jiném aktuálním kontextu požadavku.

Bloky Blockstudio jsou stále dynamické bloky WordPress. Ostrovy z nich nedělají předkompilované statické HTML. Místo toho Blockstudio mění způsob vykreslení při prvním požadavku:

  • hydratované ostrovy vykreslí svůj běžný výstup HTML bezpečný pro cache a přijmou událost připojení
  • dynamické ostrovy nejprve vykreslí zástupný prvek bezpečný pro cache a poté načtou skutečný fragment z prohlížeče návštěvníka

Režimy

Hydratované ostrovy

Hydratovaný ostrov použijte, když lze výstup serveru bezpečně ukládat do cache a blok potřebuje pouze signál o připojení na frontendu.

JSON
{
  "name": "acme/tabs",
  "blockstudio": {
    "island": "hydrate"
  }
}

Celý blok HTML je součástí počáteční odpovědi. Prostředí ostrova kvůli němu neodesílá požadavek REST. Na značce vyvolá blockstudio:island:hydrate, aby k ní mohl frontendový kód připojit chování.

Dynamické ostrovy

Dynamický ostrov použijte, když je třeba vykreslit skutečný výstup bloku v kontextu požadavku návštěvníka.

JSON
{
  "name": "acme/cart-count",
  "blockstudio": {
    "island": "dynamic"
  }
}

Počáteční odpověď obsahuje pouze zástupný prvek. Prohlížeč sloučí všechny připravené dynamické ostrovy do jednoho požadavku na:

Text
POST /wp-json/blockstudio/v1/island/render

Koncový bod vykresluje pouze registrované bloky Blockstudio, které jsou dynamické a mají blockstudio.island.mode nastavené na dynamic.

Konfigurace

Hodnota island může být zkrácený zápis nebo objekt.

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

true i "hydrate" znamenají hydrataci. "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"
      }
    }
  }
}
Vlastnost Typ Výchozí hodnota Popis
mode "hydrate" nebo "dynamic" "hydrate" Režim islandu.
tag string "div" Značka obalu markeru.
attributes string[] všechny atributy bloku Seznam povolených atributů odesílaný v požadavcích na dynamické fragmenty.
placeholder string automaticky zjištěno Relativní cesta k šabloně zástupného symbolu.
loading "eager" nebo "visible" "eager" Kdy má běhové prostředí načíst dynamický island.
event string nenastaveno Název události okna, která obnoví dynamický island.
context boolean false Podepsat a obnovit ID příspěvku a typ příspěvku dotazované stránky pro dynamické fragmenty.
cache boolean nebo object false Volitelná zásada ukládání fragmentů do mezipaměti.

Kontext stránky

Dynamické fragmenty se obvykle vykreslují nezávisle na obalu stránky. Pokud blok čte nastavení specifická pro stránku nebo související obsah, zapněte předávání identity stránky:

JSON
{
  "blockstudio": {
    "island": {
      "mode": "dynamic",
      "context": true,
      "cache": { "ttl": 60, "per": "global" }
    }
  }
}

Marker obsahuje postId a postType dotazované stránky v data-bs-island-context. Obě hodnoty jsou podepsány společně s názvem bloku a povolenými atributy pomocí tajného klíče obsluhujícího webu. Nelze je změnit ani přidat do požadavku bez zneplatnění podpisu. Běhové prostředí je odesílá spolu s existujícím dávkovým požadavkem na fragmenty, včetně obnovení viditelností a událostmi. Funguje to také s bs_render_block(), bs_block() a značkami bloků.

Při vykreslování fragmentu označují $block['postId'], $block['postType'], get_the_ID() a get_queried_object_id() tuto stránku. Po vykreslení se obnoví globální proměnné WordPress pro dotazy a příspěvky, a to i v případě výjimky při vykreslování. Jde o dotazovanou stránku, nikoli o položku uvnitř smyčky Query Loop. Neopakuje libovolné parametry URL ani neobnovuje původní URL požadavku. Pokud potřebujete kanonické URL stránky HTML, použijte get_permalink($block['postId']). Archivy a vykreslení bez dotazovaného příspěvku neposílají identitu stránky.

Koncový bod před kontrolou mezipaměti fragmentů ověří, zda stránka stále existuje, má podepsaný typ příspěvku a zda ji aktuální návštěvník může číst. Platný podpis neobchází ochranu soukromých příspěvků ani ochranu heslem, způsobilost islandu, seznamy povolených atributů ani vlastní kontroly oprávnění vašeho bloku. Je-li identita stránky k dispozici, je vždy součástí klíče mezipaměti fragmentů, takže stejný blok a atributy na různých stránkách nikdy nesdílejí fragment. Pokud výstup závisí také na návštěvníkovi, použijte per: "user" nebo mezipaměť fragmentů vypněte.

Pokud vynecháte context nebo nastavíte false, stávající markery a chování nezávislé na kontextu zůstanou beze změny. Do veřejného markeru nevkládejte důvěrná data.

Dynamické zástupné prvky

Dynamické ostrovy mají vykreslit zástupný prvek, který je bezpečné ukládat do sdílené cache celé stránky. Do větve zástupného prvku nevkládejte data specifická pro návštěvníka.

Blockstudio hledá zástupné prvky v tomto pořadí:

  1. výslovně zadaná cesta island.placeholder
  2. placeholder.php
  3. placeholder.blade.php
  4. placeholder.twig
  5. placeholder.html
  6. běžná šablona s příznaky pro zástupný prvek
PHP
<div class="cart-count-placeholder">
  Loading cart...
</div>

Pokud žádný soubor zástupného prvku neexistuje, použijte příznaky šablony v běžné šabloně:

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; ?>

V šablonách PHP, Twig a Blade jsou dostupné stejné hodnoty:

  • isIsland
  • isIslandPlaceholder
  • isIslandFragment
  • islandPhase

islandPhase je "normal", "hydrate", "placeholder" nebo "fragment".

Chování prostředí

Blockstudio vloží prostředí ostrovů pouze tehdy, když vykreslená stránka obsahuje značku ostrova. Stránky bez ostrovů nenačítají žádné další JavaScript ostrovů.

U dynamických ostrovů prostředí:

  1. shromáždí všechny připravené značky
  2. odstraní duplicitní dvojice shodného názvu bloku, atributů a podpisu
  3. odešle jeden sdružený požadavek REST
  4. nahradí každý zástupný prvek vráceným fragmentem
  5. vyvolá blockstudio:island:rendered
  6. vyvolá blockstudio:island:hydrate

Ostrovy loading: "eager" se vykreslí hned po spuštění prostředí. Ostrovy loading: "visible" čekají na IntersectionObserver. Pokud do výřezu současně vstoupí několik viditelných ostrovů, sloučí se do jednoho požadavku.

event obnoví ostrov při vyvolání pojmenované události okna:

JavaScript
window.dispatchEvent(new Event('cart:updated'));

Při chybě zůstane zástupný prvek na místě a vyvolá se blockstudio:island:error.

Koncový bod fragmentů

Koncový bod ostrovů je veřejný, ale nejde o obecné rozhraní pro vykreslování bloků API.

Každá značka obsahuje:

  • název bloku
  • atributy ze seznamu povolených
  • podpis vygenerovaný serverem

Koncový bod vykresluje pouze za těchto podmínek:

  • blok je registrovaný
  • blok je dynamický blok WordPress
  • blok je označený jako dynamický ostrov Blockstudio
  • příchozí atributy odpovídají schématu bloku i seznamu povolených atributů ostrova
  • podpis odpovídá normalizovanému názvu bloku a atributům

Podpisy se generují při vykreslování na obsluhovaném webu WordPress z tajných klíčů tohoto webu a dat ostrova. Neexportují se ani se nepřidávají do šablony.

Odpovědi koncového bodu jsou označeny jako nevhodné pro ukládání do cache. Pokud chcete ukládat fragmenty do cache, použijte island.cache.

Ukládání fragmentů do cache

Dynamické fragmenty se ve výchozím nastavení neukládají do cache.

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

true používá krátkodobou globální cache. Pro výslovné řízení použijte objektový zápis:

JSON
{
  "cache": {
    "ttl": 120,
    "per": "user"
  }
}

per: "global" sdílí jeden fragment mezipaměti pro stejný blok, atributy a kontext stránky s výslovným souhlasem. per: "user" mění klíč mezipaměti podle aktuálního ID uživatele WordPress.

Programové vykreslování

Ostrovy fungují všude, kde se vykreslují bloky Blockstudio:

PHP
bs_render_block([
  'name' => 'acme/cart-count',
  'data' => ['productId' => 42],
]);

echo bs_block([
  'name' => 'acme/cart-count',
  'data' => ['productId' => 42],
]);

Fungují také prostřednictvím značek bloků:

HTML
<bs:acme-cart-count product-id="42" />
<block name="acme/cart-count" productId="42" />

Počáteční výstup stále tvoří značka ostrova a zástupný prvek. Prostředí se vloží, pokud vykreslená odpověď tuto značku obsahuje.

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() ověřuje metadata bloků. Dynamické značky se vytvářejí pouze pro registrované dynamické bloky Blockstudio s hodnotou island.mode nastavenou na dynamic.

Hooky

Zjišťování a značení:

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 vykreslování:

PHP
blockstudio/islands/allowed
blockstudio/islands/max_per_request
blockstudio/islands/request_attributes
blockstudio/islands/fragment

blockstudio/islands/max_per_request mění maximální počet dynamických ostrovů přijímaných v jednom sdruženém požadavku na koncový bod. Výchozí hodnota je 50.

Konfigurace prostředí:

PHP
blockstudio/islands/endpoint_url
blockstudio/islands/loading

Podpisy:

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

Akce životního cyklu:

PHP
blockstudio/islands/registered
blockstudio/islands/rendered

Kdy ostrovy nepoužívat

Dynamický ostrov nepoužívejte pro obsah zásadní z hlediska SEO. Fragmenty dynamických ostrovů nejsou součástí počátečního HTML a nejsou určeny k indexování.

Použijte běžné vykreslování nebo hydratovaný ostrov, pokud je obsah bezpečné ukládat do cache a má být viditelný pro prohledávací roboty. Dynamický ostrov použijte pouze pro obsah, který může přijít až po načtení kostry stránky, například informace o účtu UI, stav košíku, personalizovaná doporučení nebo ovládací prvky přístupné jen s příslušným oprávněním.