Rendu programmatique
Comme Gutenberg est devenu un outil essentiel pour créer des sites web facilement modifiables par les clients, il est logique de créer toutes les zones nécessaires du site sous forme de blocs. Cette approche répond à la plupart des besoins, mais les utilisateurs avancés et certains cas d’usage peuvent nécessiter l’utilisation de ces blocs existants en dehors de l’éditeur.
Blockstudio propose deux méthodes pour effectuer le rendu de blocs par programmation :
- Fonctions PHP :
bs_render_blocketbs_blockpour effectuer le rendu depuis du code PHP - Balises HTML : balises
<bs:block-name>remplacées par le contenu des blocs, où qu’elles se trouvent sur la page
Toutes les fonctionnalités propres à Blockstudio, comme les styles en ligne, les scripts et les styles délimités, sont prises en charge.
Les îlots fonctionnent aussi avec ces méthodes de rendu. Un îlot dynamique affiché avec bs_render_block(), bs_block() ou une balise de bloc renvoie le même marqueur d’espace réservé qu’un bloc rendu depuis le contenu d’une publication. L’environnement d’exécution frontend est injecté lorsque ce marqueur est présent dans la réponse.
Compositions structurées et documents complets
Pour les outils, les aperçus, les exportations et les galeries de composants conçus pour durer, utilisez l’Blockstudio\Render API versionné. Il accepte une déclaration ou une liste ordonnée et effectue le rendu sans afficher le résultat avec echo :
use Blockstudio\Render;
$composition = [
'root' => 'theme/card',
'example' => [
'data' => [
'heading' => 'Example card',
],
'layers' => [
[
'name' => 'theme/button',
'data' => [
'label' => 'Continue',
],
],
],
],
];
$normalized = Render::normalize($composition);
$html = Render::composition($composition);
$document = Render::document($composition, [
'title' => 'Component preview',
'contentElement' => 'main',
'contentClasses' => ['component-preview'],
]);
La déclaration canonique normalisée comporte quatre clés :
[
'name' => 'theme/card',
'attributes' => [],
'content' => '',
'children' => [],
]
data, inner, innerBlocks, root, layers et example sont des raccourcis de saisie supprimés lors de la normalisation. Les déclarations imbriquées sont rendues récursivement par le même pipeline Blockstudio.
Render::document() renvoie schemaVersion, html, body, blocks,
assets, warnings et errors. La valeur assets distingue head,
footer, styles, scripts, modules, interactivity, ui et tailwind.
La liste de blocs et les ressources incluent les dépendances référencées par les modèles sélectionnés,
mais excluent les ressources sans rapport et celles réservées à l’éditeur.
Les documents complets peuvent définir bodyClasses/bodyAttributes et éventuellement envelopper
le corps rendu avec contentElement, contentClasses et
contentAttributes. L’enveloppe est limitée à un nom d’élément sûr ; la valeur body renvoyée
reste le contenu rendu sans enveloppe.
Les options head et footer ajoutent du balisage de document fiable à leurs
emplacements respectifs et sont incluses dans la fermeture des ressources renvoyées.
Pour assembler un document autour de HTML déjà rendu, indiquez les noms de ses blocs racine connus :
$document = Render::document_from_html(
$rendered_html,
['theme/hero', 'theme/button'],
['title' => 'Homepage preview']
);
Utilisez Render::content() pour le contenu de bloc WordPress sérialisé. Les consommateurs qui rendent plusieurs documents indépendants dans une même requête doivent appeler Blockstudio\Batch_Render::reset() entre chaque document ; Canvas::documents() le fait automatiquement.
Rendu en dehors de la page
Blockstudio place un commentaire <!--blockstudio/namespace/slug--> avant chaque bloc qu’il rend. Sur une page publique, le tampon lit ces commentaires pour repérer les blocs présents, charger leurs ressources et supprimer les commentaires avant l’envoi de la réponse.
La sortie qui ne passe pas par ce tampon conserve les commentaires. Cela concerne les réponses REST, les flux, les gestionnaires AJAX et les HTML que vous stockez ou envoyez ailleurs après do_blocks(), Render::content() ou bs_render_block(). Utilisez
bs_strip_render_markers() pour les supprimer :
$html = bs_strip_render_markers(do_blocks($post->post_content));
La fonction supprime les commentaires des blocs Blockstudio enregistrés et laisse tout le reste intact, y compris les autres commentaires HTML. Elle repère les mêmes marqueurs que ceux supprimés par le tampon de page. Appelez-la après l’enregistrement des blocs (init ou plus tard).
Ne supprimez pas le balisage qui est encore affiché dans une page publique tamponnée. La page a besoin des commentaires pour savoir quelles ressources de blocs charger, et Blockstudio les supprime lui-même à la fin.
La suppression des commentaires n’ajoute pas de ressources. Les fichiers de bloc CSS et JavaScript sont injectés uniquement par le tampon de page. Utilisez ressourcesbs_block_assets() ou Render::document() si le consommateur en a également besoin.
Inspection des blocs
Utilisez bs_block_fields() après l’enregistrement des blocs (sur init ou plus tard) pour obtenir les définitions de champs résolues sans lire les registres internes :
$fields = bs_block_fields('theme/card');
if ($fields === null) {
// Unknown block, or not a Blockstudio block.
}
La valeur renvoyée est le tableau de définitions de champs enregistré, avec les filtres d’attributs, les champs personnalisés développés, les remplacements et les groupes, onglets et répéteurs imbriqués. Un bloc Blockstudio sans champ renvoie []. Le résultat est une copie : le modifier ne change pas le bloc enregistré.
Il s’agit de définitions, et non de valeurs enregistrées. Pour valider le balisage enregistré, utilisez bs_validate_block() au lieu de maintenir un parcours distinct des champs. Pour décrire les valeurs qu’un bloc accepte, utilisez bs_block_schema(). Les attributs gérés par WordPress restent distincts.
Les champs ajoutés par les extensions ne font pas partie de bs_block_fields(). Utilisez bs_block_extension_fields() pour les obtenir. La fonction associe les extensions au nom du bloc ; elle fonctionne donc aussi pour les blocs natifs et tiers :
$fields = array_merge(
bs_block_fields('core/paragraph') ?? [],
bs_block_extension_fields('core/paragraph')
);
La valeur renvoyée répertorie les définitions de champs de chaque extension correspondante, dans l’ordre d’enregistrement des extensions, avec la même structure que bs_block_fields(). Si aucune extension ne correspond à un bloc, la fonction renvoie []. Les valeurs des extensions sont enregistrées dans le même objet attrs.blockstudio.attributes que les valeurs de champs propres au bloc ; tous les identifiants partagent donc le même espace de noms. Si deux extensions définissent le même identifiant, les deux définitions sont renvoyées et modifient la même valeur ; au rendu, la définition de l’extension enregistrée en dernier s’applique.
Pour lire les valeurs d’un bloc enregistré telles qu’elles sont reçues par son modèle, utilisez valeurs du blocbs_block_values().
Utilisez bs_block_assets() pour inspecter les CSS et JavaScript découverts par le bloc. Pour obtenir un document d’aperçu complet, avec les blocs imbriqués et les dépendances d’exécution partagées, utilisez Render::document() comme indiqué plus haut.
Validation des valeurs enregistrées
Utilisez bs_validate_block() après l’enregistrement des blocs (init ou plus tard) pour vérifier les attributs de blocs générés par programmation ou importés avant de les enregistrer :
$block = parse_blocks($content)[0];
$findings = bs_validate_block($block['blockName'], $block['attrs']);
if ($findings === null) {
// No Blockstudio fields or matching extensions apply.
} elseif ($findings === []) {
// No stored-value problems were found.
} else {
// Review the findings before saving.
}
Transmettez le tableau attrs complet, et pas seulement blockstudio.attributes. Un rendu Blockstudio accepte également les champs déclarés au niveau supérieur, et les valeurs imbriquées sont prioritaires lorsque les deux sont fournies. Les extensions des blocs natifs et tiers ne lisent que blockstudio.attributes. Un bloc Blockstudio vide est géré et renvoie [], et non null.
La validation est explicite et en lecture seule. Elle ne rend pas les modèles, ne modifie pas les valeurs, n’enregistre pas les articles, n’interroge pas les médias et n’exécute pas les rappels de remplissage. Elle ne s’exécute pas automatiquement lors des enregistrements, de la synchronisation des pages ou du rendu. Ce n’est ni un assainisseur, ni un contrôle d’autorisation, ni une vérification de l’existence d’une pièce jointe.
Chaque constat contient les clés stables suivantes :
[
'code' => 'unknown_option',
'path' => 'steps/1/style',
'source' => 'block',
'message' => 'This value is not among the field options.',
'value' => 'c',
'expected' => ['a', 'b'],
]
Utilisez code, et non le message traduit, dans les outils. source est block ou
extension. Les chemins utilisent des clés de stockage et des indices de ligne de répéteur ou de sélection commençant à zéro, sans barre oblique initiale. Les caractères littéraux ~ et / dans une clé sont échappés en ~0 et
~1. Un groupe de premier niveau préfixe ses enfants (cta_title) ; les groupes anonymes
et les onglets n’ajoutent aucun niveau. Le constructeur ne prend pas en charge les groupes avec un ID imbriqués dans un autre groupe ou un répéteur ; leurs clés ne sont donc pas acceptées. Les champs de message n’ont aucune valeur stockée. Un champ de fichiers autorise son compagnon <id>__size.
À la racine d’un bloc Blockstudio, les clés de suivi et les attributs globaux HTML transmis à l’élément rendu ne sont pas des champs inconnus. Cela n’autorise pas les clés arbitraires dans les lignes de répéteur ni les extensions des blocs principaux.
| Code | Signification | expected |
|---|---|---|
unknown_field |
Aucun champ conservé ne déclare cette clé de stockage. | Clés de stockage connues. |
unknown_option |
Une sélection ne figure pas parmi les options connues. | Valeurs d’option autorisées. |
wrong_type |
La structure stockée n’est pas prise en charge par le champ. | Famille ou type de stockage attendu. |
too_few_rows, too_many_rows |
Un répéteur présent est en dehors de sa min ou de sa max. |
Limite du nombre de lignes. |
definition_conflict |
Les définitions applicables à une clé requièrent des structures de stockage différentes. | Source et type de champ de chaque définition. |
shadowed_value |
Une valeur imbriquée remplace une valeur de champ différente au niveau supérieur. | Valeur imbriquée prioritaire. |
extension_top_level |
Le modèle peut lire une valeur de premier niveau, mais pas les liaisons d’extension. | Chemin requis sous blockstudio/attributes. |
unknown_attribute |
Une clé de premier niveau d’un bloc Blockstudio n’est pas lue par le chemin de rendu et est ignorée. | Noms d’attributs enregistrés, champs d’extension et blockstudio. |
missing_container |
attributes, disabled, name ou editor est stocké au niveau supérieur et blockstudio est manquant. |
Chemin requis sous blockstudio. |
invalid_container |
blockstudio ou blockstudio.attributes n’est pas un objet. |
object. |
Le message d’une détection unknown_field indique la clé de stockage la plus proche au même niveau si elle se trouve à trois modifications près, comme le fait la règle « unknown settings use » :
This storage key is not declared by the block or its extensions. Did you mean "title"?
expected répertorie toujours toutes les clés connues.
La comparaison ne tient pas compte de la casse et porte uniquement sur les clés de stockage de ce conteneur. Les messages sont traduits ; les intégrations doivent utiliser code, path et expected plutôt que d’analyser le texte du message.
Une clé de premier niveau d’un bloc Blockstudio qui n’est ni un attribut enregistré
(ses champs, les attributs que WordPress ajoute pour supports, lock et
metadata), ni un champ d’une extension correspondante, ni blockstudio, ni une
clé de suivi ou un attribut HTML transmis est ignorée avant l’exécution du modèle.
Une telle clé, par exemple un ID de champ mal orthographié ou un objet de valeurs stocké
sans son enveloppe blockstudio, génère un constat, car le bloc
est rendu sans cette valeur. Les blocs qui ne contiennent que des champs d’extension ne sont pas
vérifiés pour les clés de premier niveau.
Les structures acceptées correspondent au rendu : les sélections multiples et les cases à cocher peuvent
contenir une liste, un objet d’option ou une valeur scalaire importée, y compris zéro numérique. Les chaînes numériques sont acceptées pour les nombres. Les champs de fichiers peuvent contenir des ID de pièces jointes, des objets ID, des listes ou des références sous forme de chaîne. Les valeurs de lien et d’icône doivent être des objets ; les types de champ personnalisés utilisent le type d’attribut enregistré.
Un champ attributes contient une liste de paires avec un nom attribute non vide
et une valeur scalaire value ; les métadonnées facultatives telles que data.media sont conservées.
WordPress valide les attributs de premier niveau enregistrés avant le rendu, ce qui
peut rejeter une structure acceptée dans blockstudio.attributes. Par exemple, une
valeur radio "a" fonctionne dans l’objet imbriqué, mais est ignorée au niveau supérieur,
où son type enregistré est object. Une telle valeur génère wrong_type.
Utilisez l’objet imbriqué pour reprendre la même structure de stockage que celle écrite par l’éditeur.
Les champs manquants ne sont pas obligatoires. Les valeurs imbriquées vides (null, false, '',
[]) et les champs désactivés ne génèrent pas d’erreurs de valeur. Un répéteur explicitement vide est tout de même vérifié par rapport à min ; un répéteur absent ou désactivé ne l’est pas.
Une valeur vide de premier niveau est signalée si WordPress l’ignore et rétablit une
valeur par défaut non vide. La même valeur dans l’objet imbriqué peut l’effacer.
Les conflits de définition sont signalés même si la clé n’a aucune valeur enregistrée.
Les options statiques et les options de remplissage déjà résolues lors de l’enregistrement
sont vérifiées sans rappeler le remplissage. Les options fetch distantes et les arguments de remplissage contenant {attributes.*} sont ignorés. Les valeurs de couleur et de dégradé
peuvent être personnalisées, sauf si disableCustomColors ou disableCustomGradients est défini.
Cette vérification porte sur les valeurs stockées, et non sur default, fallback ou les règles de validation de l’éditeur.
Les champs d’extension correspondants sont inclus pour chaque bloc qu’ils ciblent. Les définitions ultérieures l’emportent au sein du bloc ou de ses extensions à la racine, comme lors du rendu.
Le champ propre à un bloc et un champ d’extension restent des définitions distinctes de la même clé et s’appliquent tous deux. Dans les lignes de répéteur, le rendu lit le premier champ ayant un ID correspondant dans chaque source ; ses options et limites s’appliquent donc. Les définitions en double sont conservées pour diagnostiquer les conflits :
des structures de stockage incompatibles génèrent definition_conflict, même si un doublon ultérieur n’est pas lu lors du rendu.
La fonction vérifie un seul bloc. Parcourez innerBlocks pour valider un document ;
les compositions synchronisées et autres références ne sont pas développées automatiquement. La commande
wp bs blocks validate parcourt
les blocs d’un ou de plusieurs articles et signale leurs chemins de bloc.
Les sites dotés d’un résolveur personnalisé à l’exécution du rendu peuvent adapter les constats sans modifier les données stockées :
add_filter('blockstudio/blocks/attributes/validate', function($findings, $name, $attrs) {
if ($name !== 'my-theme/card') {
return $findings;
}
return array_values(array_filter($findings, function($finding) {
return !($finding['path'] === 'customReference' && $finding['code'] === 'wrong_type');
}));
}, 10, 3);
Renvoyez toujours une liste de constats ; renvoyer [] valide le bloc. Ce
filtre s’exécute uniquement pour les blocs gérés, jamais pour le résultat null.
Décrire les valeurs enregistrées
Utilisez bs_block_schema() après l’enregistrement du bloc (init ou une version ultérieure) pour décrire les valeurs qu’un bloc enregistre, par exemple pour générer le balisage du bloc dans un outil ou une intégration d’IA, ou pour vérifier une entrée dans une route REST :
$schema = bs_block_schema('theme/card');
if ($schema === null) {
// No Blockstudio fields or matching extensions apply.
}
Le résultat est un schéma JSON de l’objet enregistré dans attrs.blockstudio.attributes. Il couvre les champs du bloc et ceux des extensions correspondantes, avec les clés de stockage utilisées par la validation : un groupe de premier niveau préfixe ses enfants, les groupes anonymes et les onglets n’ajoutent aucun niveau, et un champ de fichier ajoute son champ associé <id>__size. Les répéteurs sont des listes d’objets ligne contenant minItems et maxItems issus de min et max. additionalProperties est false à la racine du stockage des champs et dans les lignes des répéteurs. Les champs dont la valeur est un objet, comme les liens et les objets personnalisés, peuvent avoir leurs propres métadonnées. Un bloc sans champ n’a pas de properties ; seul un objet vide correspond donc.
Chaque champ est décrit dans une forme canonique acceptée par bs_validate_block() :
| Champ | Schéma |
|---|---|
text, textarea, richtext, wysiwyg, code, date, datetime, unit, classes, html-tag, block |
Une chaîne. |
number, range |
Un nombre, avec minimum et maximum provenant de min et max. |
toggle |
Un booléen. |
select, radio, checkbox |
Une valeur d’option, ou une liste de valeurs d’option pour checkbox et multiple, avec enum. |
color, gradient |
Une chaîne, avec enum si disableCustomColors ou disableCustomGradients est défini. |
token |
Une liste de chaînes. |
files |
Un ID de pièce jointe entier non négatif, ou une liste d’ID avec multiple. |
link |
Un objet avec url, title et opensInNewTab ; url est obligatoire. |
icon |
Un objet avec set, subSet et icon ; set et icon sont obligatoires. |
attributes |
Une liste d’objets avec un attribute non vide et un value scalaire. |
repeater |
Une liste d’objets ligne. |
| Types de champs personnalisés | Leur type d’attribut enregistré. |
enum répertorie les options vérifiées par la validation : les options statiques et les options de remplissage déjà résolues lors de l’enregistrement. Les options distantes fetch et les arguments de remplissage contenant {attributes.*} n’ont pas de enum. Une clé associée à des définitions ayant des formes de stockage différentes est omise, car la validation signale chaque valeur enregistrée sous cette clé. Lorsqu’un champ de bloc et un champ d’extension partagent une clé, enum répertorie les valeurs acceptées par les deux. Les répéteurs partagés combinent leurs champs enfants et appliquent les limites de lignes les plus strictes des deux définitions. Dans les lignes des répéteurs, le premier champ portant un ID correspondant dans chaque source s’applique, comme lors du rendu. Un champ explicite nommé <id>__size est prioritaire sur un champ associé à la taille du fichier ajouté automatiquement.
Lorsqu’un champ fermé n’a aucun choix disponible, ou que deux ensembles d’options applicables n’ont aucun élément en commun, sa valeur canonique est null pour une sélection unique ou une liste vide pour plusieurs sélections. Une liste d’options vide ne rend pas le champ sans restriction. Les choix distants et ceux qui dépendent des attributs restent ouverts.
Le label d’un champ devient title, son help devient description, et son default est conservé comme annotation. Le title propre au schéma correspond au titre du bloc. Les champs ne sont jamais obligatoires, et la logique conditionnelle ne fait pas partie du schéma.
Les contraintes n’utilisent que des mots-clés vérifiés par rest_validate_value_from_schema(), de sorte que le schéma peut servir tel quel de schéma d’entrée pour une route REST ou une capacité :
$values = $block['attrs']['blockstudio']['attributes'] ?? [];
$schema = bs_block_schema($block['blockName']);
if ($schema !== null) {
$result = rest_validate_value_from_schema($values, $schema);
}
Le schéma décrit un formulaire par champ ; la validation accepte également des formes importées, comme des objets d’options, des chaînes numériques et des objets ID. Il ne remplace pas bs_validate_block() : les conflits de définition sont des problèmes de configuration et peuvent toujours générer des résultats, même si la clé en conflit est omise. Les filtres de validation peuvent également imposer des règles propres au site. Utilisez bs_validate_block() pour vérifier le contenu enregistré. Les sites dotés d’un résolveur personnalisé à l’exécution du rendu peuvent adapter le schéma avec le filtre blockstudio/blocks/attributes/schema.
Fonctions PHP
Sans données
Dans sa forme la plus simple, la fonction accepte une seule valeur : l’ID du bloc à afficher sur la page.
bs_render_block('blockstudio/cta');
Avec des données
Pour afficher le bloc avec des données personnalisées, remplacez la valeur unique du premier paramètre par un tableau. La valeur de la clé data sera transmise aux variables $attributes et $a dans le modèle de votre bloc.
bs_render_block([
'id' => 'blockstudio/cta',
'data' => [
'title' => 'My title',
'subtitle' => 'My subtitle',
],
]);
Imbrication
Les blocs peuvent être imbriqués les uns dans les autres en utilisant la fonction bs_block avec la puissante variable $content dans les modèles de vos blocs.
<div>
<h1><?php echo $a['title']; ?></h1>
<p><?php echo $a['subtitle']; ?></p>
<?php echo $content; ?>
</div>
echo bs_block([
'id' => 'blockstudio/cta',
'data' => [
'title' => 'My title',
'subtitle' => 'My subtitle',
],
'content' => bs_block([
'id' => 'blockstudio/button',
'data' => [
'text' => 'Button Text',
]
])
]);
Le bloc bouton sera rendu à la place de la variable $content dans le modèle du bloc.
Les blocs intégrés rendus avec bs_render_block() ou bs_block() produisent toujours un HTML résolu côté frontal, même lorsque le bloc parent affiche actuellement un aperçu dans l’éditeur. Les pseudo-composants de modèle tels que <RichText /> et <InnerBlocks /> sont résolus avant le renvoi du bloc intégré.
Plusieurs emplacements
Il est également possible de créer plusieurs emplacements de contenu en faisant simplement de la variable $content un tableau associatif et en appelant les clés correspondantes dans la fonction bs_block.
<div>
<?php echo $content['beforeContent']; ?>
<h1><?php echo $a['title']; ?></h1>
<p><?php echo $a['subtitle']; ?></p>
<?php echo $content['afterContent']; ?>
</div>
echo bs_block([
'id' => 'blockstudio/cta',
'data' => [
'title' => 'My title',
'subtitle' => 'My subtitle',
],
'content' => [
'beforeContent' => bs_block([
'id' => 'blockstudio/badge',
'data' => ['text' => 'Before Content']
]),
'afterContent' => bs_block([
'id' => 'blockstudio/button',
'data' => ['text' => 'Button Text']
])
]
]);
Balises de bloc
Intégrez n’importe quel bloc avec la syntaxe de balise HTML. Deux formats sont pris en charge :
<bs:acme-hero title="Welcome" />
<block name="acme/hero" title="Welcome" />
Les deux affichent le même bloc. La syntaxe <bs:> transforme un trait d’union en séparateur d’espace de noms (acme-hero devient acme/hero). Les traits d’union sont testés de gauche à droite et le premier candidat enregistré est retenu ; les espaces de noms contenant des traits d’union sont donc également résolus : <bs:acme-ui-button> teste acme/ui-button, puis acme-ui/button. La syntaxe <block> prend le nom complet du bloc comme attribut name.
Les blocs Blockstudio et les blocs natifs WordPress fonctionnent. Les blocs Blockstudio sont rendus par le pipeline complet (modèles, Tailwind, ressources). Les blocs natifs utilisent le système de rendu des blocs de WordPress, avec les moteurs de rendu de blocs intégrés.
Fonctionnement
Les balises de bloc se comportent différemment selon l’endroit où elles apparaissent :
Dans les modèles de bloc et le contenu des articles, les balises sont remplacées à l’exécution par des blocs HTML rendus. Le résultat est le balisage final du bloc référencé, intégré directement à la page. Aucun bloc WordPress n’apparaît dans l’éditeur. Il s’agit uniquement d’un mécanisme de rendu.
Dans les Pages, motifs et modèles de site, les balises sont converties en blocs WordPress natifs avant la synchronisation du fichier source ou son enregistrement auprès de WordPress. Les blocs apparaissent ainsi dans l’éditeur, peuvent être modifiés lorsque la cible le permet et suivent tout le cycle de vie des blocs de WordPress. La syntaxe des balises est un raccourci permettant de définir le contenu des blocs dans les fichiers de modèle.
Cette distinction est importante : les balises de bloc dans les modèles génèrent du contenu ; dans les pages, les motifs et les modèles de site, elles produisent des blocs natifs.
Dans les modèles de bloc
Les balises de bloc sont automatiquement rendues dans les modèles Twig et PHP. Aucun réglage n’est nécessaire. Cela comprend les syntaxes <bs:> et <block>, ainsi que toutes les balises préfixées et les alias enregistrés : un modèle peut donc les produire directement au lieu d’appeler bs_render_block(). Le résultat est rendu HTML, directement intégré à la sortie du modèle du bloc :
<div class="my-page">
<bs:mytheme-card title="Featured" />
<block name="core/separator" />
<bs:core-paragraph>Rendered by WordPress</bs:core-paragraph>
<block name="core/heading" level="2">Also WordPress</block>
<theme-card title="Prefix shorthand" />
</div>
Dans le contenu des articles
Le rendu au niveau de la page (contenu des articles, zones de widgets) est facultatif :
{
"blockTags": {
"enabled": true
}
}
Ou via un filtre :
add_filter('blockstudio/settings/block_tags/enabled', '__return_true');
Syntaxe
Balises autonomes :
<bs:mytheme-cta title="Get started" variant="primary" />
<block name="core/separator" />
Balises appariées avec du contenu interne :
<bs:mytheme-section layout="wide">
<p>Content inside the block.</p>
</bs:mytheme-section>
<block name="core/group">
<block name="core/paragraph">Inside a group.</block>
</block>
Combinez-les librement. Les deux syntaxes peuvent être imbriquées :
<bs:mytheme-section>
<block name="core/heading" level="2">Title</block>
<bs:mytheme-card title="Features" />
<block name="core/paragraph">Description text.</block>
</bs:mytheme-section>
Raccourcis de préfixe
Les balises de bloc peuvent aussi utiliser des raccourcis de préfixe propres au projet. Enregistrez un préfixe avec un ou plusieurs espaces de noms ; Blockstudio résout alors <prefix-slug> vers le premier bloc enregistré dans cet ordre d’espaces de noms :
add_filter('blockstudio/block_tags/prefixes', function($prefixes) {
$prefixes['theme'] = ['theme-components', 'bsui'];
return $prefixes;
});
<theme-card title="Homepage" />
<theme-button label="Get started" />
<theme-ui-feature-matrix />
Avec l’exemple ci-dessus, <theme-card> est résolu en theme-components/card, <theme-button> se rabat sur bsui/button lorsque theme-components/button n’est pas enregistré, et <theme-ui-feature-matrix> est résolu en theme-components/ui-feature-matrix.
Les préfixes peuvent aussi se composer. Lorsqu’une balise préfixée n’est pas résolue directement et que le slug restant est lui-même une balise de préfixe enregistrée, la résolution se poursuit récursivement. Un préfixe de marque peut ainsi s’appuyer sur un préfixe d’espace de noms :
add_filter('blockstudio/block_tags/prefixes', function($prefixes) {
$prefixes['theme'] = ['theme-components'];
$prefixes['ui'] = ['bsui'];
return $prefixes;
});
<theme-ui-input />
<theme-ui-input> n’a pas de bloc theme-components/ui-input ; la résolution passe donc au préfixe ui et résout bsui/input. Les correspondances directes sont toujours prioritaires sur la résolution imbriquée, et les règles d’autorisation et de refus s’appliquent au bloc finalement résolu.
Vous pouvez également configurer des préfixes dans blockstudio.json :
{
"blockTags": {
"prefixes": {
"theme": ["theme-components", "bsui"]
}
}
}
Les préfixes doivent être composés de lettres minuscules ou de chiffres, commencer par une lettre et ne pas contenir de tirets. Les alias explicites de blockstudio/block_tags/tag_aliases sont prioritaires sur la résolution des préfixes. Les balises préfixées inconnues restent inchangées.
Les balises avec préfixe et les alias restent des raccourcis pratiques pour la rédaction. L’écriture canonique et portable est toujours <bs:namespace-slug>, car elle indique le véritable nom du bloc sans dépendre des filtres du projet :
<bs:theme-components-card />
<bs:bsui-input />
Les exemples Blockstudio, les diagnostics générés et la sortie programmatique utilisent cette écriture canonique. Les projets qui souhaitent supprimer une ancienne forme abrégée peuvent utiliser la migration autonome des balises canoniques, qui commence par une simulation, sans démarrer WordPress.
Blocs natifs
Tout bloc doté d’un moteur de rendu enregistré peut être utilisé :
<bs:core-paragraph>A paragraph</bs:core-paragraph>
<bs:core-heading level="2">A heading</bs:core-heading>
<bs:core-separator />
<bs:core-image url="photo.jpg" alt="Photo" />
<bs:core-buttons>
<bs:core-button url="/about">About</bs:core-button>
</bs:core-buttons>
Ou avec la syntaxe <block> :
<block name="core/group">
<block name="core/columns">
<block name="core/column">
<block name="core/paragraph">Left column</block>
</block>
<block name="core/column">
<block name="core/paragraph">Right column</block>
</block>
</block>
</block>
Listes d’autorisation et de refus
Contrôlez les blocs qui peuvent être rendus avec des balises :
{
"blockTags": {
"enabled": true,
"allow": ["mytheme/*", "core/*"],
"deny": ["mytheme/internal-*"]
}
}
allow limite le rendu aux motifs correspondants. deny exclut les motifs correspondants et est prioritaire. Les deux prennent en charge les caractères génériques * via fnmatch(). Ces règles s’appliquent aux deux syntaxes et au rendu dans les modèles comme au niveau des pages.
Filtres : blockstudio/block_tags/allow et blockstudio/block_tags/deny.
Transmission directe de HTML
Les attributs préfixés par data- sont transmis à l’élément racine du bloc rendu. Ceux préfixés par html- sont également transmis, avec suppression du préfixe. Cela fonctionne avec les deux syntaxes. Un attribut transmis remplace la valeur existante de l’élément racine au lieu de la fusionner ; ainsi, html-class remplace les classes propres au bloc.
Un bloc Blockstudio place également sur son élément racine les attributs globaux qu’il ne déclare pas comme champs : id, style, role, title, lang, dir, hidden, tabindex et tous les attributs aria-*. Un champ déclaré est toujours prioritaire : un bloc doté d’un champ title reçoit donc la valeur de $a['title']. Les styles transmis passent par safecss_filter_attr() ; le filtre WordPress s’applique aux attributs de style dans le contenu des articles, et ces styles sont ajoutés à celui déjà défini par le modèle.
Les valeurs d’attribut sont HTML : les entités sont donc décodées une fois lors de l’analyse d’une balise. title="Tom & Jerry" parvient au modèle sous la forme Tom & Jerry, puis est de nouveau échappé à la sortie. Les valeurs entre guillemets peuvent contenir >, comme les variantes Tailwind et les sélecteurs d’animation, aussi bien dans les balises autonomes que dans les balises appariées.
Tout autre attribut non déclaré par un bloc, y compris class, n’est jamais transmis au HTML. Lorsque WP_DEBUG est activé, Blockstudio signale chaque attribut de ce type une fois par requête via _doing_it_wrong(). Déclarez un champ pour cet attribut ou écrivez-le comme attribut data-, aria- ou html-.
<bs:mytheme-card
title="My Card"
html-class="featured-card"
html-id="main-card"
data-analytics="card-click"
/>
<block name="core/paragraph" html-class="highlight" data-section="intro">
Highlighted paragraph.
</block>
Moteurs de rendu personnalisés
Enregistrez des moteurs de rendu personnalisés pour d’autres types de blocs. Ils prennent un tableau d’attributs et une chaîne de contenu interne, et renvoient un tableau de blocs WordPress :
add_filter('blockstudio/block_tags/builders', function ($builders, $parser) {
$builders['myplugin/custom-block'] = function (array $attrs, string $inner_content) {
$html = '<div class="my-block">' . $inner_content . '</div>';
return [
'blockName' => 'myplugin/custom-block',
'attrs' => $attrs,
'innerBlocks' => [],
'innerHTML' => $html,
'innerContent' => [$html],
];
};
return $builders;
}, 10, 2);
Pour les blocs conteneurs qui doivent analyser le contenu interne en blocs enfants, ajoutez une deuxième entrée dans le même filtre :
$builders['myplugin/wrapper'] = function (array $attrs, string $inner_content) {
$inner_blocks = Blockstudio\Block_Tags::parse_inner_blocks($inner_content);
$content = ['<div class="my-wrapper">'];
foreach ($inner_blocks as $block) {
$content[] = null;
}
$content[] = '</div>';
return [
'blockName' => 'myplugin/wrapper',
'attrs' => $attrs,
'innerBlocks' => $inner_blocks,
'innerHTML' => '<div class="my-wrapper"></div>',
'innerContent' => $content,
];
};
blockstudio/block_tags/builders s’applique aux balises de bloc et aux blocs personnalisés sélectionnés via blockstudio/parser/element_mapping. C’est le hook approprié lorsqu’un bloc de projet associé à un élément doit transférer son texte interne dans un champ Blockstudio ou construire un tableau de blocs personnalisé.
blockstudio/block_tags/renderers et blockstudio/parser/renderers reçoivent le même registre et la même structure de callback. Ils restent disponibles pour assurer la compatibilité et effectuer des remplacements au dernier niveau de l’analyseur. Les filtres s’exécutent dans cet ordre :
blockstudio/block_tags/buildersblockstudio/block_tags/renderersblockstudio/parser/renderers
Un filtre ultérieur peut remplacer un moteur de rendu enregistré par un filtre précédent.
Utilisation programmatique
Appliquez le rendu des balises à n’importe quelle chaîne provenant de PHP :
$html = apply_filters('blockstudio/block_tags/render', $content);
Composants
Les balises de bloc se combinent bien avec les composants. Les composants sont des blocs rendus uniquement par programmation et qui n’apparaissent jamais dans l’éditeur.
<bs:mytheme-card title="My Card" description="Card content." />
Analyseur
Les balises de bloc sont traitées par un analyseur de chaînes léger qui remplace DOMDocument. Il gère les syntaxes <bs:> et <block>, les balises imbriquées de même nom grâce au suivi de profondeur, les valeurs d’attribut entre guillemets et les blocs conteneurs récursifs. Conçu spécifiquement pour ce cas d’utilisation, il est plus rapide que DOMDocument et WordPress de WP_HTML_Tag_Processor, et évite les problèmes connus de DOMDocument liés à la suppression des préfixes d’espace de noms et à la conversion des attributs en minuscules.
Pour les Pages, motifs et modèles de site, le même analyseur traite également les éléments HTML bruts (<p>, <div>, <h1>, etc.) et les associe aux blocs natifs WordPress correspondants.
Lorsqu’une association d’élément relie <p> à un bloc Blockstudio non natif enregistré qui déclare un attribut richtext content, le contenu HTML interne est automatiquement transmis à cet attribut content, y compris les balises en ligne telles que code et img associées à un niveau de bloc. Un paragraphe dont l’unique enfant est une image devient le bloc vers lequel <img> est associé. Les balises de bloc imbriquées ou les éléments HTML de niveau bloc continuent d’utiliser l’analyse normale des blocs internes. <block name="core/shortcode"> conserve son texte de shortcode comme contenu du bloc.