Modèles et parties de l’éditeur de site à partir de fichiers
Un thème de blocs décrit sa mise en page dans templates/*.html et parts/*.html :
des fichiers remplis de commentaires de blocs sérialisés tels que
<!-- wp:template-part {"slug":"header"} /-->. Personne n’aime les écrire
à la main, alors ils sont généralement créés dans l’éditeur de site puis exportés. Cela fonctionne
jusqu’à ce que deux personnes modifient le même modèle ou qu’un relecteur doive examiner un diff de
JSON échappé dans des commentaires HTML.
Blockstudio vous permet d’écrire les mêmes modèles comme des
pages basées sur des fichiers : un dossier avec un petit manifeste JSON et un fichier source en syntaxe de balisage de type HTML, avec des éléments simples, des balises <block> et vos propres blocs Blockstudio.
Blockstudio compile la source en balisage natif de blocs et la transmet à WordPress
comme fichier de thème. L’éditeur de site fonctionne toujours exactement comme avant : les utilisateurs peuvent
personnaliser un modèle, et sa réinitialisation rétablit la version du fichier.
Ce guide crée une partie d’en-tête et de pied de page, des modèles de page d’accueil et de publication, ainsi qu’un modèle personnalisé que les éditeurs peuvent choisir pour les pages, puis montre comment WordPress les résout.
Structure des dossiers
Les modèles vont dans templates/, les parties de modèle dans parts/. Chacun est un dossier
avec un manifeste et un fichier source :
theme/
├── templates/
│ ├── front-page/
│ │ ├── template.json
│ │ └── index.php
│ ├── single/
│ │ ├── template.json
│ │ └── index.php
│ └── page-landing/
│ ├── template.json
│ └── index.php
└── parts/
├── header/
│ ├── part.json
│ └── index.php
└── footer/
├── part.json
└── index.html
Ce sont les mêmes dossiers templates/ et parts/ que WordPress lit pour un thème
de blocs. Blockstudio analyse d’abord le thème actif, puis le thème parent.
Les dossiers contenant un template.json ou un part.json sont des sources Blockstudio ; les fichiers .html simples
qui se trouvent à côté restent des modèles WordPress natifs.
Le fichier source peut être index.php, index.blade.php, index.twig ou
index.html, dans cet ordre de vérification. Twig nécessite Timber et Blade nécessite son
package de rendu, comme décrit dans
les moteurs de modèles.
Étape 1 : la partie d’en-tête
Chaque partie a besoin d’un part.json. Le area indique à l’éditeur de site où placer la partie :
{
"slug": "header",
"title": "Header",
"description": "Site header with logo and navigation",
"area": "header"
}
La source utilise la même syntaxe que les pages et motifs Blockstudio. Un <div>
devient un bloc de groupe, les attributs deviennent des attributs de bloc et les éléments <block>
produisent n’importe quel bloc enregistré :
<div layout='{"type":"flex","justifyContent":"space-between"}'>
<block name="core/site-title" />
<block name="core/navigation" overlayMenu="mobile" />
</div>
Blockstudio le compile en ce balisage de blocs :
<!-- wp:group {"layout":{"type":"flex","justifyContent":"space-between"}} --><div class="wp-block-group is-layout-flex"><!-- wp:site-title /--><!-- wp:navigation {"overlayMenu":"mobile"} /--></div><!-- /wp:group -->
C’est ce que vous auriez autrement écrit à la main. Vos propres blocs fonctionnent de la
même façon : <block name="acme/announcement" />, une balise <bs:acme-announcement />
ou un préfixe de balise configuré compilent tous en commentaire de bloc pour ce
bloc.
Étape 2 : la partie de pied de page
Une partie peut se limiter à un seul paragraphe. Celle-ci utilise index.html pour souligner
que la source est du balisage, pas un programme :
{
"slug": "footer",
"title": "Footer",
"area": "footer"
}
<p>Built with Acme.</p>
Elle est compilée en <!-- wp:paragraph --><p>Built with Acme.</p><!-- /wp:paragraph -->.
Étape 3 : modèles de page d’accueil et de publication
Les modèles utilisent template.json. slug doit être un nom de modèle de hiérarchie WordPress exact,
comme front-page, single, page, archive, 404 ou
single-product. Blockstudio ne le précède jamais.
{
"slug": "front-page",
"title": "Front Page",
"description": "Homepage template"
}
<block name="core/template-part" slug="header" tagName="header" />
<main>
<block name="core/post-content" />
</main>
<block name="core/template-part" slug="footer" tagName="footer" />
Le modèle de publication suit la même structure avec des blocs de publication :
{
"slug": "single",
"title": "Single Post"
}
<block name="core/template-part" slug="header" tagName="header" />
<main>
<block name="core/post-title" level="1" />
<block name="core/post-date" />
<block name="core/post-content" />
</main>
<block name="core/template-part" slug="footer" tagName="footer" />
Le modèle de publication compilé :
<!-- wp:template-part {"slug":"header","tagName":"header"} /--><!-- wp:group {"tagName":"main"} --><main class="wp-block-group"><!-- wp:post-title {"level":1} /--><!-- wp:post-date /--><!-- wp:post-content /--></main><!-- /wp:group --><!-- wp:template-part {"slug":"footer","tagName":"footer"} /-->
<main> est devenu un bloc de groupe avec tagName: "main", et les blocs de parties de modèle
référencent par slug les parties des étapes 1 et 2. Lorsque WordPress affiche
le modèle, ces références pointent vers les parties provenant des fichiers, si bien que la page d’accueil
commence par <header class="wp-block-template-part"> qui contient le titre du site et la navigation, et se termine par <footer class="wp-block-template-part"> qui contient le paragraphe de pied de page.
Étape 4 : un modèle personnalisé pour les pages
Les modèles dont le slug ne fait pas partie de la hiérarchie sont des modèles personnalisés. Indiquez
les types de publications auxquels ils s’appliquent avec postTypes, et les éditeurs peuvent les choisir dans
le sélecteur de modèles :
{
"slug": "page-landing",
"title": "Landing Page",
"description": "Full-width page without a header",
"postTypes": ["page"]
}
<main>
<block name="core/post-content" />
</main>
<block name="core/template-part" slug="footer" tagName="footer" />
get_block_templates( array( 'post_type' => 'page' ), 'wp_template' ) inclut maintenant
page-landing, et l’objet modèle contient
post_types: ["page"].
Les sources sont compilées une seule fois
La source est lue et compilée en balisage de blocs une fois, et non à chaque requête. Il n’y a
ni publication actuelle ni contexte de requête. index.php est lu comme du balisage : le code PHP qu’il contient
n’est pas exécuté, donc <?php echo get_bloginfo( 'name' ); ?> ne compile rien. Tout ce qui dépend de la requête doit se trouver dans un bloc rendu à l’exécution : core/site-title plutôt que le nom du site affiché, core/post-title plutôt que the_title(), ou un bloc Blockstudio dynamique de votre cru.
Les résultats compilés sont mis en cache avec les métadonnées de surveillance des fichiers. La modification d’un manifeste ou d’un fichier source invalide le contenu mis en cache pour cet élément, si bien que la requête suivante voit le changement sans étape de compilation distincte.
Comment WordPress voit les fichiers
Blockstudio s’intègre aux mêmes recherches que celles utilisées par WordPress pour les modèles de thème. Dans get_block_templates(), les modèles provenant de fichiers apparaissent avec source: "theme" et origin: "theme", tout comme les fichiers de thème natifs, et get_block_template( 'acme//header', 'wp_template_part' ) renvoie la partie d’en-tête avec son area.
L’ordre de recherche est le suivant :
- Une personnalisation de l’éditeur de site enregistrée dans la base de données.
- Un fichier
.htmlnatif dans le thème actif. - La source basée sur le fichier Blockstudio.
- Les solutions de repli du thème parent ou des extensions.
Cet ordre préserve le fonctionnement de l’éditeur de site. Lorsqu’un utilisateur modifie le pied de page et enregistre, WordPress stocke une publication wp_template_part et get_block_template() renvoie cette personnalisation avec source: "custom".
Les modifications ultérieures de parts/footer/index.html ne sont pas visibles tant que la personnalisation existe. Lorsque l’utilisateur réinitialise la partie ou que la publication est supprimée, la recherche se rabat sur le fichier et renvoie de nouveau la dernière source compilée.
Blockstudio ne répercute pas dans les fichiers les modifications de l’éditeur de site. Si une modification doit devenir la nouvelle valeur par défaut, copiez-la dans le fichier source et réinitialisez la personnalisation.
index.html imbriqués et slugs
WordPress détecte récursivement les fichiers .html dans templates/ et parts/. Un dossier avec manifeste utilisant index.html, comme parts/footer/index.html, apparaîtrait donc aussi comme partie native avec le slug dérivé du chemin footer/index. Comme Blockstudio 7.6.6, un index.html géré par un manifeste n’est exposé que sous le slug qui lui est déclaré ; l’éditeur de site affiche donc un seul pied de page, et non deux. Les fichiers .html imbriqués sans manifeste sont laissés tels quels.
Vérifier les modèles depuis PHP
La classe Blockstudio\Site_Templates lit et compile les sources, ce qui est utile dans les tests et les vérifications de déploiement :
$templates = Blockstudio\Site_Templates::templates();
$header = Blockstudio\Site_Templates::get_part( 'header' );
echo $header['area']; // header
echo $header['content']; // compiled block markup
$errors = Blockstudio\Site_Templates::errors();
Chaque élément comprend slug, title, description, type (wp_template ou wp_template_part), status, source_type, postTypes pour les modèles ou area pour les parties, meta et le content compilé. Passez une liste pour ne compiler que certains éléments, et consultez les problèmes pour cette sélection avec selection_errors() :
$selected = Blockstudio\Site_Templates::templates( array( 'front-page' ) );
$errors = Blockstudio\Site_Templates::selection_errors( 'templates' );
Ajouter d’autres dossiers
Pour séparer les sources Blockstudio des modèles natifs ou les distribuer depuis une extension, ajoutez des racines de découverte à l’aide de filtres :
add_filter( 'blockstudio/site_templates/template_paths', function ( $paths ) {
$paths[] = get_stylesheet_directory() . '/site-templates';
return $paths;
} );
add_filter( 'blockstudio/site_templates/part_paths', function ( $paths ) {
$paths[] = get_stylesheet_directory() . '/site-parts';
return $paths;
} );
Les filtres blockstudio/site_templates/template_content et part_content modifient une source avant son analyse, et blockstudio/site_templates/parser remplace l’analyseur pour un seul élément. La liste complète figure dans le tableau des hooks des modèles de site.
Quand utiliser quoi
| Ce que vous voulez | Utilisez |
|---|---|
| La mise en page du thème WordPress choisit pour un URL : en-tête, pied de page, publication, archive | Modèles et parties de site |
| Une page accessible par une URL dont le contenu se trouve dans des fichiers | Pages basées sur des fichiers |
| Une section réutilisable que les éditeurs insèrent | Motifs |
Les modèles ne créent pas de publications. Les pages, oui. Une section de documentation, par exemple, est une collection de pages dont les publications sont affichées à l’aide d’un modèle que vous pouvez toujours créer ici.
Étapes suivantes
- Référence des modèles de site : chaque propriété de manifeste, le PHP API et tous les hooks.
- Présentation des pages et des motifs : l’analyseur HTML, les balises de blocs et la correspondance des éléments utilisés par les sources de modèle.
- Créer un site de documentation : des collections de pages avec Markdown, des chargeurs de données et des mises en page.