Aller au contenu

Composer des modèles avec des balises de blocs

Dès qu’un projet compte plusieurs blocs, les modèles doivent commencer à s’imbriquer. Un bloc de fonctionnalités veut afficher trois cartes. Une page d’accueil veut une section avec un bouton à l’intérieur. Vous pouvez appeler bs_render_block() pour chacun, mais un modèle rempli d’appels PHP et de tableaux imbriqués est difficile à lire et encore plus à imbriquer.

Les balises de blocs permettent d’écrire un bloc directement à l’endroit où son contenu doit apparaître, sous forme de balise HTML :

HTML
<bs:acme-card title="Fast" text="Rendered on the server." />

Une même balise a deux significations selon l’endroit où elle est écrite. Dans un modèle de bloc ou le contenu d’une publication, elle est remplacée par le HTML rendu du bloc. Dans une page, un motif ou la source d’un modèle de site, elle devient un véritable bloc WordPress qui apparaît dans l’éditeur. Ce guide crée quelques blocs, les compose de ces deux façons, ajoute un préfixe de projet pour raccourcir les noms, puis montre comment convertir ces formes abrégées en notation portable.

Les blocs

Trois petits blocs suffisent. Voici une carte avec deux champs :

JSON
{
  "$schema": "https://blockstudio.dev/schema/block",
  "apiVersion": 3,
  "name": "acme/card",
  "title": "Card",
  "blockstudio": {
    "attributes": [
      { "id": "title", "type": "text", "label": "Title", "default": "" },
      { "id": "text", "type": "textarea", "label": "Text", "default": "" }
    ]
  }
}
PHP
<article useBlockProps class="acme-card">
  <h3><?php echo esc_html( $a['title'] ); ?></h3>
  <p><?php echo esc_html( $a['text'] ); ?></p>
</article>

Une section qui enveloppe tout ce qui est placé à l’intérieur, avec un champ heading déclaré comme celui de la carte :

PHP
<section useBlockProps class="acme-section">
  <h2><?php echo esc_html( $a['heading'] ); ?></h2>
  <InnerBlocks />
</section>

Et un bouton dans un second espace de noms, acme-ui/button, avec les champs label et href :

PHP
<a useBlockProps class="acme-button" href="<?php echo esc_url( $a['href'] ); ?>"><?php echo esc_html( $a['label'] ); ?></a>

Balises dans un modèle de bloc

Les modèles de blocs rendent les balises automatiquement. Aucune configuration n’est nécessaire. Un bloc de fonctionnalités peut afficher directement deux cartes et un séparateur de base :

PHP
<div useBlockProps class="acme-features">
  <bs:acme-card title="Fast" text="Rendered on the server." />
  <block name="acme/card" title="Typed" text="Fields come from block.json." />
  <block name="core/separator" />
</div>

Le rendu de acme/features produit :

HTML
<!--blockstudio/acme/features--><div class="acme-features wp-block-acme-features">
  <!--blockstudio/acme/card--><article class="acme-card wp-block-acme-card">
  <h3>Fast</h3>
  <p>Rendered on the server.</p>
</article>

  <!--blockstudio/acme/card--><article class="acme-card wp-block-acme-card">
  <h3>Typed</h3>
  <p>Fields come from block.json.</p>
</article>

  <hr class="wp-block-separator has-alpha-channel-opacity">
</div>

Chaque bloc Blockstudio dans la sortie est précédé d’un commentaire <!--blockstudio/namespace/slug-->. Le tampon de page le retire de la réponse ; pour une sortie qui contourne le tampon, utilisez bs_strip_render_markers(). Les deux syntaxes sont équivalentes. <bs:acme-card> encode le nom du bloc dans la balise, et <block name="acme/card"> le transmet comme attribut. Chaque autre attribut devient une valeur de champ : title parvient donc au modèle de carte sous la forme $a['title']. Les blocs natifs fonctionnent aussi ; ils sont rendus par WordPress à l’aide des moteurs de rendu de blocs intégrés.

Balises jumelées et contenu interne

Une balise jumelée transmet ses éléments enfants au bloc. Pour un bloc Blockstudio, ils remplissent <InnerBlocks />, et les balises imbriquées sont rendues en premier :

