Aller au contenu

Îlots

Les îlots de blocs permettent à un bloc de conserver le processus de rendu normal Blockstudio tout en déplaçant le contenu propre à la requête hors de la réponse initiale HTML.

C’est utile lorsqu’une page doit être mise en cache de manière intensive, mais qu’un bloc dépend encore du visiteur actuel, de sa session, de son panier, de ses autorisations ou d’un autre contexte de requête en temps réel.

Les blocs Blockstudio restent des blocs WordPress dynamiques. Les îlots ne les transforment pas en HTML statiques précompilés. À la place, Blockstudio modifie le rendu lors de la première requête :

  • les îlots hydratés affichent leur HTML normal compatible avec la mise en cache et reçoivent un événement de montage
  • les îlots dynamiques affichent d’abord un espace réservé compatible avec la mise en cache, puis récupèrent le fragment réel depuis le navigateur du visiteur

Modes

Îlots hydratés

Utilisez un îlot hydraté lorsque la sortie du serveur peut être mise en cache et que le bloc a uniquement besoin d’un signal de montage sur l’interface publique.

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

L’HTML complet du bloc est présent dans la réponse initiale. Le moteur d’îlots n’effectue pas de requête REST pour le récupérer. Il envoie blockstudio:island:hydrate sur le marqueur afin que le code de l’interface publique puisse lui associer un comportement.

Îlots dynamiques

Utilisez un îlot dynamique lorsque la sortie réelle du bloc doit être rendue dans le contexte de la requête du visiteur.

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

La réponse initiale contient uniquement un espace réservé. Le navigateur regroupe tous les îlots dynamiques prêts en une seule requête vers :

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

Le point de terminaison ne rend que les blocs Blockstudio enregistrés qui sont dynamiques et dont blockstudio.island.mode est défini sur dynamic.

Configuration

La valeur island peut être une forme abrégée ou un objet.

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

true et "hydrate" signifient tous deux que l’îlot est hydraté. "dynamic" signifie qu’il est dynamique.

JSON
{
  "blockstudio": {
    "island": {
      "mode": "dynamic",
      "tag": "section",
      "attributes": ["productId", "variant"],
      "placeholder": "cart-placeholder.php",
      "loading": "visible",
      "event": "cart:updated",
      "cache": {
        "ttl": 60,
        "per": "user"
      }
    }
  }
}
Propriété Type Valeur par défaut Description
mode "hydrate" ou "dynamic" "hydrate" Mode îlot.
tag string "div" Balise enveloppe du marqueur.
attributes string[] tous les attributs du bloc Liste d’autorisation des attributs envoyés aux requêtes de fragments dynamiques.
placeholder string détecté automatiquement Chemin relatif du modèle d’espace réservé.
loading "eager" ou "visible" "eager" Moment où le runtime doit récupérer un îlot dynamique.
event string non défini Nom de l’événement de fenêtre qui actualise un îlot dynamique.
context boolean false Signer et restaurer l’ID et le type d’article de la page interrogée pour les fragments dynamiques.
cache boolean ou object false Stratégie facultative de mise en cache des fragments.

Contexte de la page

Les fragments dynamiques sont normalement rendus indépendamment de l’enveloppe de la page. Optez pour son identité de page lorsque votre bloc lit des paramètres propres à la page ou du contenu associé :

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

Le marqueur inclut postId et postType de la page interrogée dans data-bs-island-context. Les deux valeurs sont signées avec le nom du bloc et les attributs autorisés à l’aide du secret du site qui les sert. Elles ne peuvent être ni modifiées ni ajoutées à une requête sans invalider la signature. Le runtime les envoie avec la requête de fragments groupée existante, y compris lors des actualisations visibles et déclenchées par un événement. Cela fonctionne également avec bs_render_block(), bs_block() et les balises de bloc.

Lors du rendu des fragments, $block['postId'], $block['postType'], get_the_ID() et get_queried_object_id() font référence à cette page. WordPress Les variables globales de requête et d’article sont restaurées ensuite, y compris après une exception de rendu. Il s’agit de la page interrogée, et non d’un élément dans une boucle de requête. Les paramètres arbitraires de URL ne sont pas rejoués et l’URL de la requête d’origine n’est pas restauré. Utilisez get_permalink($block['postId']) si vous avez besoin du HTML URL canonique de la page. Les archives et les rendus sans article interrogé n’envoient aucune identité de page.

Le point de terminaison vérifie que la page existe toujours, qu’elle a le type d’article signé et que le visiteur actuel peut la lire avant de consulter le cache des fragments. Une signature valide ne contourne ni la confidentialité des articles ou leur protection par mot de passe, ni l’éligibilité de l’îlot, les listes d’autorisation des attributs ou les propres contrôles d’autorisation de votre bloc. L’identité de la page fait toujours partie de la clé du cache des fragments lorsqu’elle est présente ; le même bloc et les mêmes attributs sur différentes pages ne partagent donc jamais un fragment. Utilisez per: "user" ou désactivez le cache des fragments si la sortie dépend également du visiteur.

