Aller au contenu

Fragments personnalisés sur les pages mises en cache

Une page servie depuis un cache statique est identique pour tout le monde. C’est le but de la mise en cache, mais aussi le problème : l’en-tête doit afficher « Bonjour, Ada » pour un client connecté, et l’icône du panier doit indiquer trois articles. Si le modèle varie selon l’utilisateur actuel, le cache stocke le message de bienvenue d’un visiteur pour tout le monde, ou doit ignorer entièrement la page.

Les îlots dynamiques de Blockstudio séparent ces deux besoins. Le HTML mis en cache contient un espace réservé compatible avec la mise en cache. Une fois la page chargée, un petit environnement d’exécution demande à WordPress le fragment personnalisé dans la requête du visiteur, puis le remplace. La page reste compatible avec la mise en cache, et seul le fragment est dynamique.

Ce guide crée deux îlots, un message de bienvenue et un compteur de panier, puis explique le contenu de la page mise en cache, la requête de fragment et la manière dont le point de terminaison identifie le visiteur. Il complète Servir WordPress en tant que site statiqueHTML.

Fonctionnement d’un îlot dynamique

  1. Le bloc affiche son espace réservé dans un élément marqueur. Ce marqueur contient le nom du bloc, les attributs autorisés et une signature générée par le serveur.
  2. Comme la page rendue contient un marqueur, Blockstudio injecte l’environnement d’exécution des îlots. Les pages sans îlots ne chargent aucun JavaScript d’îlot.
  3. L’environnement d’exécution collecte les marqueurs prêts et envoie une seule requête POST groupée à /wp-json/blockstudio/v1/island/render.
  4. Le point de terminaison vérifie chaque signature, affiche le bloc dans le contexte de la requête du visiteur et renvoie les fragments.
  5. L’environnement d’exécution remplace chaque espace réservé et distribue des événements.

Dans l’éditeur de blocs, le bloc s’affiche normalement, sans espace réservé.

Étape 1 : le bloc de bienvenue

Créez le bloc avec trois fichiers :

Code
blocks/
└── greeting/
    ├── block.json
    ├── placeholder.php
    └── index.php
JSON
{
  "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" transforme le bloc en îlot qui effectue une requête de fragment. tag définit l’élément marqueur, ce qui permet à l’îlot de s’insérer dans une barre de navigation. attributes est la liste autorisée des attributs du bloc transmis avec la requête de fragment ; tout attribut non répertorié n’est ni envoyé ni signé. cache est expliqué plus loin.

La page mise en cache contient l’espace réservé. Il doit pouvoir être affiché à tous les visiteurs et ne contient donc aucune donnée utilisateur. Un lien « Compte » convient à tout le monde :

PHP
<a href="<?php echo esc_url( home_url( '/account/' ) ); ?>">Account</a>

Le modèle principal affiche le fragment réel :

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

Il est tout à fait possible de vérifier l’utilisateur actuel ici : ce modèle s’exécute uniquement pour la requête de fragment, jamais pour la page mise en cache.

Insérez-le à l’endroit où s’affiche l’en-tête :

PHP
<?php echo bs_block( array( 'name' => 'acme/greeting' ) ); ?>

Les balises de bloc fonctionnent aussi : <bs:acme-greeting /> ou <block name="acme/greeting" />.

Étape 2 : contenu de la page mise en cache

Rendu sur le serveur, le bloc ne produit que le marqueur et l’espace réservé :

HTML
<span data-bs-island="acme/greeting" data-bs-island-mode="dynamic" data-bs-island-phase="placeholder" data-bs-island-props="{&quot;guestLabel&quot;:&quot;Sign in&quot;}" data-bs-island-signature="a7311ba9f6abf3c993edfdd7d49d2fa23bfa068f715b96637c35ef30de8b2043" data-bs-island-loading="eager"><!--blockstudio/acme/greeting--><a href="https://example.com/account/">Account</a>
</span>

Effectuez le rendu une fois en tant que visiteur anonyme et une fois en tant qu’utilisateur connecté : les deux chaînes sont identiques octet pour octet. C’est précisément ce qu’exige un prérendu statique avec serveLoggedIn activé : quel que soit l’auteur du rendu, le document stocké reste identique, et aucune donnée personnelle ne peut s’y retrouver.

Étape 3 : la requête de fragment

L’environnement d’exécution envoie tous les îlots prêts dans une seule requête :

JSON
{
    "islands": [
        {
            "clientId": "a1",
            "name": "acme/greeting",
            "attributes": {
                "guestLabel": "Sign in"
            },
            "signature": "a7311ba9f6abf3c993edfdd7d49d2fa23bfa068f715b96637c35ef30de8b2043"
        }
    ]
}

La réponse est indexée par clientId. Pour un visiteur connecté :

JSON
{
    "a1": "<!--blockstudio/acme/greeting-->  <a href=\"https://example.com/account/\">\n    Hi, Ada  </a>\n"
}

Une entrée dont la vérification échoue renvoie un code d’erreur au lieu de HTML, sans faire échouer le reste du lot. Ici, la deuxième entrée a modifié guestLabel sans signature correspondante, et la troisième a nommé un bloc qui n’est pas un îlot dynamique :

JSON
{
    "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"
    }
}

