Aller au contenu

Contexte et communication entre blocs

La plupart des blocs sont autonomes. Ils ont leurs propres champs et leur propre modèle, sans se soucier de ce qui les entoure. Mais certains composants sont naturellement hiérarchiques : une grille de cartes dont le parent contrôle le nombre de colonnes et l’espacement, un tableau de prix dont le parent définit la devise, ou un conteneur de section qui indique à ses enfants d’utiliser un thème clair ou sombre.

WordPress fournit pour cela un contexte de blocAPI. Un bloc parent expose certaines de ses données, auxquelles les blocs enfants s’abonnent. Lorsque le parent change, les enfants sont mis à jour automatiquement. Blockstudio simplifie considérablement les choses : vous n’avez pas du tout besoin de configurer providesContext. Chaque bloc Blockstudio fournit automatiquement tous ses attributs comme contexte. Les blocs enfants n’ont qu’à ajouter une ligne dans leur block.json pour s’y abonner.

Ce guide présente quatre modèles de composants concrets qui utilisent le contexte, chacun illustrant un besoin de communication différent.

Fonctionnement du contexte dans Blockstudio

Dans WordPress standard, vous devez associer explicitement chaque attribut parent à une clé de contexte dans providesContext, puis répertorier ces clés dans le usesContext de l’enfant. Blockstudio supprime entièrement la première étape.

Bloc parent : aucune configuration nécessaire. Chaque bloc Blockstudio fournit automatiquement tous ses attributs sous le nom de son bloc.

Bloc enfant : ajoutez usesContext avec le nom du bloc parent :

JSON
{
  "usesContext": ["my-theme/parent-block"]
}

Modèle enfant : accédez aux attributs du parent via $context (ou la forme abrégée $c) :

PHP
<?php $parent = $context['my-theme/parent-block']; ?>
<p>Parent says: <?php echo esc_html( $parent['message'] ); ?></p>

Voilà toute la configuration. Pas de providesContext dans le parent, pas de correspondance d’attributs ni de code d’enregistrement. L’enfant reçoit tous les attributs transformés du parent : les champs média sont résolus en données de pièce jointe, les champs de sélection respectent returnFormat et les répéteurs sont entièrement développés.

Deux types de contexte

Blockstudio fournit deux variables de contexte dans les modèles, qui ont des rôles différents :

Variable Contenu Cas d’utilisation
$context / $c Attributs du bloc parent (via usesContext) Communication entre composants
$block['context'] / $b['context'] Données de boucle WordPress (postId, postType) Boucles de blocs de requête

Le premier sert aux blocs qui communiquent avec leurs parents. Le second concerne les blocs dans une boucle de requête qui doivent savoir quel article ils affichent. Ce guide porte sur le premier type.

Prise en charge dans l’éditeur

Dans l’éditeur, les mises à jour du contexte sont réactives. Lorsqu’un utilisateur modifie la valeur d’un champ du bloc parent, tous les blocs enfants abonnés au contexte de ce parent sont automatiquement rendus à nouveau avec la nouvelle valeur. Aucune actualisation manuelle n’est nécessaire.

Conteneur de section

Le modèle de contexte le plus courant : un bloc conteneur qui fournit les paramètres du thème à ses enfants. Le parent possède des champs pour la couleur d’arrière-plan, la couleur du texte et les marges intérieures. Les enfants lisent ces valeurs pour appliquer un style cohérent.

Parent : section

