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.
{
"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.
{
"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:
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.
{
"blockstudio": {
"island": true
}
}
true en "hydrate" betekenen allebei gehydrateerd. "dynamic" betekent dynamisch.
{
"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:
{
"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:
- het expliciete pad
island.placeholder placeholder.phpplaceholder.blade.phpplaceholder.twigplaceholder.html- de normale template met placeholderflags
<div class="cart-count-placeholder">
Loading cart...
</div>
Gebruik de templateflags in je normale template als er geen placeholderbestand bestaat:
<?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:
isIslandisIslandPlaceholderisIslandFragmentislandPhase
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:
- verzamelt alle gereedstaande markers
- verwijdert dubbele paren met dezelfde bloknaam, attributen en handtekening
- verstuurt één gebundelde REST-aanvraag
- vervangt elke placeholder door het geretourneerde fragment
- verstuurt
blockstudio:island:rendered - 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:
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.
{
"blockstudio": {
"island": {
"mode": "dynamic",
"cache": true
}
}
}
true gebruikt een korte globale cache. Gebruik de objectvorm voor expliciete controle:
{
"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:
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:
<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
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:
blockstudio/islands/is_island
blockstudio/islands/mode
blockstudio/islands/attributes
blockstudio/islands/marker_tag
blockstudio/islands/marker_attributes
blockstudio/islands/placeholder
Endpoint en rendering:
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:
blockstudio/islands/endpoint_url
blockstudio/islands/loading
Handtekeningen:
blockstudio/islands/signature_payload
blockstudio/islands/signature
blockstudio/islands/verify_signature
Lifecycle-acties:
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.