Chaque réponse contient Cache-Control: no-store, no-cache, must-revalidate, max-age=0, Pragma: no-cache et X-Robots-Tag: noindex. Le point de terminaison se trouve sous /wp-json, que le prérendu statique contourne toujours : ni le cache d’origine ni un CDN respectant les en-têtes de l’origine ne stockera donc de fragment.

Qui est le visiteur

L’environnement d’exécution envoie la requête avec credentials: 'same-origin', afin que le navigateur inclue le cookie de connexion WordPress. Le WordPress REST API ignore normalement l’authentification par cookie sans nonce, et un nonce ne peut pas se trouver dans une page mise en cache. Le point de terminaison de l’îlot gère lui-même ce cas : pour une requête de navigateur de même origine, il valide le cookie logged_in et rétablit l’identité de l’utilisateur avant le rendu.

La même origine est déterminée en comparant l’en-tête Sec-Fetch-Site et, s’il est présent, l’en-tête Origin à home_url(). Une requête provenant d’une autre origine et accompagnée du cookie est traitée comme anonyme : une requête venant d’un autre site n’affiche donc jamais le fragment personnel d’un visiteur. En pratique :

Requête Rendu en tant que
Requête fetch de même origine avec un cookie de connexion valide Utilisateur connecté
Requête interorigine avec le même cookie Visiteur anonyme
Aucun cookie Visiteur anonyme

De quelle page s’agit-il ?

Ajoutez "context": true à blockstudio.island lorsque le fragment a besoin de l’identité de sa page. Le marqueur signe alors l’ID d’article et le type d’article de la page interrogée, en plus des attributs. Dans le fragment, $block['postId'], $block['postType'], get_the_ID() et get_queried_object_id() font référence à cette page. Dans une boucle de requête, il s’agit toujours de la page externe interrogée, et non de l’élément de la boucle.

Le contexte de page est facultatif et fait également partie de la clé du cache de fragments. Le point de terminaison vérifie à nouveau les droits d’accès, même pour les fragments mis en cache, afin qu’un marqueur signé ne révèle pas une page devenue privée ou protégée par mot de passe. Consultez Contexte de page pour les détails de configuration et de sécurité. Aucun URL ni paramètre de requête arbitraire n’est rejoué.

Étape 4 : un compteur de panier qui s’actualise

Le deuxième îlot illustre l’autre style d’espace réservé et deux options d’exécution. Au lieu d’utiliser un fichier d’espace réservé distinct, le modèle vérifie $isIslandPlaceholder :