JSON
{
  "name": "my-theme/section",
  "title": "Section",
  "category": "design",
  "icon": "align-wide",
  "description": "Section wrapper with theme settings.",
  "blockstudio": {
    "attributes": [
      {
        "id": "theme",
        "type": "select",
        "label": "Theme",
        "default": "light",
        "options": [
          { "value": "light", "label": "Light" },
          { "value": "dark", "label": "Dark" },
          { "value": "accent", "label": "Accent" }
        ]
      },
      {
        "id": "spacing",
        "type": "select",
        "label": "Spacing",
        "default": "md",
        "options": [
          { "value": "sm", "label": "Small" },
          { "value": "md", "label": "Medium" },
          { "value": "lg", "label": "Large" }
        ]
      }
    ]
  }
}
PHP
<?php
$theme_classes = array(
	'light'  => 'bg-white text-gray-900',
	'dark'   => 'bg-gray-900 text-white',
	'accent' => 'bg-indigo-600 text-white',
);
$spacing_classes = array(
	'sm' => 'py-8',
	'md' => 'py-16',
	'lg' => 'py-24',
);
$classes = ( $theme_classes[ $a['theme'] ] ?? '' ) . ' ' . ( $spacing_classes[ $a['spacing'] ] ?? '' );
?>
<div useBlockProps class="<?php echo esc_attr( $classes ); ?>">
  <InnerBlocks
    allowedBlocks='<?php echo esc_attr( wp_json_encode( array( 'my-theme/section-heading', 'my-theme/section-text', 'core/columns', 'core/group' ) ) ); ?>'
  />
</div>

Enfant : titre de section

JSON
{
  "name": "my-theme/section-heading",
  "title": "Section Heading",
  "category": "design",
  "icon": "heading",
  "description": "Heading that adapts to section theme.",
  "usesContext": ["my-theme/section"],
  "parent": ["my-theme/section"],
  "blockstudio": {
    "attributes": [
      { "id": "text", "type": "text", "label": "Heading", "default": "Section Title" },
      {
        "id": "size",
        "type": "select",
        "label": "Size",
        "default": "lg",
        "options": [
          { "value": "sm", "label": "Small" },
          { "value": "lg", "label": "Large" },
          { "value": "xl", "label": "Extra Large" }
        ]
      }
    ]
  }
}
PHP
<?php
$section = $context['my-theme/section'] ?? array();
$theme   = $section['theme'] ?? 'light';

$color_class = match ( $theme ) {
	'light'  => 'text-gray-900',
	'dark'   => 'text-white',
	'accent' => 'text-white',
	default  => 'text-gray-900',
};

$size_class = match ( $a['size'] ) {
	'sm' => 'text-2xl',
	'lg' => 'text-4xl',
	'xl' => 'text-6xl',
	default => 'text-4xl',
};
?>
<h2 useBlockProps class="<?php echo esc_attr( "$color_class $size_class font-bold" ); ?>">
  <?php echo esc_html( $a['text'] ); ?>
</h2>

Ce que cela montre : le titre n’a pas son propre champ de couleur. Il lit la valeur theme de la section dans le contexte et adapte son apparence. Lorsque l’utilisateur fait passer la section de « Clair » à « Sombre » dans l’éditeur, la couleur du texte du titre est mise à jour immédiatement.

La propriété parent dans le block.json de l’enfant limite les emplacements où le bloc peut être inséré. Il apparaît dans l’outil d’insertion uniquement lorsque l’utilisateur se trouve dans un bloc my-theme/section. Cette propriété est facultative, mais recommandée pour les blocs qui n’ont de sens qu’à l’intérieur d’un parent précis.

Enfant : texte de section

JSON
{
  "name": "my-theme/section-text",
  "title": "Section Text",
  "category": "design",
  "icon": "text",
  "description": "Body text that adapts to section theme.",
  "usesContext": ["my-theme/section"],
  "parent": ["my-theme/section"],
  "blockstudio": {
    "attributes": [
      { "id": "text", "type": "textarea", "label": "Text", "default": "Section body text." }
    ]
  }
}
PHP
<?php
$section = $context['my-theme/section'] ?? array();
$theme   = $section['theme'] ?? 'light';

$color_class = match ( $theme ) {
	'dark', 'accent' => 'text-white/80',
	default          => 'text-gray-600',
};
?>
<p useBlockProps class="<?php echo esc_attr( "$color_class text-lg leading-relaxed" ); ?>">
  <?php echo esc_html( $a['text'] ); ?>