HTML
<bs:acme-section heading="Why Acme">
  <bs:acme-card title="Fast" text="Rendered on the server." />
  <bs:acme-ui-button label="Get started" href="/start" />
</bs:acme-section>
HTML
<!--blockstudio/acme/section--><section class="acme-section wp-block-acme-section">
  <h2>Why Acme</h2>
  <div>
  <!--blockstudio/acme/card--><article class="acme-card wp-block-acme-card">
  <h3>Fast</h3>
  <p>Rendered on the server.</p>
</article>

  <!--blockstudio/acme-ui/button--><a class="acme-button wp-block-acme-ui-button" href="/start">Get started</a>

</div>
</section>

Comment le nom d’une balise devient un nom de bloc

Une balise <bs:> ne contient pas de barre oblique, alors Blockstudio en recherche une. Il remplace chaque trait d’union par une barre oblique, de gauche à droite, et utilise le premier résultat correspondant à un bloc enregistré. <bs:acme-card> correspond à acme/card dès le premier essai. <bs:acme-ui-button> essaie acme/ui-button, ne trouve rien, puis correspond à acme-ui/button. Les espaces de noms contenant des traits d’union fonctionnent donc sans configuration, tant que les deux possibilités ne sont pas toutes deux présentes.

Raccourcir les noms avec des préfixes

<bs:acme-ui-button> est précis, mais long. Un préfixe de projet associe un préfixe de balise court à un ou plusieurs espaces de noms. Configurez-le dans blockstudio.json :

JSON
{
  "$schema": "https://blockstudio.dev/schema/blockstudio",
  "blockTags": {
    "prefixes": {
      "acme": ["acme"],
      "ui": ["acme-ui"]
    }
  }
}

Vous pouvez aussi enregistrer la même association depuis PHP :

PHP
add_filter( 'blockstudio/block_tags/prefixes', function ( $prefixes ) {
	$prefixes['acme'] = array( 'acme' );
	$prefixes['ui']   = array( 'acme-ui' );

	return $prefixes;
} );

Désormais, <acme-card> correspond à acme/card, et <ui-button> à acme-ui/button. Si un préfixe répertorie plusieurs espaces de noms, ils sont testés dans l’ordre et le premier bloc enregistré l’emporte. Un bloc de projet peut ainsi remplacer un bloc de bibliothèque portant le même identifiant.

Les préfixes peuvent aussi être imbriqués. <acme-ui-button> essaie d’abord acme/ui-button. Ce bloc n’existe pas, et le reste de la balise, ui-button, est lui-même une balise à préfixe enregistrée. La résolution poursuit donc avec acme-ui/button. Une correspondance directe l’emporte toujours sur une correspondance imbriquée.

HTML
<bs:acme-section heading="Why Acme">
  <acme-card title="Fast" text="Rendered on the server." />
  <acme-ui-button label="Get started" href="/start" />
</bs:acme-section>

Cela génère exactement le même HTML que la version canonique ci-dessus.

Quelques règles s’appliquent aux préfixes :

  • Un préfixe contient des lettres minuscules et des chiffres, commence par une lettre et ne contient pas de tiret.
  • Si une balise avec préfixe ne correspond à aucun bloc enregistré, elle reste telle quelle dans la sortie. Ainsi, <acme-missing title="x" /> reste inchangée.
  • Les alias exacts du filtre blockstudio/block_tags/tag_aliases ont priorité sur les préfixes. Un alias associe une balise avec tiret à un bloc. Par exemple, $aliases['acme-cta'] = 'acme-ui/button'; fait en sorte que <acme-cta> rende le bouton.

Les balises avec préfixe et les alias sont rendus dans les modèles de blocs, comme les balises <bs:> et <block> de Blockstudio 7.5.

Attributs

Les attributs correspondant à un identifiant de champ deviennent des valeurs de champ. Deux préfixes ont un autre effet :

  • Les attributs data-* sont copiés sur l’élément racine du bloc rendu.
  • Les attributs html-* sont copiés sur l’élément racine sans leur préfixe : html-id="intro" devient donc id="intro".
HTML
<bs:acme-card title="Hi" text="There" data-track="card" html-id="intro" html-class="featured" />
HTML
<article data-track="card" id="intro" class="featured">
  <h3>Hi</h3>
  <p>There</p>
