Pages et compositions
Blockstudio vous permet de définir des pages WordPress, des compositions de blocs et des modèles de l’Éditeur de site sous forme de fichiers dans votre thème. Écrivez des modèles de type HTML et l’analyseur de Blockstudio les convertit en blocs natifs WordPress.
- Pages sont synchronisées avec la base de données en tant qu’articles WordPress, afin de garder les modèles de fichiers et le contenu des pages synchronisés.
- Compositions sont enregistrées en mémoire via
register_block_pattern()et disponibles dans l’outil d’insertion de blocs pour que les utilisateurs les placent où ils le souhaitent. - Modèles de site fournissent des sources
wp_templateetwp_template_partbasées sur des fichiers pour l’Éditeur de site WordPress.
Les trois fonctionnalités partagent le même analyseur HTML et la même syntaxe de blocs.
Créer des pages à partir de fichiers
Un guide pratique des modèles de pages basés sur des fichiers, de la synchronisation et du verrouillage.
Structure des dossiers
theme/
├── pages/
│ ├── about/
│ │ ├── page.json
│ │ └── index.php
│ └── contact/
│ ├── page.json
│ └── index.twig
├── patterns/
├── hero/
│ ├── pattern.json
│ └── index.php
└── cta/
├── pattern.json
└── index.blade.php
├── templates/
└── front-page/
├── template.json
└── index.php
└── parts/
└── header/
├── part.json
└── index.php
Chaque sous-dossier contient un fichier de configuration JSON (page.json, pattern.json, template.json ou part.json) et un fichier de modèle.
Moteurs de modèles
Les modèles peuvent être écrits en balisage brut dans index.php, ou avec Twig ou Blade :
| Fichier | Moteur | Prérequis |
|---|---|---|
index.php |
Aucun (lu tel quel, le code PHP n’est pas exécuté) | Aucun |
index.twig |
Twig | Timber |
index.blade.php |
Blade | illuminate/view |
Si plusieurs fichiers de modèle existent, l’ordre de priorité est : index.php > index.blade.php > index.twig.
Comme les modèles sont compilés à l’initialisation (avant tout contexte de requête), les modèles Twig et Blade n’ont pas accès aux variables dynamiques. Ils sont utiles pour les fonctions et filtres intégrés comme {{ "text"|upper }} ou {{ strtoupper("text") }}.
Correspondance entre HTML et les blocs
Les éléments HTML standard sont automatiquement convertis en blocs WordPress correspondants.
Texte
| HTML | Bloc |
|---|---|
<p> |
core/paragraph |
<h1> – <h6> |
core/heading |
<ul> |
core/list (non ordonnée) |
<ol> |
core/list (ordonnée) |
<li> |
core/list-item |
<blockquote> |
core/quote |
<code> |
core/code |
<pre> |
core/preformatted |
Les listes conservent leur structure. Un <ul> ou un <ol> dans un <li> devient un bloc interne core/list de ce core/list-item, comme dans la structure enregistrée par l’éditeur ; les listes peuvent donc être imbriquées à n’importe quelle profondeur. Un class sur une liste ou un élément devient son className, ce qui permet de définir un style de bloc tel que is-style-checks depuis un fichier de page ; <block name="core/list" className="..."> fait de même.
Médias
| HTML | Bloc |
|---|---|
<img> |
core/image |
<figure> |
core/image (avec légende) |
<audio> |
core/audio |
<video> |
core/video |
Mise en page
| HTML | Bloc |
|---|---|
<div>, <section> |
core/group |
<main>, <header>, <footer>, <article>, <aside> |
core/group qui conserve l’élément comme son tagName |
<hr> |
core/separator |
<details> |
core/details |
<table> |
core/table |
Syntaxe des blocs
Pour les blocs sans équivalent direct en HTML, utilisez l’élément <block> :
<block name="core/cover" url="https://example.com/hero.jpg">
<h1>Welcome</h1>
<p>Content inside the cover block.</p>
</block>
Blocs principaux
<!-- Pullquote -->
<block name="core/pullquote">
<p>An important quote.</p>
</block>
<!-- Verse -->
<block name="core/verse">Roses are red,
Violets are blue.</block>
<!-- Cover -->
<block name="core/cover" url="https://example.com/image.jpg">
<h2>Cover Title</h2>
</block>
<!-- Embed -->
<block name="core/embed" url="https://youtube.com/watch?v=..." providerNameSlug="youtube" />
<!-- Spacer -->
<block name="core/spacer" height="50px" />
<!-- Gallery -->
<block name="core/gallery">
<img src="https://example.com/1.jpg" alt="Image 1" />
<img src="https://example.com/2.jpg" alt="Image 2" />
</block>
<!-- Columns -->
<block name="core/columns">
<block name="core/column">
<h3>Column 1</h3>
</block>
<block name="core/column">
<h3>Column 2</h3>
</block>
</block>
<!-- Buttons -->
<block name="core/buttons">
<block name="core/button" url="/get-started">Get Started</block>
</block>
<!-- Row (flex layout) -->
<block name="core/group" layout='{"type":"flex","flexWrap":"nowrap"}'>
<p>Item 1</p>
<p>Item 2</p>
</block>
Blocs personnalisés
La même syntaxe fonctionne avec tous les blocs enregistrés :
<block name="blockstudio/section">
<h1>Welcome</h1>
</block>
<block name="acf/hero" title="Hero Title" background="dark">
<p>Inner content becomes InnerBlocks.</p>
</block>
Attributs
Les attributs HTML des éléments <block> sont transmis comme attributs de bloc. Les valeurs JSON sont prises en charge :
<block name="core/heading" level="3">Custom Heading</block>
<block name="core/group" layout='{"type":"flex","orientation":"vertical"}'>
<p>Stacked content.</p>
</block>
<img src="https://example.com/photo.jpg" alt="Photo" width="800" height="400" />
Les valeurs d’attribut sont décodées une fois, comme le ferait un navigateur, de sorte que data-animate="[&>span]:fade" et data-animate="[&>span]:fade" enregistrent la même valeur.
Sur un élément associé à un bloc Blockstudio, chaque attribut est stocké avec le bloc. Les champs déclarés sont transmis au modèle ; les attributs globaux non déclarés par le bloc (id, style, role, title, lang, dir, hidden, tabindex, aria-* et data-*) sont placés sur l’élément racine du bloc lors de son rendu, exactement comme sur les balises de bloc block tags. Dans les sources de pages et de compositions, un préfixe html- désigne uniquement l’un de ces attributs globaux. Ainsi, html-role="note" est transmis sous la forme role, tandis que les gestionnaires d’événements tels que html-onclick ne sont jamais rendus. Tout le reste, y compris un class non déclaré, reste dans le contenu de la publication sans parvenir à la page, et wp bs pages sync le signale pour chaque page analysée.
Rendus de blocs personnalisés
L’analyseur HTML repose sur une architecture fondée sur un registre. Ajoutez un générateur pour un bloc personnalisé avec blockstudio/block_tags/builders :
add_filter( 'blockstudio/block_tags/builders', function( $builders, $parser ) {
$builders['acf/hero'] = function( array $attrs, string $inner_content ) {
$inner_blocks = Blockstudio\Block_Tags::parse_inner_blocks( $inner_content );
return array(
'blockName' => 'acf/hero',
'attrs' => $attrs,
'innerBlocks' => $inner_blocks,
'innerHTML' => '',
'innerContent' => array_fill( 0, count( $inner_blocks ), null ),
);
};
return $builders;
}, 10, 2 );
Utilisez-le ensuite dans n’importe quel modèle :
<block name="acf/hero" background="dark">
<h1>Welcome</h1>
</block>
Vous pouvez également remplacer le rendu des blocs principaux :
add_filter( 'blockstudio/parser/renderers', function( $renderers, $parser ) {
$renderers['core/paragraph'] = function( array $attrs, string $inner_content ) {
$content = trim( $inner_content );
$attrs['align'] = $attrs['align'] ?? 'center';
return array(
'blockName' => 'core/paragraph',
'attrs' => $attrs,
'innerBlocks' => array(),
'innerHTML' => '<p class="has-text-align-center">' . $content . '</p>',
'innerContent' => array( '<p class="has-text-align-center">' . $content . '</p>' ),
);
};
return $renderers;
}, 10, 2 );
Les fonctions de rappel du générateur reçoivent les attributs analysés et le contenu interne brut. Elles doivent renvoyer un tableau de blocs WordPress. Consultez Rendus personnalisés pour connaître l’ordre complet des filtres et voir un exemple de conteneur.
Signature de la fonction génératrice
/**
* @param array $attrs Parsed element or block-tag attributes.
* @param string $inner_content Raw inner content.
* @return array WordPress block array.
*/
function my_builder( array $attrs, string $inner_content ): array {}
Correspondance des éléments
Par défaut, les éléments HTML standard tels que <h1>, <p> et <img> correspondent aux blocs principaux WordPress. Vous pouvez remplacer cette correspondance pour associer n’importe quel élément HTML à un autre bloc à l’aide du filtre blockstudio/parser/element_mapping :
add_filter( 'blockstudio/parser/element_mapping', function( $mapping ) {
$mapping['h1'] = 'custom/heading';
$mapping['h2'] = 'custom/heading';
$mapping['p'] = 'custom/paragraph';
$mapping['img'] = 'custom/image';
return $mapping;
}, 10, 2 );
Lorsque ce filtre est actif, chaque <h1> de vos modèles produit un bloc custom/heading au lieu de core/heading. Les attributs de l’élément sont transmis au bloc cible. Si un moteur de rendu est enregistré pour le nom du bloc cible, il sera utilisé. Sinon, une structure de bloc générique est créée.
Cette option est utile lorsque votre thème ou extension fournit des types de blocs personnalisés destinés à remplacer les valeurs par défaut dans tous les modèles de pages et de compositions.
Pour les correspondances <p> simples, Blockstudio peut transmettre directement le contenu HTML interne à l’attribut richtext content d’un bloc Blockstudio non principal enregistré. Le bloc cible doit déclarer un attribut avec id: "content" et type: "richtext".
La mise en forme en ligne (a, b, br, code, del, em, i, img, ins, mark, s, small, span, strong, sub, sup, u) reste dans la valeur transmise, même si la même balise est associée à un élément, comme code et img par défaut. Un paragraphe dont l’unique enfant est une image devient le bloc auquel <img> associe les images, comme celui que Markdown produit pour une image autonome. Les balises de blocs imbriquées et les éléments HTML de niveau bloc continuent d’être analysés comme des blocs internes.
Les valeurs de correspondance peuvent aussi être des fonctions lorsque le bloc cible dépend des attributs de l’élément :
add_filter( 'blockstudio/parser/element_mapping', function( $mapping ) {
$mapping['div'] = function( array $attrs ) {
if ( isset( $attrs['width'] ) ) {
return 'theme/row';
}
if ( isset( $attrs['gap'] ) ) {
return 'theme/flow';
}
return 'theme/div';
};
return $mapping;
} );
Les blocs personnalisés associés à des éléments conteneurs tels que <section> et <div> analysent récursivement les enfants HTML imbriqués ; les titres, images, balises de bloc et paragraphes internes deviennent ainsi des blocs enfants natifs.
Exemple complet
Un modèle de page complet combinant plusieurs types de blocs :
<div>
<h1>Welcome to Our Site</h1>
<p>This is an <strong>introduction</strong> with <em>formatting</em>.</p>
<block name="core/columns">
<block name="core/column">
<h3>Feature One</h3>
<p>First feature description.</p>
</block>
<block name="core/column">
<h3>Feature Two</h3>
<p>Second feature description.</p>
</block>
</block>
<block name="core/cover" url="https://example.com/hero.jpg">
<h2>Our Mission</h2>
<p>Building amazing things together.</p>
</block>
<details>
<summary>FAQ</summary>
<p>Answers to common questions.</p>
</details>
<block name="core/buttons">
<block name="core/button" url="/contact">Contact Us</block>
<block name="core/button" url="/learn-more">Learn More</block>
</block>
</div>