</p>

Le titre et le texte réagissent maintenant tous deux au thème de la section. L’utilisateur choisit un thème une seule fois dans le parent, et chaque enfant s’adapte.

Grille de cartes

Un bloc parent en grille qui contrôle les paramètres de mise en page de ses cartes enfants. Le parent définit le nombre de colonnes et l’espacement. Les enfants utilisent ces valeurs pour comprendre le contexte de leur mise en page et ajuster leur style en conséquence.

Parent : grille de cartes

JSON
{
  "name": "my-theme/card-grid",
  "title": "Card Grid",
  "category": "design",
  "icon": "grid-view",
  "description": "Responsive card grid with configurable columns.",
  "blockstudio": {
    "attributes": [
      {
        "id": "columns",
        "type": "range",
        "label": "Columns",
        "default": 3,
        "min": 1,
        "max": 4,
        "step": 1
      },
      {
        "id": "gap",
        "type": "select",
        "label": "Gap",
        "default": "md",
        "options": [
          { "value": "sm", "label": "Small" },
          { "value": "md", "label": "Medium" },
          { "value": "lg", "label": "Large" }
        ]
      },
      {
        "id": "cardStyle",
        "type": "select",
        "label": "Card Style",
        "default": "elevated",
        "options": [
          { "value": "elevated", "label": "Elevated (shadow)" },
          { "value": "outlined", "label": "Outlined (border)" },
          { "value": "flat", "label": "Flat (no decoration)" }
        ]
      }
    ]
  }
}
PHP
<?php
$gap_class = match ( $a['gap'] ) {
	'sm' => 'gap-4',
	'md' => 'gap-6',
	'lg' => 'gap-8',
	default => 'gap-6',
};
?>
<div useBlockProps class="grid grid-cols-<?php echo esc_attr( $a['columns'] ); ?> <?php echo esc_attr( $gap_class ); ?>">
  <InnerBlocks
    allowedBlocks='<?php echo esc_attr( wp_json_encode( array( 'my-theme/card' ) ) ); ?>'
    template='<?php echo esc_attr( wp_json_encode( array(
      array( 'my-theme/card', array() ),
      array( 'my-theme/card', array() ),
      array( 'my-theme/card', array() ),
    ) ) ); ?>'
  />
</div>

Enfant : carte

JSON
{
  "name": "my-theme/card",
  "title": "Card",
  "category": "design",
  "icon": "cover-image",
  "description": "Card that inherits style from its grid parent.",
  "usesContext": ["my-theme/card-grid"],
  "parent": ["my-theme/card-grid"],
  "blockstudio": {
    "attributes": [
      { "id": "image", "type": "files", "label": "Image", "multiple": false },
      { "id": "title", "type": "text", "label": "Title", "default": "Card Title" },
      { "id": "description", "type": "textarea", "label": "Description", "default": "Card description goes here." },
      { "id": "url", "type": "link", "label": "Link" }
    ]
  }
}
PHP
<?php
$grid      = $context['my-theme/card-grid'] ?? array();
$card_style = $grid['cardStyle'] ?? 'elevated';

$style_class = match ( $card_style ) {
	'elevated' => 'bg-white rounded-xl shadow-md',
	'outlined' => 'bg-white rounded-xl border border-gray-200',
	'flat'     => 'bg-gray-50 rounded-xl',
	default    => 'bg-white rounded-xl shadow-md',
};
?>
<div useBlockProps class="<?php echo esc_attr( "$style_class overflow-hidden" ); ?>">
  <?php if ( $a['image'] ) : ?>
    <img
      src="<?php echo esc_url( $a['image']['url'] ); ?>"
      alt="<?php echo esc_attr( $a['image']['alt'] ); ?>"
      class="w-full aspect-video object-cover" />
  <?php endif; ?>
  <div class="p-6">
    <h3 class="text-lg font-semibold"><?php echo esc_html( $a['title'] ); ?></h3>
    <p class="mt-2 text-gray-600"><?php echo esc_html( $a['description'] ); ?></p>
    <?php if ( $a['url'] ) : ?>
      <a href="<?php echo esc_url( $a['url']['url'] ); ?>" class="mt-4 inline-block text-indigo-600 font-medium">
        <?php echo esc_html( $a['url']['title'] ?: 'Learn more' ); ?>
      </a>
    <?php endif; ?>
  </div>