</article>

html-class définit l’attribut sans y ajouter de valeur : les classes acme-card wp-block-acme-card propres au bloc disparaissent. Pour permettre à l’appelant d’ajouter des classes au bloc, déclarez un champ à cet effet et fusionnez-le dans le modèle.

Tout autre attribut qui ne correspond pas à un champ déclaré est supprimé. Un class="wide" simple sur <bs:acme-card> rend la carte sans cet attribut. Blockstudio 7.7 signale ces attributs par un avis _doing_it_wrong() lorsque WP_DEBUG est activé.

Les mêmes balises dans les sources de pages

Dans les pages fondées sur des fichiers, les motifs et les modèles de site, les balises ne sont pas rendues. Elles sont converties en blocs lors de l’analyse de la source et apparaissent donc dans l’éditeur. Voici cette source de page :

HTML
<bs:acme-section heading="Why Acme">
  <p>Everything below is a real block.</p>
  <acme-card title="Fast" text="Rendered on the server." />
  <acme-ui-button label="Get started" href="/start" />
</bs:acme-section>

Elle est analysée pour produire ce balisage de blocs (sauts de ligne ajoutés pour faciliter la lecture) :

HTML
<!-- wp:acme/section {"blockstudio":{"attributes":{"heading":"Why Acme"}}} -->
<!-- wp:paragraph --><p>Everything below is a real block.</p><!-- /wp:paragraph -->
<!-- wp:acme/card {"blockstudio":{"attributes":{"title":"Fast","text":"Rendered on the server."}}} /-->
<!-- wp:acme-ui/button {"blockstudio":{"attributes":{"label":"Get started","href":"/start"}}} /-->
<!-- /wp:acme/section -->

Les valeurs des champs sont placées sous blockstudio.attributes, où les blocs Blockstudio les conservent, et le paragraphe ainsi que les deux blocs internes deviennent des blocs enfants de la section. Les préfixes et les alias sont résolus ici comme dans les modèles.

Balises dans le contenu des publications

Par défaut, le contenu rédigé dans l’éditeur ou stocké dans des widgets n’est pas analysé. Activez le rendu au niveau des pages dans blockstudio.json :

JSON
{
  "blockTags": {
    "enabled": true
  }
}

Les balises dans the_content et widget_text sont alors rendues à la priorité 5. Cette même option enregistre un filtre pour le rendu des balises dans n’importe quelle chaîne :

PHP
$html = apply_filters( 'blockstudio/block_tags/render', $content );

Limitez les balises pouvant être rendues à l’aide des motifs allow et deny, qui acceptent les caractères génériques fnmatch() et s’appliquent à chaque syntaxe et aux deux modes de rendu :

JSON
{
  "blockTags": {
    "enabled": true,
    "deny": ["acme-ui/*"]
  }
}

Une fois cette règle appliquée, <acme-ui-button> et <bs:acme-ui-button> restent dans la sortie sans être rendues. deny a priorité sur allow. Les filtres blockstudio/block_tags/allow et blockstudio/block_tags/deny modifient les mêmes listes depuis PHP.

L’analyse vérifie la notation canonique

L’extension PHPStan valide les balises de blocs dans les modèles PHP, Twig et Blade. Toute faute dans un nom de champ ou de bloc est signalée avec le bloc auquel elle correspond :

Text
  3      Block tag "acme/card" has unknown attribute "txt" in index.php
         🪪  blockstudio.blockTag.attribute
  4      Block tag references unknown block "acme/cards" in index.php
         🪪  blockstudio.blockTag.unknown

Dans la version 7.6, cela concerne les balises <bs:> et <block>. Une balise avec préfixe telle que <acme-card txt="..."> n’est pas vérifiée. Blockstudio 7.7 étend la règle aux balises avec préfixe, aux sources de pages et aux éléments HTML mappés. Son indication répertorie les attributs globaux qu’une balise peut transmettre.

Convertir les formes abrégées en notation canonique

Les balises avec préfixe et les alias sont des commodités propres au projet. Elles ne sont résolues que là où les filtres et les paramètres du projet sont chargés. Une fois copié dans un autre projet, une bibliothèque de blocs ou le contexte d’un agent de programmation, un modèle perd donc leur signification. <bs:namespace-slug> consigne le véritable nom du bloc et fonctionne partout, raison pour laquelle les exemples, diagnostics et sorties générées de Blockstudio l’utilisent.