Si context est omis ou vaut false, les marqueurs existants et le comportement sans contexte restent inchangés. Ne placez pas de données confidentielles dans le marqueur public.

Espaces réservés dynamiques

Les îlots dynamiques doivent afficher un espace réservé pouvant être partagé dans un cache de page complet. N’incluez pas de données propres au visiteur dans la branche de l’espace réservé.

Blockstudio recherche les espaces réservés dans cet ordre :

  1. le chemin explicite island.placeholder
  2. placeholder.php
  3. placeholder.blade.php
  4. placeholder.twig
  5. placeholder.html
  6. le modèle normal avec les indicateurs d’espace réservé
PHP
<div class="cart-count-placeholder">
  Loading cart...
</div>

Si aucun fichier d’espace réservé n’existe, utilisez les indicateurs du modèle normal :

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

Les mêmes valeurs sont disponibles dans les modèles PHP, Twig et Blade :

  • isIsland
  • isIslandPlaceholder
  • isIslandFragment
  • islandPhase

islandPhase est "normal", "hydrate", "placeholder" ou "fragment".

Comportement du moteur

Blockstudio n’injecte le moteur d’îlots que si la page rendue contient un marqueur d’îlot. Les pages sans îlots ne chargent aucune JavaScript supplémentaire liée aux îlots.

Pour les îlots dynamiques, le moteur :

  1. collecte tous les marqueurs prêts
  2. supprime les doublons de paires identiques de nom de bloc, d’attributs et de signature
  3. envoie une requête REST groupée
  4. remplace chaque espace réservé par le fragment reçu
  5. envoie blockstudio:island:rendered
  6. envoie blockstudio:island:hydrate

Les îlots loading: "eager" sont rendus dès le démarrage du moteur. Les îlots loading: "visible" attendent IntersectionObserver. Si plusieurs îlots visibles entrent dans la fenêtre d’affichage en même temps, ils sont regroupés dans une seule requête.

event actualise un îlot lorsque l’événement de fenêtre nommé se déclenche :

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

En cas d’échec, l’espace réservé reste en place et blockstudio:island:error est envoyé.

Point de terminaison des fragments

Le point de terminaison des îlots est public, mais ce n’est pas une API générale de rendu des blocs.

Chaque marqueur contient :

  • le nom du bloc
  • les attributs autorisés
  • une signature générée côté serveur

Le point de terminaison n’effectue le rendu que si :

  • le bloc est enregistré
  • le bloc est un bloc WordPress dynamique
  • le bloc est marqué comme îlot Blockstudio dynamique
  • les attributs reçus respectent le schéma du bloc et la liste d’autorisation de l’îlot
  • la signature correspond au nom de bloc et aux attributs normalisés

Les signatures sont générées au moment du rendu sur le site WordPress qui sert la page, à partir des sels de ce site et du contenu de l’îlot. Elles ne sont ni exportées ni intégrées à un thème.

Les réponses du point de terminaison sont marquées comme non mises en cache. Pour mettre les fragments en cache, utilisez island.cache.

Mise en cache des fragments

Par défaut, les fragments dynamiques ne sont pas mis en cache.

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

true utilise un cache global de courte durée. Utilisez la forme objet pour définir explicitement les paramètres :

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

per: "global" partage un fragment mis en cache pour le même bloc, les mêmes attributs et le même contexte de page avec opt-in. per: "user" fait varier le cache selon l’ID utilisateur WordPress actuel.

Rendu programmatique

Les îlots fonctionnent partout où les blocs Blockstudio sont rendus :

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

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

Ils fonctionnent également avec les balises de bloc :

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

La sortie initiale contient toujours le marqueur de l’îlot et son espace réservé ; le moteur est injecté si la réponse rendue contient ce marqueur.

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() valide les métadonnées du bloc. Les marqueurs dynamiques ne sont créés que pour les blocs Blockstudio dynamiques enregistrés dont island.mode est défini sur dynamic.

Hooks

Détection et balisage :

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

Point de terminaison et rendu :

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

blockstudio/islands/max_per_request modifie le nombre maximal d’îlots dynamiques acceptés par une requête groupée au point de terminaison. La valeur par défaut est 50.

Configuration du moteur :

PHP
blockstudio/islands/endpoint_url
blockstudio/islands/loading

Signatures :

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

Actions de cycle de vie :

PHP
blockstudio/islands/registered
blockstudio/islands/rendered

Quand ne pas utiliser les îlots

N’utilisez pas d’îlot dynamique pour du contenu essentiel au SEO. Les fragments d’îlots dynamiques ne figurent pas dans la réponse initiale HTML et ne sont pas destinés à être indexés.

Utilisez le rendu normal ou un îlot hydraté lorsque le contenu peut être mis en cache et doit être visible par les robots d’indexation. Réservez les îlots dynamiques au contenu qui peut arriver après la structure de la page, comme les UI de compte, l’état du panier, les recommandations personnalisées ou les commandes soumises à des autorisations.