</div>

Ce que cela montre : la carte n’a pas son propre champ de style. Elle lit cardStyle dans le bloc parent de la grille. Lorsque l’utilisateur fait passer la grille de « Avec relief » à « Contour », toutes les cartes de la grille sont mises à jour simultanément. Elles restent ainsi visuellement cohérentes sans obliger l’utilisateur à les modifier une par une.

L’attribut template sur <InnerBlocks> préremplit la grille avec trois cartes, offrant ainsi un point de départ à l’utilisateur.

Tableau de prix

Un modèle plus avancé où le parent fournit une logique métier partagée (devise, période de facturation), utilisée par les enfants dans leur affichage. Cela évite de répéter les mêmes champs dans chaque niveau de prix.

Parent : tableau de prix

JSON
{
  "name": "my-theme/pricing-table",
  "title": "Pricing Table",
  "category": "text",
  "icon": "money-alt",
  "description": "Pricing comparison with shared currency and billing settings.",
  "blockstudio": {
    "attributes": [
      {
        "id": "currency",
        "type": "select",
        "label": "Currency",
        "default": "usd",
        "options": [
          { "value": "usd", "label": "USD ($)" },
          { "value": "eur", "label": "EUR (\u20ac)" },
          { "value": "gbp", "label": "GBP (\u00a3)" }
        ]
      },
      {
        "id": "period",
        "type": "select",
        "label": "Billing Period",
        "default": "month",
        "options": [
          { "value": "month", "label": "Monthly" },
          { "value": "year", "label": "Yearly" }
        ]
      }
    ]
  }
}
PHP
<div useBlockProps class="grid grid-cols-3 gap-6 items-start">
  <InnerBlocks
    allowedBlocks='<?php echo esc_attr( wp_json_encode( array( 'my-theme/pricing-tier' ) ) ); ?>'
    template='<?php echo esc_attr( wp_json_encode( array(
      array( 'my-theme/pricing-tier', array( 'name' => 'Starter', 'price' => 9 ) ),
      array( 'my-theme/pricing-tier', array( 'name' => 'Pro', 'price' => 29, 'highlighted' => true ) ),
      array( 'my-theme/pricing-tier', array( 'name' => 'Enterprise', 'price' => 99 ) ),
    ) ) ); ?>'
  />
</div>

Enfant : niveau de prix

JSON
{
  "name": "my-theme/pricing-tier",
  "title": "Pricing Tier",
  "category": "text",
  "icon": "tag",
  "description": "Single pricing tier that reads currency from parent.",
  "usesContext": ["my-theme/pricing-table"],
  "parent": ["my-theme/pricing-table"],
  "blockstudio": {
    "attributes": [
      { "id": "name", "type": "text", "label": "Tier Name", "default": "Plan" },
      { "id": "price", "type": "number", "label": "Price", "default": 0 },
      { "id": "highlighted", "type": "toggle", "label": "Highlighted", "default": false },
      {
        "id": "features",
        "type": "repeater",
        "label": "Features",
        "attributes": [
          { "id": "text", "type": "text", "label": "Feature" }
        ]
      }
    ]
  }
}
PHP
<?php
$table    = $context['my-theme/pricing-table'] ?? array();
$currency = $table['currency'] ?? 'usd';
$period   = $table['period'] ?? 'month';

$symbols = array(
	'usd' => '$',
	'eur' => "\u{20AC}",
	'gbp' => "\u{00A3}",
);
$symbol = $symbols[ $currency ] ?? '$';

