Ga naar de inhoud

Islands

Met block islands kan een blok de normale Blockstudio-renderpipeline blijven gebruiken, terwijl aanvraaggebonden uitvoer buiten het initiële HTML-antwoord wordt gehouden.

Dit is handig wanneer een pagina intensief moet worden gecachet, maar een blok nog afhankelijk is van de huidige bezoeker, sessie, winkelwagen, machtigingen of een andere actuele aanvraagcontext.

Blockstudio-blokken zijn nog steeds dynamische WordPress-blokken. Islands maken er geen vooraf gecompileerde statische HTML van. In plaats daarvan verandert Blockstudio wat er bij de eerste aanvraag wordt gerenderd:

  • gehydrateerde islands renderen hun normale cacheveilige HTML en ontvangen een mount-event
  • dynamische islands renderen eerst een cacheveilige placeholder en halen daarna het echte fragment op vanuit de browser van de bezoeker

Modi

Gehydrateerde islands

Gebruik een gehydrateerde island wanneer de serveruitvoer veilig kan worden gecachet en het blok alleen een frontend-mountsignaal nodig heeft.

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

Het volledige blok-HTML is aanwezig in het initiële antwoord. De island-runtime doet er geen REST-aanvraag voor. De runtime verstuurt blockstudio:island:hydrate op de marker, zodat frontendcode gedrag kan toevoegen.

Dynamische islands

Gebruik een dynamische island wanneer de echte blokuitvoer in de aanvraagcontext van de bezoeker moet worden gerenderd.

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

Het initiële antwoord bevat alleen een placeholder. De browser bundelt alle gereedstaande dynamische islands in één aanvraag naar:

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

Het endpoint rendert alleen geregistreerde Blockstudio-blokken die dynamisch zijn en waarvoor blockstudio.island.mode is ingesteld op dynamic.

Configuratie

De waarde van island kan een verkorte notatie of een object zijn.

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

true en "hydrate" betekenen allebei gehydrateerd. "dynamic" betekent dynamisch.

JSON
{
  "blockstudio": {
    "island": {
      "mode": "dynamic",
      "tag": "section",
      "attributes": ["productId", "variant"],
      "placeholder": "cart-placeholder.php",
      "loading": "visible",
      "event": "cart:updated",
      "cache": {
        "ttl": 60,
        "per": "user"
      }
    }
  }
}
Eigenschap Type Standaard Beschrijving
mode "hydrate" of "dynamic" "hydrate" Island-modus.
tag string "div" Wrapper-tag voor markering.
attributes string[] alle blokattributen Lijst met toegestane attributen die naar dynamische fragmentverzoeken wordt verzonden.
placeholder string automatisch gedetecteerd Relatief pad naar de tijdelijke plaatsaanduidingssjabloon.
loading "eager" of "visible" "eager" Wanneer de runtime een dynamisch island ophaalt.
event string niet ingesteld Naam van het window-event dat een dynamisch island vernieuwt.
context boolean false Onderteken en herstel het bericht-ID en berichttype van de opgevraagde pagina voor dynamische fragmenten.
cache boolean of object false Optioneel cachebeleid voor fragmenten.

Paginacontext

Dynamische fragmenten worden doorgaans onafhankelijk van de paginaschil gerenderd. Schakel de pagina-identiteit in als uw blok pagina-instellingen of gerelateerde inhoud uitleest:

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

De markering bevat de postId en postType van de opgevraagde pagina in data-bs-island-context. Beide waarden worden ondertekend met de bloknaam en de toegestane attributen, met behulp van het geheim van de serverende site. Ze kunnen niet worden gewijzigd of aan een verzoek worden toegevoegd zonder de handtekening ongeldig te maken. De runtime verzendt ze met het bestaande gebundelde fragmentverzoek, ook bij vernieuwen door zichtbaarheid en door events. Dit werkt ook met bs_render_block(), bs_block() en bloktags.

Tijdens het renderen van fragmenten verwijzen $block['postId'], $block['postType'], get_the_ID() en get_queried_object_id() naar die pagina. Daarna worden de query- en berichtglobale variabelen van WordPress hersteld, ook na een renderfout. Dit is de opgevraagde pagina, geen item binnen een Query Loop. Willekeurige URL-parameters worden niet opnieuw afgespeeld en de oorspronkelijke request-URL wordt niet hersteld. Gebruik get_permalink($block['postId']) als u de canonieke URL van de pagina HTML nodig hebt. Archieven en renders zonder opgevraagd bericht verzenden geen pagina-identiteit.

Het endpoint controleert of de pagina nog bestaat, het ondertekende berichttype heeft en leesbaar is voor de huidige bezoeker voordat de fragmentcache wordt geraadpleegd. Een geldige handtekening omzeilt geen bescherming van privéberichten of met een wachtwoord beveiligde berichten, geschiktheid voor islands, lijsten met toegestane attributen of uw eigen machtigingscontroles voor het blok. Als pagina-identiteit aanwezig is, maakt deze altijd deel uit van de fragmentsleutel. Hetzelfde blok met dezelfde attributen deelt dus nooit een fragment tussen verschillende pagina’s. Gebruik per: "user" of schakel de fragmentcache uit als de uitvoer ook afhangt van de bezoeker.