JSON
{
  "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
<?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; ?>

Les mêmes options existent dans tous les langages de modèle : isIsland, isIslandPlaceholder, isIslandFragment et islandPhase ("normal", "hydrate", "placeholder" ou "fragment"). Ici, le compteur vient d’un filtre acme/cart_count renseigné par votre code de commerce. Lorsqu’il renvoie 3, le point de terminaison renvoie :

JSON
{"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" diffère la requête jusqu’à ce que le marqueur entre dans la zone visible, en utilisant IntersectionObserver. Les îlots visibles qui apparaissent ensemble sont tout de même regroupés dans une seule requête. event désigne un événement de fenêtre qui récupère à nouveau l’îlot. Ainsi, après un appel d’ajout au panier, votre script n’a plus qu’à déclencher cet événement :

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

Réagir dans le code frontend

Les événements remontent depuis le marqueur : un seul écouteur sur document couvre toutes les îles. event.detail.name contient le nom du bloc :

JavaScript
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);
});

Après un échange, l’environnement d’exécution distribue blockstudio:island:rendered, puis blockstudio:island:hydrate. En cas d’échec, l’espace réservé reste en place et blockstudio:island:error se déclenche. Les îles hydratées ("island": "hydrate") ignorent entièrement la requête : leur HTML complet figure dans la page et elles ne reçoivent que l’événement hydrate, ce qui convient aux blocs interactifs compatibles avec la mise en cache, comme les onglets.

Mise en cache des fragments

Par défaut, les fragments sont rendus à chaque requête. Le message de bienvenue ci-dessus active une mise en cache de courte durée :

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

per: "user" fait varier le fragment mis en cache selon l’ID utilisateur WordPress ; les requêtes anonymes ne sont jamais mises en cache avec cette option, afin que deux visiteurs anonymes ne partagent pas une entrée destinée à un utilisateur. per: "global" partage un fragment pour un même bloc et des attributs identiques, ce qui convient aux contenus actualisés mais non personnels, comme un niveau de stock. ttl est défini par défaut sur 60 secondes, et cache: true correspond à un cache global de 60 secondes.

Modèle de sécurité

Le point de terminaison est public, mais ce n’est pas un moteur de rendu de blocs généraliste. Il ne rend une entrée que si toutes les conditions suivantes sont réunies :

  • le bloc est enregistré, dynamique et island.mode est défini sur dynamic
  • la signature correspond au nom du bloc et aux attributs conservés après le filtrage : seules les clés présentes à la fois dans le schéma du bloc et dans la liste d’autorisation de l’île

La signature est un HMAC-SHA256 calculé sur le nom normalisé du bloc et ses attributs, avec le sel auth du site qui sert le contenu. Les signatures sont créées au moment du rendu sur ce site et ne sont jamais intégrées à un thème. Cela entraîne deux conséquences. Un document rendu sur un environnement de préproduction contient des signatures de cet environnement : rendez donc les documents sur le site qui les sert. Et la rotation des sels WordPress invalide toutes les signatures des documents enregistrés ; purgez donc le prérendu statique après une rotation du sel.

Une requête accepte jusqu’à 50 îles ; au-delà, elle renvoie HTTP 413. Modifiez la limite avec blockstudio/islands/max_per_request. Des hooks de signature (blockstudio/islands/signature_payload, blockstudio/islands/signature, blockstudio/islands/verify_signature) sont disponibles pour les hébergeurs qui ont besoin d’un autre mécanisme.

Quand ne pas utiliser une île

Les fragments ne figurent pas dans le HTML initial ; les robots d’exploration ne les voient donc pas. Conservez le contenu important pour le SEO dans le rendu normal. Utilisez les îles dynamiques pour les éléments qui peuvent arriver après la structure de la page : liens de compte, état du panier, recommandations et commandes soumises à des autorisations. Si toute la page est personnalisée, comme un tableau de bord de compte, ajoutez plutôt son chemin à dynamicPaths et rendez-la dynamiquement.

Étapes suivantes