Aller au contenu

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/ :

Text
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 :

  1. index.php
  2. index.blade.php
  3. index.twig
  4. index.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.

JSON
{
  "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 :

Text
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.

JSON
{
  "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 :

PHP
<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 :

  1. Personnalisation enregistrée dans la base de données de l’éditeur du site
  2. Fichier de thème actif natif .html
  3. Source basée sur des fichiers Blockstudio
  4. 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

PHP
$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 :

PHP
$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 :

PHP
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 :

PHP
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 :

PHP
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 :

PHP
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 :

PHP
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.