Aller au contenu

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 :

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

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

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

HTML
<!-- 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.

Une partie peut se limiter à un seul paragraphe. Celle-ci utilise index.html pour souligner que la source est du balisage, pas un programme :

JSON
{
  "slug": "footer",
  "title": "Footer",
  "area": "footer"
}
HTML
<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.

JSON
{
  "slug": "front-page",
  "title": "Front Page",
  "description": "Homepage template"
}
PHP
<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 :

JSON
{
  "slug": "single",
  "title": "Single Post"
}
PHP
<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é :

HTML
<!-- 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 :

JSON
{
  "slug": "page-landing",
  "title": "Landing Page",
  "description": "Full-width page without a header",
  "postTypes": ["page"]
}
PHP
<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 :

  1. Une personnalisation de l’éditeur de site enregistrée dans la base de données.
  2. Un fichier .html natif dans le thème actif.
  3. La source basée sur le fichier Blockstudio.
  4. 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 :

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

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

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;
} );

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