Créer des pages à partir de fichiers
La création traditionnelle de pages WordPress se fait dans l’éditeur de blocs : faire glisser des blocs, configurer des réglages, cliquer sur Enregistrer. Cela convient aux clients qui créent leurs propres pages, mais pose problème aux développeurs qui conçoivent des pages structurées et suivies dans le contrôle de version. La mise en page réside dans la base de données, pas dans le code. Impossible de la réviser dans une demande de fusion, de la restaurer avec git ou de la reproduire sur une nouvelle installation.
Les pages basées sur des fichiers de Blockstudio résolvent ce problème. Définissez les pages dans des fichiers de votre thème, écrivez des modèles HTML convertis en blocs WordPress et contrôlez précisément ce que les clients peuvent ou ne peuvent pas modifier. Une commande explicite synchronise ces fichiers avec des publications WordPress ordinaires, tandis que vos modèles restent la référence.
Ce guide explique comment créer des pages à partir de zéro et détaille les contrôles de verrouillage et de modification qui rendent les pages basées sur des fichiers adaptées aux projets clients.
Votre première page
Créez un dossier pages dans votre thème, puis ajoutez-y un sous-dossier contenant deux fichiers :
theme/
└── pages/
└── about/
├── page.json
└── index.php
{
"name": "about",
"title": "About Us",
"postStatus": "publish"
}
<h1>About Us</h1>
<p>We build things for the web.</p>
Exécutez la commande de synchronisation des pages :
wp bs pages sync
Blockstudio analyse HTML en blocs WordPress et crée une page intitulée « About Us », dont le slug est about. Ouvrez-la dans l’éditeur : vous verrez un titre et un paragraphe, exactement comme si vous les aviez ajoutés manuellement.
Modifiez index.php, changez le texte et relancez la commande. Actualisez l’éditeur pour voir la mise à jour. C’est le cycle de base : écrivez HTML, synchronisez à la demande, obtenez des blocs.
Le langage de modèle
L’analyseur HTML de Blockstudio convertit les éléments HTML standard en blocs WordPress. Écrivez un <p> pour obtenir un bloc de paragraphe. Écrivez un <h2> pour obtenir un bloc de titre. La correspondance est intuitive :
| HTML | Bloc |
|---|---|
<p> |
Paragraphe |
De <h1> à <h6> |
Titre (le niveau correspond à la balise) |
<ul>, <ol> |
Liste |
<blockquote> |
Citation |
<img> |
Image |
<div>, <section> |
Groupe |
<hr> |
Séparateur |
<details> |
Détails |
<table> |
Tableau |
Pour les blocs sans équivalent direct en HTML, utilisez l’élément <block> avec un attribut name :
<block name="core/cover" url="https://example.com/hero.jpg">
<h2>Hero Title</h2>
<p>Content over the background image.</p>
</block>
<block name="core/spacer" height="80px" />
<block name="core/buttons">
<block name="core/button" url="/contact">Get in Touch</block>
<block name="core/button" url="/work">See Our Work</block>
</block>
Les attributs des éléments <block> sont transmis comme attributs de bloc. Les valeurs sont converties automatiquement : "true" devient un booléen, "3" un entier, et les chaînes JSON telles que '{"type":"flex"}' sont décodées en objets.
Mises en page
Les groupes prennent en charge différents modes de mise en page grâce à l’attribut layout :
<!-- Default group (stacked) -->
<div>
<p>Stacked by default.</p>
</div>
<!-- Row (horizontal flex) -->
<block name="core/group" layout='{"type":"flex","flexWrap":"nowrap"}'>
<p>Side</p>
<p>by side</p>
</block>
<!-- Stack (vertical flex) -->
<block name="core/group" layout='{"type":"flex","orientation":"vertical"}'>
<p>Stacked</p>
<p>with flex</p>
</block>
<!-- Columns -->
<block name="core/columns">
<block name="core/column">
<p>Left column.</p>
</block>
<block name="core/column">
<p>Right column.</p>
</block>
</block>
Blocs personnalisés
La syntaxe <block> fonctionne avec tous les blocs enregistrés, y compris vos propres blocs Blockstudio :
<block name="my-theme/hero" title="Welcome" background="dark" />
<block name="my-theme/testimonial" quote="Great product." author="Jane" />
Les attributs sont automatiquement associés aux valeurs des champs Blockstudio du bloc.
Créer une page d’atterrissage
Voici une page d’atterrissage complète qui utilise les blocs principaux pour sa structure et sa mise en page :
{
"name": "landing",
"title": "Landing Page",
"slug": "landing",
"postStatus": "publish",
"templateLock": "all"
}
<block name="core/cover" url="https://images.unsplash.com/photo-1497366216548-37526070297c?w=1600">
<h1>Build faster with Blockstudio</h1>
<p>File-based blocks. Zero build step. Full editor integration.</p>
<block name="core/buttons">
<block name="core/button" url="/get-started">Get Started</block>
<block name="core/button" url="/docs">Documentation</block>
</block>
</block>
<div>
<h2>Why developers love it</h2>
<block name="core/columns">
<block name="core/column">
<h3>No build step</h3>
<p>Write PHP, CSS, and JavaScript. No webpack, no bundler, no transpiler.</p>
</block>
<block name="core/column">
<h3>File-based</h3>
<p>Every block is a folder. Every page is a template. Version control everything.</p>
</block>
<block name="core/column">
<h3>Full editor support</h3>
<p>Fields, previews, and InnerBlocks work in the block editor out of the box.</p>
</block>
</block>
</div>
<block name="core/media-text" mediaurl="https://images.unsplash.com/photo-1460925895917-afdab827c52f?w=800" mediatype="image">
<h2>Ship entire sites from your IDE</h2>
<p>Define pages, blocks, and patterns as files. Blockstudio handles the rest.</p>
</block>
<div>
<h2>Frequently asked questions</h2>
<details>
<summary>Do I need to learn React?</summary>
<p>No. Templates are PHP. Fields are JSON. Interactivity is optional.</p>
</details>
<details>
<summary>Does it work with my existing theme?</summary>
<p>Yes. Drop a blockstudio folder into any theme and start creating blocks.</p>
</details>
</div>
<div>
<block name="core/buttons">
<block name="core/button" url="/get-started">Start Building</block>
</block>
</div>
Cette page comprend une bannière principale de couverture, une grille de fonctionnalités à trois colonnes, une section média-texte, des accordéons FAQ et un appel à l’action. Le tout tient dans un seul fichier HTML. templateLock: "all" dans page.json signifie que le client ne peut rien modifier. La section suivante explique comment assouplir cette restriction.
Contrôler l’éditeur
C’est là que les pages basées sur des fichiers révèlent tout leur potentiel. Blockstudio vous offre deux commandes indépendantes : le verrouillage du modèle et le mode d’édition des blocs. Ensemble, elles vous permettent de définir précisément les parties d’une page que les clients peuvent modifier. Verrouillez la structure tout en leur permettant de modifier le texte. Figez certaines sections tout en laissant les autres entièrement accessibles. Créez une page où le client ne peut saisir du texte que dans trois titres précis.
Verrouillage du modèle
La propriété templateLock dans page.json contrôle la modification de la structure : elle détermine si les blocs peuvent être ajoutés, supprimés ou réorganisés.
"all" (par défaut)
{
"name": "terms",
"templateLock": "all"
}
Le verrouillage le plus strict. Les clients ne peuvent ni ajouter, ni supprimer, ni déplacer de blocs. Ils ne peuvent pas non plus modifier le contenu des blocs (sauf si cette option est associée à blockEditingMode). C’est le comportement par défaut si aucune valeur n’est précisée.
Quand l’utiliser : pour les pages juridiques, les conditions d’utilisation et les politiques de confidentialité. Pour toute page dont le contenu ne doit être modifié que par du code.
"insert"
{
"name": "about",
"templateLock": "insert"
}
Les clients ne peuvent ni ajouter ni supprimer de blocs, mais ils peuvent déplacer les blocs existants et modifier leur contenu. Le nombre de blocs reste fixe, mais leur ordre peut changer.
Quand l’utiliser : pour les pages dont les sections doivent rester fixes, mais que le client doit pouvoir réorganiser. Par exemple, une page de portfolio dont le nombre de sections est prédéfini, mais dont le client choisit l’ordre.
"contentOnly"
{
"name": "homepage",
"templateLock": "contentOnly"
}
Les clients peuvent modifier le texte, mais ne peuvent ni ajouter, ni supprimer, ni déplacer de blocs. La différence avec "all" est que "all" empêche aussi la modification du contenu, tandis que "contentOnly" l’autorise explicitement.
Quand l’utiliser : c’est le choix le plus courant pour les pages destinées aux clients. Le développeur contrôle la mise en page. Le client renseigne le texte.
false
{
"name": "blog",
"templateLock": false
}
Aucun verrouillage. Les clients ont le contrôle total : ils peuvent ajouter, supprimer, déplacer et modifier n’importe quel bloc. Le modèle fournit une structure de départ, puis le client en prend les commandes.
Quand l’utiliser : pour les pages d’index de blog, les pages de contenu libre ou toute page où le client doit disposer d’une liberté éditoriale totale.
Mode d’édition des blocs
Alors que templateLock contrôle la structure (ajout, suppression, déplacement), blockEditingMode contrôle les interactions avec chaque bloc : déterminer si les blocs peuvent être sélectionnés, configurés ou modifiés.
Définissez une valeur par défaut pour la page dans page.json :
{
"name": "landing",
"templateLock": "all",
"blockEditingMode": "disabled"
}
"default"
Édition complète. Les blocs peuvent être sélectionnés, leurs réglages modifiés et leur contenu édité. C’est l’expérience habituelle dans l’éditeur.
"contentOnly"
Les blocs peuvent être modifiés, mais uniquement pour leur contenu textuel. Vous ne pouvez pas ouvrir leurs réglages, changer les couleurs, ajuster les marges internes ni modifier d’autres attributs sans rapport avec le contenu. La barre d’outils du bloc n’affiche que les options de mise en forme du texte.
"disabled"
Les blocs sont entièrement inactifs. Ils s’affichent dans l’éditeur, mais ne peuvent être ni cliqués, ni sélectionnés, ni modifiés. Le client voit le contenu, mais ne peut pas y toucher.
Dérogations par élément
C’est là que cela devient intéressant. La valeur blockEditingMode définie au niveau de la page s’applique par défaut à tous ses blocs, mais vous pouvez la remplacer pour des éléments spécifiques du modèle :
{
"name": "landing",
"templateLock": "all",
"blockEditingMode": "disabled"
}
<block name="core/cover" url="https://example.com/hero.jpg">
<h1 blockEditingMode="contentOnly">Edit This Heading</h1>
<p blockEditingMode="contentOnly">Edit this paragraph too.</p>
</block>
<div>
<h2>Features</h2>
<p>This paragraph cannot be edited (inherits "disabled").</p>
<p blockEditingMode="contentOnly">But this one can.</p>
</div>
<block name="core/buttons">
<block name="core/button" url="/contact">This button is frozen</block>
</block>
La valeur par défaut de la page est "disabled" : tous les blocs sont donc inactifs au départ. Certains éléments peuvent ensuite activer "contentOnly" pour rendre leur texte modifiable. Résultat : le client peut saisir du texte dans exactement deux champs (le titre principal et le paragraphe d’introduction) et dans un paragraphe de fonctionnalité. Tout le reste est verrouillé.
Cela fonctionne sur n’importe quel élément HTML (<h1>, <p>, <div>, etc.) et sur les éléments <block>. Vous pouvez également définir blockEditingMode="default" sur des éléments spécifiques pour autoriser l’édition complète :
<block name="core/buttons" blockEditingMode="default">
<block name="core/button" url="/contact">Fully editable button</block>
</block>
Le client peut maintenant modifier le texte du bouton, URL, les styles et tout autre réglage. Le reste de la page demeure figé.
Propagation aux ancêtres
Un détail important concerne les interactions entre les dérogations par élément et les blocs conteneurs. Si la valeur par défaut de la page est "disabled" et que vous définissez blockEditingMode="contentOnly" sur un titre dans un groupe, le titre doit rester accessible. Or, son groupe parent est "disabled", ce qui empêche d’y accéder.
Blockstudio gère cela automatiquement. Lorsqu’un bloc enfant bénéficie d’une dérogation de mode d’édition, tous ses blocs ancêtres passent à "contentOnly" pour que l’enfant reste accessible. Vous n’avez pas besoin de définir manuellement les modes des conteneurs parents. Définissez simplement la dérogation sur le bloc que vous voulez rendre modifiable : le chemin qui y mène s’ouvre.
<!-- page default: "disabled" -->
<div>
<!-- this group is auto-set to "contentOnly" because it contains an override -->
<div>
<!-- this group is also auto-set to "contentOnly" -->
<p blockEditingMode="contentOnly">Deeply nested but still editable.</p>
</div>
</div>
La propagation aux ancêtres ne fait passer les conteneurs qu’à "contentOnly", jamais à "default". Les groupes ancêtres deviennent ainsi accessibles à la navigation (vous pouvez y entrer), mais pas entièrement modifiables (vous ne pouvez pas changer leurs réglages).
Tableau des choix
En combinant templateLock et blockEditingMode, vous disposez d’un éventail de niveaux de contrôle. Voici les combinaisons les plus utiles :
Le développeur contrôle tout
{ "templateLock": "all" }
Pas besoin de blockEditingMode. La valeur par défaut templateLock: "all" empêche toute modification. À utiliser pour les pages entièrement gérées par du code.
Le client modifie tout le texte
{ "templateLock": "contentOnly" }
Le client peut modifier le texte de n’importe quel bloc, mais pas la structure de la page. Une configuration simple et permissive.
Le client modifie uniquement certains textes
{
"templateLock": "all",
"blockEditingMode": "disabled"
}
À associer à blockEditingMode="contentOnly" sur des éléments spécifiques du modèle. C’est l’option la plus précise : le client ne peut modifier que les blocs que vous avez indiqués.
Le client réorganise des sections fixes
{ "templateLock": "insert" }
Le client peut réorganiser les sections et modifier leur contenu, mais ne peut ni ajouter ni supprimer de blocs. Idéal pour les pages composées d’un ensemble fixe de sections dont l’ordre peut varier.
Le client a le contrôle total
{ "templateLock": false }
Le modèle sert de point de départ. À partir de là, le client peut tout faire.
Préserver les modifications du client
Par défaut, lorsque vous mettez à jour un fichier de modèle, Blockstudio remplace l’intégralité du contenu de la page. Si le client a modifié un titre dans l’éditeur, cette modification disparaît à la prochaine synchronisation. Cela convient aux pages contrôlées par le développeur, mais les pages auxquelles les clients contribuent nécessitent un moyen de préserver leur travail.
Clés
Ajoutez un attribut key à un élément pour qu’il soit fusionné au lieu d’être remplacé :
<block name="core/cover" key="hero" url="https://example.com/hero.jpg">
<h1>Default Hero Title</h1>
<p>Default hero description.</p>
</block>
<div key="features">
<h2>Features</h2>
<p>Feature introduction text.</p>
</div>
<div>
<h2>Unkeyed Section</h2>
<p>This gets replaced on every sync.</p>
</div>
Lorsque le modèle change et que la page est synchronisée à nouveau :
- Les blocs avec une clé conservent le contenu du client (texte, blocs internes, mise en forme). Les attributs structurels du modèle (comme celui de la couverture
url) sont tout de même mis à jour. - Les blocs sans clé sont entièrement remplacés par la version du modèle.
Une clé protège le bloc entier et tous ses enfants. Il n’est pas nécessaire d’ajouter une clé à chaque paragraphe d’un groupe qui en possède déjà une. La clé du groupe couvre tout son contenu.
Les clés doivent être uniques
Les clés doivent être uniques dans l’ensemble du modèle. Si deux éléments partagent la même clé, le deuxième est traité comme un élément sans clé (et un avertissement PHP est émis). Utilisez des noms explicites : "hero", "features", "cta", "testimonial-section".
Faire évoluer les modèles
Les clés vous permettent d’ajouter de nouvelles sections à un modèle sans toucher au contenu existant des clients :
<h1 key="title">Welcome</h1>
<div key="services">
<h2>Our Services</h2>
<p>We do great work.</p>
</div>
<h1 key="title">Welcome</h1>
<div key="services">
<h2>Our Services</h2>
<p>We do great work.</p>
</div>
<div key="testimonials">
<h2>What Clients Say</h2>
<p>Default testimonial text.</p>
</div>
Lors de la synchronisation, le titre et les services conservent les modifications du client. La nouvelle section de témoignages apparaît avec le contenu par défaut du modèle. Si vous supprimez ensuite du modèle un bloc doté d’une clé, celui-ci est supprimé de la page.
Le workflow complet côté client
Voici comment assembler tous ces éléments pour un projet réel :
{
"name": "homepage",
"title": "Home",
"slug": "home",
"postStatus": "publish",
"templateLock": "all",
"blockEditingMode": "disabled"
}
<block name="core/cover" key="hero" url="https://example.com/hero.jpg">
<h1 blockEditingMode="contentOnly">Your Company Name</h1>
<p blockEditingMode="contentOnly">Your tagline goes here.</p>
<block name="core/buttons">
<block name="core/button" url="/contact">Contact Us</block>
</block>
</block>
<div key="features">
<h2 blockEditingMode="contentOnly">What We Do</h2>
<block name="core/columns">
<block name="core/column">
<h3 blockEditingMode="contentOnly">Service One</h3>
<p blockEditingMode="contentOnly">Describe this service.</p>
</block>
<block name="core/column">
<h3 blockEditingMode="contentOnly">Service Two</h3>
<p blockEditingMode="contentOnly">Describe this service.</p>
</block>
<block name="core/column">
<h3 blockEditingMode="contentOnly">Service Three</h3>
<p blockEditingMode="contentOnly">Describe this service.</p>
</block>
</block>
</div>
<block name="core/media-text" key="about" mediaurl="https://example.com/team.jpg" mediatype="image">
<h2 blockEditingMode="contentOnly">About Us</h2>
<p blockEditingMode="contentOnly">Tell your story here.</p>
</block>
<div key="cta">
<h2 blockEditingMode="contentOnly">Ready to get started?</h2>
<block name="core/buttons">
<block name="core/button" url="/contact">Get in Touch</block>
</block>
</div>
Cette page contient quatre sections dotées d’une clé. Le client peut modifier les titres et les paragraphes marqués avec blockEditingMode="contentOnly" ; ces modifications sont conservées lors des mises à jour du modèle. Le développeur contrôle la mise en page, les images, les URL des boutons et la structure générale. Si le développeur ajoute ensuite une section de témoignages entre « about » et « cta », celle-ci apparaît à la prochaine synchronisation sans affecter le texte du client.
Liaison des blocs : une alternative aux clés
WordPress 6.5 a introduit les liaisons de blocs API, qui relient les attributs des blocs aux métadonnées des articles. Au lieu de stocker le contenu modifiable dans le balisage du bloc (où les clés le protègent), le contenu est stocké dans wp_postmeta (où les synchronisations de modèles ne peuvent pas le modifier).
<h1 metadata='{"bindings":{"content":{"source":"core/post-meta","args":{"key":"hero_title"}}}}'>
Default Title
</h1>
<p metadata='{"bindings":{"content":{"source":"core/post-meta","args":{"key":"hero_description"}}}}'>
Default description.
</p>
Les clés de métadonnées doivent être enregistrées dans PHP :
register_post_meta( 'page', 'hero_title', array(
'show_in_rest' => true,
'single' => true,
'type' => 'string',
'default' => 'Default Title',
) );
Les liaisons de blocs ont deux avantages sur les clés : les données peuvent être interrogées avec WP_Query via meta_query, et elles sont disponibles dans le REST API. En contrepartie, chaque clé de métadonnées doit être enregistrée dans PHP, et les liaisons ne fonctionnent qu’avec des attributs de bloc individuels (pas avec du contenu imbriqué complexe).
Utilisez les clés pour les sections au contenu riche dont la structure des blocs est importante (un groupe avec des titres, des paragraphes et des images). Utilisez les liaisons pour les valeurs textuelles individuelles que vous devez aussi pouvoir interroger ou afficher ailleurs.
Modèles de types de publication
Utilisez templateFor pour définir une structure de blocs par défaut pour tous les nouveaux articles d’un type donné :
{
"name": "product-template",
"title": "Product Template",
"templateFor": "product",
"templateLock": "insert"
}
<h1>Product Name</h1>
<block name="core/columns">
<block name="core/column">
<img src="" alt="Product image" />
</block>
<block name="core/column">
<p>Product description goes here.</p>
<block name="core/buttons">
<block name="core/button" url="#">Buy Now</block>
</block>
</block>
</block>
<div>
<h2>Specifications</h2>
<table>
<thead>
<tr><th>Feature</th><th>Value</th></tr>
</thead>
<tbody>
<tr><td>Weight</td><td>1.2 kg</td></tr>
</tbody>
</table>
</div>
Chaque nouvel article de type « product » commence avec cette structure. templateLock: "insert" permet aux éditeurs de réorganiser les sections et de modifier leur contenu, mais pas d’ajouter ni de supprimer des blocs.
Conseils
Synchronisez à un moment précis du déploiement. Lancez wp bs pages sync après
avoir modifié ou déployé les sources des pages. Les visites du site ou de l’administration ne synchronisent jamais les pages. PHP Les outils de déploiement peuvent appeler Blockstudio\Pages::reconcile() et
examiner son rapport lisible par machine.
Épinglez les ID des articles importants. Utilisez postId dans page.json pour les pages référencées par des menus, des liens codés en dur ou des systèmes externes. Sans épinglage, une page supprimée puis recréée reçoit un nouvel ID, ce qui rompt ces références.
Utilisez sync: false pour les structures de départ. Pour créer une page une seule fois, puis la confier entièrement au client, définissez "sync": false et créez-la avec Blockstudio\Pages::force_sync(). La réconciliation normale l’ignore alors.
Verrouillez et déverrouillez via PHP. Appelez Blockstudio\Pages::lock('about') pour empêcher la synchronisation d’une page donnée (utile pendant les périodes où le client y apporte des modifications). Appelez Blockstudio\Pages::unlock('about') pour réactiver la synchronisation.
Moteurs de modèles. En plus de PHP, les modèles peuvent être écrits en Twig (nécessite Timber) ou en Blade (nécessite illuminate/view). C’est utile pour les boucles et les filtres, mais les modèles de pages sont compilés lors d’une synchronisation explicite, pas lors d’une requête au site. Utilisez PHP si la compilation des sources elle-même a besoin d’assistants propres à PHP.
La synchronisation forcée ignore les clés. Un appel à Pages::force_sync('about') remplace l’intégralité du contenu de la page et ignore les clés et la vérification de la date de modification. Utilisez-le lorsque vous souhaitez délibérément réinitialiser une page à l’état du modèle.
Étapes suivantes
- Référence des pages : toutes les propriétés
page.json, le PHP API et l’algorithme de fusion avec clés, en détail. - Présentation des pages et des compositions : le parseur HTML, la référence de la syntaxe des blocs, les moteurs de rendu personnalisés et la correspondance des éléments.
- Compositions : la même syntaxe de modèle pour créer des compositions de blocs réutilisables plutôt que des pages.