Hoppa till innehåll

Öar

Blocköar låter ett block behålla den vanliga renderingspipen för Blockstudio, samtidigt som utdata som är specifika för en begäran flyttas ut från det första HTML-svaret.

Det här är användbart när en sida bör cachas aggressivt, men ett block fortfarande är beroende av den aktuella besökaren, sessionen, kundvagnen, behörigheter eller annan aktuell begärandekontext.

Blockstudio-block är fortfarande dynamiska WordPress-block. Öar omvandlar dem inte till förkompilerade statiska HTML. I stället ändrar Blockstudio vad som renderas vid den första begäran:

  • hydrerade öar renderar sin vanliga cache-säkra HTML och tar emot en monteringshändelse
  • dynamiska öar renderar först en cache-säker platshållare och hämtar sedan det verkliga fragmentet från besökarens webbläsare

Lägen

Hydrerade öar

Använd en hydrerad ö när serverutdata är säker att cacha och blocket bara behöver en monteringssignal i frontend.

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

Hela blockets HTML finns i det första svaret. Öarnas körmiljö gör ingen REST-begäran efter det. Den skickar blockstudio:island:hydrate på markören så att frontendkod kan koppla på beteenden.

Dynamiska öar

Använd en dynamisk ö när det verkliga blockinnehållet måste renderas i besökarens begärandekontext.

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

Det första svaret innehåller bara en platshållare. Webbläsaren samlar alla dynamiska öar som är klara i en enda begäran till:

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

Slutpunkten renderar bara registrerade Blockstudio-block som är dynamiska och har blockstudio.island.mode inställt på dynamic.

Konfiguration

Värdet för island kan vara en kortform eller ett objekt.

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

true och "hydrate" betyder båda hydrerad. "dynamic" betyder dynamisk.

JSON
{
  "blockstudio": {
    "island": {
      "mode": "dynamic",
      "tag": "section",
      "attributes": ["productId", "variant"],
      "placeholder": "cart-placeholder.php",
      "loading": "visible",
      "event": "cart:updated",
      "cache": {
        "ttl": 60,
        "per": "user"
      }
    }
  }
}
Egenskap Typ Standard Beskrivning
mode "hydrate" eller "dynamic" "hydrate" Ö-läge.
tag string "div" Omslagstagg för markör.
attributes string[] alla blockattribut Tillåtelselista för attribut som skickas med dynamiska fragmentförfrågningar.
placeholder string identifieras automatiskt Relativ sökväg till platshållarmallen.
loading "eager" eller "visible" "eager" När körmiljön ska hämta en dynamisk ö.
event string ej angivet Namn på fönsterhändelse som uppdaterar en dynamisk ö.
context boolean false Signera och återställ den efterfrågade sidans inläggs-ID och inläggstyp för dynamiska fragment.
cache boolean eller object false Valfri cachepolicy för fragment.

Sidkontext

Dynamiska fragment renderas normalt oberoende av sidans skal. Aktivera sidans identitet om ditt block läser sidspecifika inställningar eller relaterat innehåll:

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

Markören innehåller den efterfrågade sidans postId och postType i data-bs-island-context. Båda värdena signeras med blocknamnet och tillåtna attribut med hjälp av den visande webbplatsens hemlighet. De kan inte ändras eller läggas till i en förfrågan utan att signaturen blir ogiltig. Körmiljön skickar dem med den befintliga batchade fragmentförfrågan, även vid uppdateringar som utlöses av synlighet eller händelser. Detta fungerar också med bs_render_block(), bs_block() och blocktaggar.

Under fragmentrendering hänvisar $block['postId'], $block['postType'], get_the_ID() och get_queried_object_id() till den sidan. WordPress-frågan och globala inläggsvärden återställs efteråt, även om ett renderingsfel inträffar. Detta är den efterfrågade sidan, inte ett objekt inuti en Query Loop. Godtyckliga parametrar i URL spelas inte upp igen och den ursprungliga förfrågans URL återställs inte. Använd get_permalink($block['postId']) när du behöver den HTML sidans kanoniska URL. Arkiv och renderingar utan ett efterfrågat inlägg skickar ingen sididentitet.

Slutpunkten kontrollerar att sidan fortfarande finns, har den signerade inläggstypen och kan läsas av den aktuella besökaren innan fragmentcachen används. En giltig signatur kringgår inte skydd för privata inlägg eller lösenordsskydd, ö-behörighet, tillåtelselistor för attribut eller blockets egna behörighetskontroller. Sididentiteten ingår alltid i fragmentcachenyckeln när den finns, så samma block och attribut på olika sidor delar aldrig ett fragment. Använd per: "user" eller ingen fragmentcache när utdata också beror på besökaren.

