Fragmentos personalizados en páginas en caché
Una página servida desde una caché estática es igual para todo el mundo. Esa es la finalidad de almacenarla en caché, pero también el problema: el encabezado debería saludar con «Hola, Ada» a un cliente que haya iniciado sesión, y el icono del carrito debería mostrar tres artículos. Si la plantilla muestra contenido según el usuario actual, la caché guarda el saludo de un visitante para todo el mundo o tiene que excluir la página por completo.
Las islas dinámicas de Blockstudio separan esas dos cuestiones. La HTML almacenada en caché contiene un marcador de posición seguro para la caché. Tras cargar la página, un pequeño entorno de ejecución solicita el fragmento personalizado a WordPress en la propia solicitud del visitante y lo inserta. La página sigue siendo apta para la caché y solo el fragmento se actualiza dinámicamente.
Esta guía crea dos islas, un saludo y el número de artículos en el carrito, y explica qué contiene la página en caché, cómo es la solicitud del fragmento y cómo el endpoint identifica al visitante. Se complementa con Servir WordPress de forma estáticaHTML.
Cómo funciona una isla dinámica
- El bloque renderiza su marcador de posición dentro de un elemento marcador. Este incluye el nombre del bloque, los atributos de la lista de permitidos y una firma generada por el servidor.
- Como la página renderizada contiene un marcador, Blockstudio inserta el entorno de ejecución de las islas. Las páginas sin islas no incluyen ningún JavaScript de islas.
- El entorno de ejecución recopila los marcadores listos y envía una sola
POSTpor lotes a/wp-json/blockstudio/v1/island/render. - El endpoint verifica cada firma, renderiza el bloque en el contexto de la solicitud del visitante y devuelve los fragmentos.
- El entorno de ejecución sustituye cada marcador de posición y envía eventos.
En el editor de bloques, el bloque se renderiza con normalidad, sin marcador de posición.
Paso 1: El bloque de saludo
Cree el bloque con tres archivos:
blocks/
└── greeting/
├── block.json
├── placeholder.php
└── index.php
{
"apiVersion": 3,
"name": "acme/greeting",
"title": "Greeting",
"category": "widgets",
"icon": "admin-users",
"description": "Account link that greets signed-in visitors.",
"blockstudio": {
"island": {
"mode": "dynamic",
"tag": "span",
"attributes": ["guestLabel"],
"cache": {
"ttl": 300,
"per": "user"
}
},
"attributes": [
{ "id": "guestLabel", "type": "text", "label": "Guest label", "default": "Sign in" }
]
}
}
mode: "dynamic" convierte el bloque en una isla que solicita un fragmento.
tag define el elemento marcador para que la isla pueda colocarse en línea en una barra de navegación. attributes es la lista de atributos de bloque permitidos que se envían con la solicitud del fragmento; todo lo que no se incluya no se envía ni se firma. cache se explica más adelante.
La página en caché contiene el marcador de posición. Debe ser seguro para todos los visitantes, así que no incluye datos de usuario. Un enlace «Cuenta» sirve para todo el mundo:
<a href="<?php echo esc_url( home_url( '/account/' ) ); ?>">Account</a>
La plantilla principal renderiza el fragmento real:
<?php
$user = wp_get_current_user();
?>
<?php if ( $user->exists() ) : ?>
<a href="<?php echo esc_url( home_url( '/account/' ) ); ?>">
<?php echo esc_html( sprintf( 'Hi, %s', $user->display_name ) ); ?>
</a>
<?php else : ?>
<a href="<?php echo esc_url( wp_login_url() ); ?>">
<?php echo esc_html( $a['guestLabel'] ); ?>
</a>
<?php endif; ?>
En este caso, se puede mostrar contenido según el usuario actual: esta plantilla solo se ejecuta para la solicitud del fragmento, nunca para la página en caché.
Colóquelo donde se renderice el encabezado:
<?php echo bs_block( array( 'name' => 'acme/greeting' ) ); ?>
También funcionan las etiquetas de bloque: <bs:acme-greeting /> o
<block name="acme/greeting" />.
Paso 2: Contenido de la página en caché
Al renderizarse en el servidor, el bloque solo genera el marcador y el marcador de posición:
<span data-bs-island="acme/greeting" data-bs-island-mode="dynamic" data-bs-island-phase="placeholder" data-bs-island-props="{"guestLabel":"Sign in"}" data-bs-island-signature="a7311ba9f6abf3c993edfdd7d49d2fa23bfa068f715b96637c35ef30de8b2043" data-bs-island-loading="eager"><!--blockstudio/acme/greeting--><a href="https://example.com/account/">Account</a>
</span>
Renderícelo una vez como visitante anónimo y otra como usuario que haya iniciado sesión; las dos cadenas serán idénticas byte por byte. Esa es exactamente la propiedad que necesita un prerrenderizado estático con serveLoggedIn habilitado: quienquiera que inicie el renderizado, el documento almacenado será el mismo y no contendrá datos personales.
Paso 3: Solicitud del fragmento
El entorno de ejecución envía todas las islas listas en una sola solicitud:
{
"islands": [
{
"clientId": "a1",
"name": "acme/greeting",
"attributes": {
"guestLabel": "Sign in"
},
"signature": "a7311ba9f6abf3c993edfdd7d49d2fa23bfa068f715b96637c35ef30de8b2043"
}
]
}
La respuesta se identifica mediante clientId. Para un visitante que haya iniciado sesión:
{
"a1": "<!--blockstudio/acme/greeting--> <a href=\"https://example.com/account/\">\n Hi, Ada </a>\n"
}
Si una entrada no supera la verificación, se devuelve un código de error en vez de HTML, sin que falle el resto del lote. En este caso, la segunda entrada cambió guestLabel sin una firma correspondiente, y la tercera indicó un bloque que no es una isla dinámica:
{
"a1": "<!--blockstudio/acme/greeting--> <a href=\"https://example.com/wp-login.php\">\n Sign in </a>\n",
"a2": {
"error": "blockstudio_island_invalid_signature"
},
"a3": {
"error": "blockstudio_island_not_allowed"
}
}
Todas las respuestas incluyen
Cache-Control: no-store, no-cache, must-revalidate, max-age=0,
Pragma: no-cache y X-Robots-Tag: noindex. El endpoint está en
/wp-json, que el prerrenderizado estático siempre omite, así que ni la caché del servidor de origen ni una CDN que respete los encabezados del servidor almacenarán un fragmento.
Quién es el visitante
El entorno de ejecución envía la solicitud con credentials: 'same-origin', por lo que el navegador incluye la cookie de inicio de sesión WordPress. Normalmente, WordPress REST API ignora la autenticación mediante cookies si no hay un nonce, y un nonce no puede incluirse en una página en caché. El endpoint de islas se encarga de ello: en las solicitudes de navegador del mismo origen, valida la cookie logged_in y restaura ese usuario antes de renderizar.
El mismo origen se determina comparando el encabezado Sec-Fetch-Site y, si está presente, el encabezado Origin con home_url(). Una solicitud de otro origen que incluya la cookie se renderiza como anónima, así que desde otro sitio nunca se muestra el fragmento personalizado de un visitante. En la práctica:
| Solicitud | Se renderiza como |
|---|---|
| Solicitud fetch del mismo origen con una cookie de inicio de sesión válida | Usuario que ha iniciado sesión |
| Solicitud de otro origen con la misma cookie | Anónimo |
| Sin cookie | Anónimo |
¿Qué página es esta?
Añada "context": true a blockstudio.island cuando el fragmento necesite la identidad de su página. Entonces, el marcador firma el ID de entrada y el tipo de entrada de la página consultada junto con los atributos. En el fragmento, $block['postId'], $block['postType'], get_the_ID() y get_queried_object_id() hacen referencia a esa página. Dentro de un bucle de consultas, esto sigue refiriéndose a la página consultada externa, no al elemento del bucle.
El contexto de página es opcional y también forma parte de la clave de la caché de fragmentos. El endpoint vuelve a comprobar el acceso, incluso en los fragmentos almacenados en caché, por lo que un marcador firmado no expone una página que desde entonces se haya vuelto privada o protegida con contraseña. Consulta Contexto de página para conocer los detalles de configuración y seguridad. No se vuelven a reproducir URL arbitrarios ni parámetros de consulta.
Paso 4: Un contador de artículos del carrito que se actualiza solo
La segunda isla muestra el otro estilo de marcador de posición y dos opciones del entorno de ejecución. En lugar de un archivo de marcador de posición independiente, la plantilla comprueba $isIslandPlaceholder:
{
"apiVersion": 3,
"name": "acme/cart-count",
"title": "Cart Count",
"category": "widgets",
"icon": "cart",
"description": "Number of items in the visitor's cart.",
"blockstudio": {
"island": {
"mode": "dynamic",
"loading": "visible",
"event": "acme:cart-updated"
},
"attributes": []
}
}
<?php
$count = (int) apply_filters( 'acme/cart_count', 0 );
?>
<?php if ( $isIslandPlaceholder ) : ?>
<a href="/cart/" class="cart-count">Cart</a>
<?php else : ?>
<a href="/cart/" class="cart-count">
Cart <span class="cart-count__badge"><?php echo esc_html( (string) $count ); ?></span>
</a>
<?php endif; ?>
Las mismas opciones están disponibles en todos los lenguajes de plantilla: isIsland, isIslandPlaceholder, isIslandFragment y islandPhase ("normal", "hydrate", "placeholder" o "fragment"). En este caso, el contador procede de un filtro acme/cart_count que su código de comercio rellena; cuando devuelve 3, el endpoint responde:
{"c1":"<!--blockstudio/acme/cart-count--> <a href=\"/cart/\" class=\"cart-count\">\n Cart <span class=\"cart-count__badge\">3</span>\n </a>\n"}
loading: "visible" aplaza la solicitud hasta que el marcador entra en el área visible, mediante IntersectionObserver. Las islas visibles que aparecen a la vez siguen agrupándose en una sola solicitud. event indica un evento de ventana que vuelve a obtener la isla, así que tras añadir un artículo al carrito, su script solo tiene que anunciarlo:
window.dispatchEvent(new Event('acme:cart-updated'));
Reacción al código del frontend
Los eventos se propagan desde el marcador, así que un solo listener en document cubre todas las islas. event.detail.name contiene el nombre del bloque:
document.addEventListener('blockstudio:island:rendered', (event) => {
if (event.detail.name !== 'acme/cart-count') return;
event.target.querySelector('.cart-count__badge')?.classList.add('is-fresh');
});
document.addEventListener('blockstudio:island:error', (event) => {
console.warn('Island failed', event.detail.name, event.detail.error);
});
Tras el intercambio, el entorno de ejecución envía blockstudio:island:rendered y luego blockstudio:island:hydrate. Si falla, el marcador de posición permanece y se dispara blockstudio:island:error. Las islas hidratadas ("island": "hydrate") omiten por completo la solicitud: su HTML completo ya está en la página y solo reciben el evento hydrate, lo que resulta adecuado para bloques interactivos compatibles con la caché, como las pestañas.
Caché de fragmentos
De forma predeterminada, los fragmentos se renderizan en cada solicitud. El saludo anterior activa una caché de corta duración:
{
"cache": {
"ttl": 300,
"per": "user"
}
}
per: "user" varía el fragmento almacenado en caché según el ID de usuario de WordPress, y las solicitudes anónimas nunca se almacenan en ella, por lo que dos visitantes anónimos no pueden compartir una entrada destinada a un usuario. per: "global" comparte un fragmento para el mismo bloque y los mismos atributos, lo que conviene para contenido dinámico pero no personal, como el nivel de existencias. ttl tiene una duración predeterminada de 60 segundos, y cache: true es una caché global de 60 segundos.
El modelo de seguridad
El endpoint es público, pero no es un renderizador de bloques de uso general. Solo renderiza una entrada si se cumplen todas estas condiciones:
- el bloque está registrado, es dinámico y tiene
island.modeestablecido endynamic - la firma coincide con el nombre del bloque y los atributos que superan el filtro: solo las claves presentes tanto en el esquema del bloque como en la lista de permitidos de la isla
La firma es un HMAC-SHA256 calculado sobre el nombre normalizado del bloque y sus atributos, con la sal auth del sitio que lo sirve como clave. Las firmas se crean al renderizar en ese sitio y nunca se incluyen en un tema. De esto se derivan dos consecuencias. Un documento renderizado en un entorno de pruebas lleva firmas de ese entorno, así que renderice los documentos en el sitio que los sirve. Y cambiar las sales WordPress invalida todas las firmas de los documentos almacenados, por lo que debe purgar la representación previa estática después de cambiar una sal.
Una solicitud admite hasta 50 islas; si hay más, devuelve HTTP 413. Cambie el límite con blockstudio/islands/max_per_request. Hay hooks para firmas (blockstudio/islands/signature_payload, blockstudio/islands/signature, blockstudio/islands/verify_signature) para los alojamientos que necesitan un esquema distinto.
Cuándo no usar una isla
Los fragmentos no están en el HTML inicial, así que los rastreadores no los ven. Mantenga el contenido relevante para SEO en el renderizado normal. Use islas dinámicas para lo que pueda llegar después de la estructura de la página: enlaces de cuenta, estado del carrito, recomendaciones y controles restringidos por permisos. Si toda la página es personal, como un panel de cuenta, incluya su ruta en dynamicPaths y renderícela en tiempo real.
Pasos siguientes
- Referencia de islas: todas las opciones, orden de búsqueda de marcadores de posición, PHP API y hooks.
- Servir WordPress como HTML estático: la caché para la que se diseñaron estas islas.
- Referencia de representación previa estática:
serveLoggedIn, rutas dinámicas y servicio anticipado. - Componentes interactivos: comportamiento del cliente para bloques que necesitan algo más que un evento de montaje.