Als context is weggelaten of false is, blijven bestaande markeringen en gedrag zonder context ongewijzigd. Plaats geen vertrouwelijke gegevens in de openbare markering.

Dynamische placeholders

Dynamische islands moeten een placeholder renderen die veilig is in een gedeelde cache voor volledige pagina’s. Neem geen bezoekersspecifieke gegevens op in de placeholdervertakking.

Blockstudio zoekt in deze volgorde naar placeholders:

  1. het expliciete pad island.placeholder
  2. placeholder.php
  3. placeholder.blade.php
  4. placeholder.twig
  5. placeholder.html
  6. de normale template met placeholderflags
PHP
<div class="cart-count-placeholder">
  Loading cart...
</div>

Gebruik de templateflags in je normale template als er geen placeholderbestand bestaat:

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

Dezelfde waarden zijn beschikbaar in templates voor PHP, Twig en Blade:

  • isIsland
  • isIslandPlaceholder
  • isIslandFragment
  • islandPhase

islandPhase is "normal", "hydrate", "placeholder" of "fragment".

Runtimegedrag

Blockstudio voegt de island-runtime alleen toe wanneer de gerenderde pagina een island-marker bevat. Pagina’s zonder islands bevatten geen extra island-JavaScript.

Voor dynamische islands doet de runtime het volgende:

  1. verzamelt alle gereedstaande markers
  2. verwijdert dubbele paren met dezelfde bloknaam, attributen en handtekening
  3. verstuurt één gebundelde REST-aanvraag
  4. vervangt elke placeholder door het geretourneerde fragment
  5. verstuurt blockstudio:island:rendered
  6. verstuurt blockstudio:island:hydrate

loading: "eager"-islands worden gerenderd zodra de runtime start. loading: "visible"-islands wachten op IntersectionObserver. Als meerdere zichtbare islands tegelijk in de viewport komen, worden ze in één aanvraag gebundeld.

event vernieuwt een island wanneer de genoemde window-gebeurtenis plaatsvindt:

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

Bij fouten blijft de placeholder staan en wordt blockstudio:island:error verstuurd.

Fragmentendpoint

Het island-endpoint is openbaar, maar het is geen algemene blokrender-API.

Elke marker bevat:

  • de bloknaam
  • de attributen op de toelatingslijst
  • een door de server gegenereerde handtekening

Het endpoint rendert alleen wanneer:

  • het blok is geregistreerd
  • het blok een dynamisch WordPress-blok is
  • het blok is gemarkeerd als een dynamische Blockstudio-island
  • de binnenkomende attributen voldoen aan het blokschema en de toelatingslijst van de island
  • de handtekening overeenkomt met de genormaliseerde bloknaam en attributen

Handtekeningen worden tijdens het renderen gegenereerd op de serverende WordPress-site, op basis van de salts van die site en de island-payload. Ze worden niet geëxporteerd of in een thema ingebakken.

Antwoorden van het endpoint zijn gemarkeerd als niet-cachebaar. Gebruik island.cache als je fragmenten wilt cachen.

Fragmentcaching

Dynamische fragmenten worden standaard niet gecachet.

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

true gebruikt een korte globale cache. Gebruik de objectvorm voor expliciete controle:

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

per: "global" deelt één gecachet fragment voor hetzelfde blok, dezelfde attributen en dezelfde opt-in paginacontext. per: "user" varieert de cache op basis van de huidige gebruikers-ID van WordPress.

Programmatisch renderen

Islands werken overal waar Blockstudio-blokken worden gerenderd:

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

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

Ze werken ook via bloktags:

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

De initiële uitvoer bestaat nog steeds uit de island-marker en placeholder; de runtime wordt toegevoegd wanneer het gerenderde antwoord die marker bevat.

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() valideert blokmetadata. Dynamische markers worden alleen opgebouwd voor geregistreerde dynamische Blockstudio-blokken waarvoor island.mode is ingesteld op dynamic.

Hooks

Detectie en markup:

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

Endpoint en rendering:

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

blockstudio/islands/max_per_request wijzigt het maximumaantal dynamische islands dat door één gebundelde endpointaanvraag wordt geaccepteerd. De standaardwaarde is 50.

Runtimeconfiguratie:

PHP
blockstudio/islands/endpoint_url
blockstudio/islands/loading

Handtekeningen:

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

Lifecycle-acties:

PHP
blockstudio/islands/registered
blockstudio/islands/rendered

Wanneer je islands beter niet gebruikt

Gebruik geen dynamische island voor inhoud die cruciaal is voor SEO. Dynamische island-fragmenten zijn niet aanwezig in de initiële HTML en zijn niet bedoeld om te worden geïndexeerd.

Gebruik normale rendering of een gehydrateerde island wanneer de inhoud cacheveilig is en zichtbaar moet zijn voor crawlers. Gebruik een dynamische island alleen voor inhoud die na de paginaschil kan binnenkomen, zoals account-UI, winkelwagenstatus, gepersonaliseerde aanbevelingen of bedieningselementen waarvoor machtigingen vereist zijn.