Modèles du site
Les modèles du site permettent aux thèmes de blocs de définir des sources WordPress wp_template et wp_template_part en utilisant la même syntaxe privilégiant les fichiers que pour les pages et motifs Blockstudio.
Utilisez les modèles du site lorsque vous souhaitez contrôler la mise en page du thème que WordPress sélectionne dans la hiérarchie des modèles de l’éditeur du site : page d’accueil, publications individuelles, archives, recherche, pages 404, en-têtes, pieds de page et autres parties de modèle.
Pages, motifs ou modèles du site ?
| Fonctionnalité | Crée | Idéal pour |
|---|---|---|
| Pages | Publications ou entrées de type de publication personnalisé | Pages de contenu réelles, pages de documentation, pages de destination et contenu avec routage. |
| Motifs | Motifs de blocs | Sections réutilisables insérées par les éditeurs. |
| Modèles du site | Sources de fichiers wp_template et wp_template_part |
Mise en page du thème contrôlée par l’éditeur du site et la hiérarchie de modèles WordPress. |
Les modèles du site ne créent pas de pages ordinaires. Ils fournissent la source fichier qu’utilise WordPress pour résoudre un modèle de thème de blocs. Si un utilisateur personnalise le modèle dans l’éditeur du site, WordPress enregistre cette personnalisation dans la base de données, où elle prévaut sur la source fichier jusqu’à sa réinitialisation.
Structure des dossiers
Placez les modèles complets dans templates/ et les parties de modèle dans parts/ :
theme/
templates/
front-page/
template.json
index.php
single/
template.json
index.twig
parts/
header/
part.json
index.php
footer/
part.json
index.php
Chaque dossier contient un manifeste et un fichier source.
| Fichier | Moteur |
|---|---|
index.php |
Balisage de bloc de type HTML, lu tel quel (le code PHP n’est pas exécuté) |
index.blade.php |
Blade |
index.twig |
Twig |
index.html |
Balisage de bloc de type HTML |
Si plusieurs fichiers source existent, Blockstudio suit cet ordre :
index.phpindex.blade.phpindex.twigindex.html
WordPress détecte également les fichiers .html de manière récursive et expose normalement un index.html imbriqué sous un slug dérivé de son chemin, tel que header/index.
Lorsque ce fichier appartient à un manifeste Blockstudio, Blockstudio supprime le doublon dérivé du chemin et n’expose que le slug déclaré dans le manifeste.
Les modèles natifs .html imbriqués sans manifeste Blockstudio restent inchangés.
La source est compilée une fois en balisage de bloc natif WordPress. Elle ne doit pas dépendre de la requête ou de la publication en cours. Placez le comportement d’exécution dans des blocs dynamiques.
template.json
template.json définit un modèle complet de l’éditeur du site.
{
"slug": "front-page",
"title": "Front Page",
"description": "Homepage template",
"postTypes": ["page"]
}
Propriétés
| Propriété | Type | Valeur par défaut | Description |
|---|---|---|---|
slug / name |
string |
Nom du dossier | Slug du modèle WordPress. Utilisez les slugs exacts de la hiérarchie, tels que front-page, single, archive-product ou 404. |
title |
string |
Titre dérivé du slug | Titre affiché dans l’éditeur du site. |
description |
string |
"" |
Description affichée dans l’éditeur du site. |
postTypes |
string[] |
[] |
Types de publication pour les modèles personnalisés. Les modèles de la hiérarchie du cœur peuvent omettre cette propriété. |
source / template / file |
string |
Fichier index détecté automatiquement | Chemin facultatif du fichier source, relatif au dossier du modèle. |
status |
string |
"publish" |
État du modèle. |
sync |
boolean |
false |
Réservé à une matérialisation future dans la base de données. Les personnalisations utilisateur ne sont jamais écrasées dans v1. |
meta |
object |
{} |
Métadonnées personnalisées pour les API d’assistance. Les clés de manifeste inconnues sont également stockées ici. |
Les slugs de modèle ne sont pas préfixés. WordPress a besoin de noms exacts pour la hiérarchie des modèles :
index
home
front-page
single
single-post
single-product
archive
archive-product
page
page-about
404
search
taxonomy-product_cat
part.json
part.json définit une partie de modèle de l’éditeur du site.
{
"slug": "header",
"title": "Header",
"description": "Main site header",
"area": "header"
}
Propriétés
| Propriété | Type | Valeur par défaut | Description |
|---|---|---|---|
slug / name |
string |
Nom du dossier | Slug de la partie de modèle WordPress. |
title |
string |
Titre dérivé du slug | Titre affiché dans l’éditeur du site. |
description |
string |
"" |
Description affichée dans l’éditeur du site. |
area |
string |
"uncategorized" |
Zone de la partie de modèle. Les valeurs courantes sont header, footer et sidebar. |
source / template / file |
string |
Fichier index détecté automatiquement | Chemin facultatif du fichier source, relatif au dossier de la partie. |
status |
string |
"publish" |
État de la partie de modèle. |
meta |
object |
{} |
Métadonnées personnalisées pour les API d’assistance. Les clés de manifeste inconnues sont également stockées ici. |
Création du balisage
Les sources des modèles du site utilisent le même analyseur que les pages et les motifs :
<div class="site-shell">
<block name="core/template-part" slug="header" />
<main>
<h1>Welcome</h1>
<p>This template is compiled from Blockstudio files.</p>
<block name="core/post-content" />
</main>
<block name="core/template-part" slug="footer" />
</div>
L’élément <main> devient un bloc core/group qui s’affiche comme <main>,
et ses enfants, y compris la balise de bloc core/post-content, deviennent ses blocs internes. Vous pouvez utiliser :
- des éléments HTML standard, tels que
<h1>,<p>,<ul>,<div>, et les éléments de sectionnement<main>,<header>,<footer>,<article>et<aside> <block name="namespace/block"><bs:namespace-block>- des préfixes configurés de balises de bloc
- des blocs et composants Blockstudio
Lorsque WordPress affiche le modèle compilé, les blocs de partie de modèle reçoivent l’attribut du thème actif.
Personnalisations dans l’éditeur du site
Blockstudio fournit la source fichier. WordPress gère les personnalisations utilisateur.
L’ordre de recherche est le suivant :
- Personnalisation enregistrée dans la base de données de l’éditeur du site
- Fichier de thème actif natif
.html - Source basée sur des fichiers Blockstudio
- Solutions de repli du thème parent ou de l’extension
Lorsqu’un utilisateur enregistre dans l’éditeur du site un modèle basé sur un fichier Blockstudio, WordPress crée une entrée de base de données normale wp_template ou wp_template_part.
Cette entrée enregistrée prévaut sur les modifications ultérieures du fichier. La réinitialisation ou la suppression de la personnalisation révèle à nouveau la dernière source basée sur un fichier.
Blockstudio ne réécrit pas dans des fichiers les modifications de l’éditeur du site situées dans v1.
Performances
La découverte des modèles est mise en cache par requête et conservée avec les métadonnées de surveillance des fichiers. Toute modification d’un manifeste ou d’un fichier source invalide le contenu compilé mis en cache. Les personnalisations de la base de données ne sont pas mises en cache par-dessus : WordPress les vérifie toujours en premier.
Les intégrations d’exécution qui composent des fichiers provenant de plusieurs racines peuvent fournir une source de découverte logique pour les modèles et les parties de modèle. Les manifestes et les modèles source sélectionnés peuvent se trouver dans différentes racines physiques tout en conservant une seule arborescence de thème logique.
PHP API
$templates = Blockstudio\Site_Templates::templates();
$parts = Blockstudio\Site_Templates::parts();
$template = Blockstudio\Site_Templates::get_template('front-page');
$header = Blockstudio\Site_Templates::get_part('header');
$paths = Blockstudio\Site_Templates::get_paths();
Transmettez une liste explicite pour lire et compiler uniquement les slugs, chemins ou chemins source exacts :
$templates = Blockstudio\Site_Templates::templates([
'front-page',
]);
$parts = Blockstudio\Site_Templates::parts([
'header',
]);
$errors = Blockstudio\Site_Templates::selection_errors('templates');
L’omission de l’argument conserve le comportement complet du registre. Une liste vide ne renvoie aucun élément. Les demandes de slug et de chemin conventionnels limitent la découverte aux répertoires correspondants ; les slugs personnalisés de manifeste peuvent nécessiter une analyse des métadonnées, mais les sources sans rapport ne sont toujours ni compilées ni renvoyées.
Les fonctions d’assistance des modèles sont également disponibles :
blockstudio_site_templates();
blockstudio_site_template_parts();
blockstudio_site_template('front-page');
blockstudio_site_template_part('header');
Hooks
Voici tous les points d’extension des modèles du site :
| Hook | Type | Description |
|---|---|---|
blockstudio/site_templates/template_paths |
Filtre | Ajuste les racines de découverte des modèles complets. |
blockstudio/site_templates/part_paths |
Filtre | Ajuste les racines de découverte des parties de modèle. |
blockstudio/site_templates/paths |
Filtre | Ajuste les deux listes de chemins sous la forme templates et parts. |
blockstudio/site_templates/template_candidates |
Filtre | Ajuste les fichiers source candidats d’un manifeste. |
blockstudio/site_templates/templates |
Filtre | Ajuste les modèles renvoyés par API du registre. |
blockstudio/site_templates/parts |
Filtre | Ajuste les parties de modèle renvoyées par API du registre. |
blockstudio/site_templates/template_content |
Filtre | Ajuste la source compilée du modèle complet avant l’analyse. |
blockstudio/site_templates/part_content |
Filtre | Ajuste la source compilée de la partie de modèle avant l’analyse. |
blockstudio/site_templates/parser |
Filtre | Remplace l’instance Html_Parser pour un élément. |
blockstudio/site_templates/source_compiled |
Action | S’exécute juste avant la compilation d’une source sélectionnée. |
blockstudio/site_templates/discovered |
Action | S’exécute après une passe de découverte et de compilation à froid. |
blockstudio/site_templates/registered |
Action | S’exécute après la persistance du registre reconstruit. |
Ajouter ou remplacer des chemins de découverte :
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;
});
add_filter('blockstudio/site_templates/paths', function ($paths) {
return $paths;
});
Filtrer les données découvertes :
add_filter('blockstudio/site_templates/templates', function ($templates) {
return $templates;
});
add_filter('blockstudio/site_templates/parts', function ($parts) {
return $parts;
});
Filtrer la source avant l’analyse :
add_filter('blockstudio/site_templates/template_content', function ($content, $template) {
return $content;
}, 10, 2);
add_filter('blockstudio/site_templates/part_content', function ($content, $part) {
return $content;
}, 10, 2);
Modifier les sources candidates ou l’analyseur :
add_filter(
'blockstudio/site_templates/template_candidates',
function ($candidates, $directory, $manifest) {
$candidates[] = $directory . '/template.custom.php';
return $candidates;
},
10,
3
);
add_filter(
'blockstudio/site_templates/parser',
function ($parser, $item) {
return $parser;
},
10,
2
);
discovered et registered sont des actions du cycle de vie de reconstruction du cache. Elles ne se déclenchent pas lorsqu’un accès utilise un cache de registre encore valide.