Om context utelämnas eller är false förblir befintliga markörer och det kontextfria beteendet oförändrade. Lägg inte konfidentiella data i den offentliga markören.

Dynamiska platshållare

Dynamiska öar bör rendera en platshållare som är säker i en delad helsidescache. Ta inte med besökarspecifika data i platshållargrenen.

Blockstudio letar efter platshållare i följande ordning:

  1. den uttryckliga sökvägen island.placeholder
  2. placeholder.php
  3. placeholder.blade.php
  4. placeholder.twig
  5. placeholder.html
  6. den vanliga mallen med platshållarflaggor
PHP
<div class="cart-count-placeholder">
  Loading cart...
</div>

Om ingen platshållarfil finns använder du mallflaggorna i den vanliga mallen:

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

Samma värden är tillgängliga i mallarna PHP, Twig och Blade:

  • isIsland
  • isIslandPlaceholder
  • isIslandFragment
  • islandPhase

islandPhase är "normal", "hydrate", "placeholder" eller "fragment".

Körmiljöns beteende

Blockstudio lägger till körmiljön för öar endast när den renderade sidan innehåller en ömarkör. Sidor utan öar skickar ingen extra ö-JavaScript.

För dynamiska öar gör körmiljön följande:

  1. samlar alla markörer som är klara
  2. tar bort dubbletter av par med identiska blocknamn, attribut och signaturer
  3. skickar en enda samlad REST-begäran
  4. byter ut varje platshållare mot det returnerade fragmentet
  5. skickar blockstudio:island:rendered
  6. skickar blockstudio:island:hydrate

loading: "eager"-öar renderas så snart körmiljön startar. loading: "visible"-öar väntar på IntersectionObserver. Om flera synliga öar kommer in i visningsområdet samtidigt samlas de i en enda begäran.

event uppdaterar en ö när den namngivna fönsterhändelsen utlöses:

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

Vid fel ligger platshållaren kvar och blockstudio:island:error skickas.

Fragmentändpunkt

Öns ändpunkt är offentlig, men den är inte ett allmänt gränssnitt för blockrendering API.

Varje markör innehåller:

  • blocknamnet
  • attributen i tillåtelselistan
  • en serverskapad signatur

Ändpunkten renderar bara när:

  • blocket är registrerat
  • blocket är ett dynamiskt WordPress-block
  • blocket är markerat som en dynamisk Blockstudio-ö
  • de inkommande attributen följer blockschemat och öns tillåtelselista
  • signaturen matchar det normaliserade blocknamnet och attributen

Signaturer skapas vid rendering på den betjänande WordPress-webbplatsen utifrån webbplatsens salter och öns nyttolast. De exporteras inte och bäddas inte in i ett tema.

Ändpunktssvar markeras som ej cachebara. Använd island.cache om du vill cacha fragment.

Fragmentcachning

Dynamiska fragment cachas inte som standard.

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

true använder en kortlivad global cache. Använd objektformen för uttrycklig kontroll:

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

per: "global" delar ett cachelagrat fragment för samma block, attribut och kontext för sidor med opt-in. per: "user" varierar cachen efter aktuellt WordPress användar-ID.

Programmatisk rendering

Öar fungerar där Blockstudio-block renderas:

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

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

De fungerar även via blocktaggar:

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

Den första utdata är fortfarande ömarkören och platshållaren, och körmiljön läggs till när det renderade svaret innehåller den markören.

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() validerar blockmetadata. Dynamiska markörer skapas bara för registrerade dynamiska Blockstudio-block där island.mode är inställt på dynamic.

Hooks

Identifiering och markup:

PHP
blockstudio/islands/is_island
blockstudio/islands/mode
blockstudio/islands/attributes
blockstudio/islands/marker_tag
blockstudio/islands/marker_attributes
blockstudio/islands/placeholder

Ändpunkt och rendering:

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

blockstudio/islands/max_per_request ändrar det högsta antalet dynamiska öar som godtas i en enda samlad ändpunktsbegäran. Standardvärdet är 50.

Körmiljökonfiguration:

PHP
blockstudio/islands/endpoint_url
blockstudio/islands/loading

Signaturer:

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

Livscykelåtgärder:

PHP
blockstudio/islands/registered
blockstudio/islands/rendered

När du inte ska använda öar

Använd inte en dynamisk ö för innehåll som är kritiskt för SEO. Dynamiska öfragment finns inte i det första HTML och är inte avsedda att indexeras.

Använd normal rendering eller en hydrerad ö när innehållet är cache-säkert och bör vara synligt för sökrobotar. Använd en dynamisk ö endast för innehåll som kan komma efter sidskalet, till exempel kontots UI, kundvagnsstatus, personliga rekommendationer eller behörighetsstyrda kontroller.