$period_label = $period === 'year' ? '/year' : '/month';

$border_class = $a['highlighted'] ? 'border-2 border-indigo-600' : 'border border-gray-200';
?>
<div useBlockProps class="<?php echo esc_attr( "rounded-xl p-8 $border_class" ); ?>">
  <h3 class="text-lg font-semibold"><?php echo esc_html( $a['name'] ); ?></h3>
  <div class="mt-4">
    <span class="text-4xl font-bold"><?php echo esc_html( $symbol . $a['price'] ); ?></span>
    <span class="text-gray-500"><?php echo esc_html( $period_label ); ?></span>
  </div>
  <?php if ( ! empty( $a['features'] ) ) : ?>
    <ul class="mt-6 space-y-3">
      <?php foreach ( $a['features'] as $feature ) : ?>
        <li class="flex items-center gap-2">
          <span class="text-indigo-600">&#10003;</span>
          <?php echo esc_html( $feature['text'] ); ?>
        </li>
      <?php endforeach; ?>
    </ul>
  <?php endif; ?>
</div>

Ce que cela montre : le symbole de la devise et la période de facturation sont définis une seule fois dans le tableau de prix, puis hérités par chaque niveau. Lorsque l’utilisateur passe des USD aux EUR, le symbole de la devise est mis à jour simultanément dans les trois niveaux. Sans contexte, il faudrait dupliquer le champ de devise dans chaque niveau et les synchroniser manuellement.

Contexte de boucle de requête

WordPress fournit un autre type de contexte dans les boucles de blocs de requête. Lorsqu’un bloc est rendu dans une boucle, $block['context'] (ou $b['context']) contient les données de l’article de l’itération en cours :

PHP
<?php
$loop_post_id   = $block['context']['postId'];
$loop_post_type = $block['context']['postType'];
?>
<article useBlockProps>
  <h2><?php echo esc_html( get_the_title( $loop_post_id ) ); ?></h2>
  <p><?php echo esc_html( get_the_excerpt( $loop_post_id ) ); ?></p>
  <a href="<?php echo esc_url( get_permalink( $loop_post_id ) ); ?>">Read more</a>
</article>

Cela diffère du contexte du bloc parent ($context / $c). Le contexte de boucle est fourni par WordPress core et ne contient que postId et postType. Vous n’avez pas besoin de usesContext dans votre block.json pour cela. Blockstudio abonne automatiquement chaque bloc à postId et postType.

Utilité du contexte de boucle : cartes d’articles personnalisées dans des blocs de requête, blocs qui affichent les métadonnées d’un article, ou tout bloc dont le rendu doit varier selon l’article dans une boucle.

Vous pouvez aussi accéder aux données de l’article de la page externe, quel que soit le contexte de boucle :

PHP
$outer_post_id   = $block['postId'];   // always the current page
$loop_post_id    = $block['context']['postId'];  // current loop iteration

Contexte imbriqué

Le contexte se propage dans toute l’arborescence des blocs, et pas seulement sur un niveau. Si le bloc A contient le bloc B, qui contient lui-même le bloc C, C peut s’abonner au contexte de A. Cela fonctionne parce que WordPress propage le contexte à tous les niveaux d’InnerBlocks.

Code
my-theme/section (theme: "dark")
└── core/columns
    └── core/column
        └── my-theme/section-heading (reads section context)

Le titre n’a pas besoin d’être un enfant direct de la section. Il peut être imbriqué dans des blocs core (colonnes, groupes, etc.) et recevoir tout de même le contexte de la section. L’abonnement usesContext fonctionne à n’importe quelle profondeur.

Plusieurs parents

Un enfant peut s’abonner à plusieurs parents :

JSON
{
  "usesContext": ["my-theme/section", "my-theme/card-grid"]
}
PHP
<?php
$section = $context['my-theme/section'] ?? array();
$grid    = $context['my-theme/card-grid'] ?? array();