Une commande autonome convertit les formes abrégées en cette notation. Prenons un projet dont les sources utilisent encore les formes courtes : elles comprennent un alias, une balise pour un bloc qui n’existe plus et un exemple dans un extrait de code :

PHP
<div useBlockProps class="acme-features">
  <acme-card title="Fast" text="Rendered on the server." />
  <acme-ui-button label="Get started" href="/start" />
</div>
PHP
<acme-section heading="Why Acme">
  <acme-cta label="Talk to us" href="/contact" />
  <acme-quote text="Missing block" />
</acme-section>
<pre><code>&lt;acme-card /&gt; <acme-card title="Example" /></code></pre>

La commande ne charge pas WordPress. Elle prend donc la configuration du projet sous forme de fichiers JSON conservés en dehors de l’arborescence analysée :

JSON
{ "acme": ["acme"], "ui": ["acme-ui"] }
JSON
["acme/card", "acme/section", "acme/features", "acme-ui/button"]
JSON
{ "acme-cta": "acme-ui/button" }

Commencez par un essai à blanc, qui est également le comportement par défaut :

Shell
php vendor/blockstudio/blockstudio/bin/migrate-block-tags.php \
  --root="$PWD" \
  --prefix-map=/tmp/acme-tags/prefixes.json \
  --known-blocks=/tmp/acme-tags/blocks.json \
  --aliases=/tmp/acme-tags/aliases.json \
  --report=/tmp/acme-tags/report.json \
  --dry-run
Text
Report: /tmp/acme-tags/report.json
Dry run: 2 files, 2 changed, 5 replacements, 1 unknown, 0 ambiguous, 1 manual.

Le rapport répertorie chaque correspondance qu’il appliquerait et chaque cas qu’il ne peut pas deviner :

JSON
{
  "mappings": [
    { "legacy": "acme-card", "canonical": "bs:acme-card", "block": "acme/card", "occurrences": 1 },
    { "legacy": "acme-cta", "canonical": "bs:acme-ui-button", "block": "acme-ui/button", "occurrences": 1 },
    { "legacy": "acme-section", "canonical": "bs:acme-section", "block": "acme/section", "occurrences": 2 },
    { "legacy": "acme-ui-button", "canonical": "bs:acme-ui-button", "block": "acme-ui/button", "occurrences": 1 }
  ],
  "unknown": [
    { "path": "pages/home/index.php", "line": 3, "column": 4, "tag": "acme-quote", "reason": "no-known-block" }
  ],
  "manual": [
    { "path": "pages/home/index.php", "line": 5, "column": 33, "tag": "acme-card", "reason": "code-sample" }
  ]
}

Le rapport est abrégé ici. Il consigne aussi la configuration et les empreintes avant et après pour chaque fichier. Les balises ouvrante et fermante d’une section comptent comme deux occurrences. acme-quote correspond au préfixe acme, mais ne désigne aucun bloc connu : la balise est donc inconnue. acme-card dans <pre><code> est un exemple, pas du balisage. Elle est signalée pour vérification manuelle et n’est jamais réécrite. Il en va de même pour les commentaires HTML et le code intégré.

L’application des changements est refusée tant qu’il reste des balises inconnues, ambiguës ou dynamiques :

Text
Error: Unresolved tags remain; no files were written. Review a dry-run report or pass --allow-unresolved.

La commande se termine avec 2. Corrigez la balise inconnue, ici en la supprimant, puis relancez avec --apply au lieu de --dry-run :

Text
Applied: 2 files, 2 changed, 5 replacements, 0 unknown, 0 ambiguous, 1 manual.

Seuls les noms des balises changent. Les attributs sont préservés octet par octet :

HTML
<bs:acme-section heading="Why Acme">
  <bs:acme-ui-button label="Talk to us" href="/contact" />
</bs:acme-section>

Une nouvelle exécution à blanc sur le résultat indique 0 changed, 0 replacements. Vous pouvez ensuite garder les préfixes enregistrés afin que les branches utilisant encore la forme courte continuent de fonctionner.

Étapes suivantes