$theme     = $section['theme'] ?? 'light';
$cardStyle = $grid['cardStyle'] ?? 'elevated';
?>

Si un parent est introuvable dans l’arborescence des ancêtres, sa clé sera absente de $context. Utilisez toujours l’opérateur de coalescence des valeurs nulles (??) ou vérifiez isset() lorsque vous lisez des valeurs de contexte, au cas où le bloc serait utilisé en dehors de son parent attendu.

Programmation défensive

Les blocs qui utilisent le contexte doivent toujours gérer le cas où le parent est absent. Un utilisateur peut insérer le bloc en dehors du parent prévu, ou le bloc parent peut ne pas avoir de valeur définie pour un champ donné.

PHP
<?php
// Always provide defaults
$section = $context['my-theme/section'] ?? array();
$theme   = $section['theme'] ?? 'light';
$spacing = $section['spacing'] ?? 'md';
?>

Pour imposer qu’un enfant n’apparaisse qu’à l’intérieur de son parent, ajoutez la propriété parent :

JSON
{
  "parent": ["my-theme/section"]
}

Cela retire le bloc de l’outil d’insertion lorsque l’utilisateur ne se trouve pas dans un bloc my-theme/section. Sans parent, le bloc apparaît partout, et votre modèle doit gérer correctement l’absence de contexte.

Utilisez parent pour les blocs qui n’ont aucun sens en dehors de leur conteneur (niveaux de prix, éléments d’une grille de cartes). Ne l’utilisez pas pour les blocs autonomes qui bénéficient simplement d’un style supplémentaire fourni par un parent (titres de section qui peuvent aussi être utilisés seuls).

Conseils

Le contexte est en lecture seule. Les enfants ne peuvent pas modifier les attributs du parent via le contexte. Les données circulent vers le bas, jamais vers le haut. Si un enfant doit communiquer quelque chose à son parent, il faut une autre approche (par exemple, l’état serveur partagé via l’API d’interactivité ou les métadonnées d’article).

Tous les attributs sont fournis. Blockstudio fournit chaque attribut du bloc parent, pas seulement ceux que vous sélectionnez. L’enfant peut donc accéder à tous les champs définis par le parent. Si le parent ajoute un champ ultérieurement, les enfants y ont automatiquement accès sans modification de configuration.

Valeurs transformées. Les valeurs du contexte passent par le pipeline de transformation des attributs de Blockstudio. Les champs fichier contiennent toutes les données de la pièce jointe (url, alt, width, height), les champs de sélection respectent returnFormat et les répéteurs sont développés récursivement. Vous obtenez la même structure de données que $a dans le modèle parent.

Réactivité de l’éditeur. Lorsqu’un utilisateur modifie un champ parent dans l’éditeur, les blocs enfants sont automatiquement rendus à nouveau. Cela s’appuie sur la propagation de contexte intégrée de WordPress, avec un React useEffect qui détecte les changements de contexte et déclenche un nouveau rendu côté serveur de l’enfant.

Gardez le contexte léger. Même si Blockstudio fournit automatiquement tous les attributs du parent, les enfants ne doivent lire que les valeurs dont ils ont réellement besoin. Il ne s’agit pas d’un enjeu de performances (les données sont déjà présentes), mais de clarté du code. Documentez les champs parents dont dépend un enfant, afin que les futurs développeurs comprennent cette relation.

Étapes suivantes

  • Référence du contexte : variables de modèle, contexte de boucle et structure de données $block.
  • InnerBlocks : le composant <InnerBlocks />, allowedBlocks, les modèles et le filtre d’enveloppe du site public.
  • Guide sur l’interactivité : pour la réactivité côté client entre les blocs (l’API d’interactivité gère ce que le contexte ne peut pas faire : communication de l’enfant vers le parent, état partagé entre blocs et mises à jour déclenchées par l’utilisateur).