Aller au contenu

Pages

Les pages sont des modèles basés sur des fichiers qui se synchronisent avec la base de données WordPress sous forme d’articles. La synchronisation est explicite : exécutez wp bs pages sync ou appelez le API Pages lorsque vous souhaitez appliquer les modifications des sources. Le chargement de l’interface publique ou de l’interface d’administration WordPress ne lance jamais la découverte complète des pages et ne modifie jamais les articles de page.

Les pages peuvent être définies dans un dossier page.json unique, sous forme de fichiers Markdown autonomes ou comme collection dotée d’un manifeste pages.json. Les collections sont utiles pour la documentation, les bases de connaissances, les bibliothèques de pages de destination ou tout ensemble de pages imbriquées à générer à partir de fichiers.

page.json

Pour une page définie par JSON, ajoutez un fichier de configuration page.json :

JSON
{
  "name": "about",
  "title": "About Us",
  "slug": "about-us",
  "postType": "page",
  "postStatus": "publish",
  "templateLock": "all"
}

Propriétés

Propriété Type Valeur par défaut Description
name string obligatoire Identifiant unique de la page
title string Automatique à partir du nom Titre de la page
slug string Identique au nom Slug URL de la page
path string "." Chemin logique au sein d’une collection
order integer 0 Ordre dans le menu pour l’article synchronisé
postType string "page" Type d’article WordPress
postStatus string "draft" Statut des nouveaux articles (publish, draft, pending, private)
postId integer – Associer la page à un ID d’article WordPress spécifique
blockEditingMode string – Mode d’édition des blocs : "default", "contentOnly" ou "disabled"
templateLock string|false "all" Mode de verrouillage : "all", "insert", "contentOnly" ou false
templateFor string|null null Définir comme modèle par défaut pour un type d’article
sync boolean true Indique si une réconciliation explicite normale peut créer ou mettre à jour l’article
render string|object|false – Effectuer le rendu de la page avec un moteur de rendu de page enregistré (voir Pages de composants)

Dans page.json, le frontmatter et les entrées du chargeur, les clés reconnues incluent blockEditingMode, collection, content, contentType, defaults, file, html, markdown, meta, name, order, path, postId, postStatus, postType, postTypeArgs, render, slug, template, templateFor, templateLock et title. Toute clé non répertoriée ci-dessus est stockée dans le tableau meta de la page.

Sources de contenu

La définition d’une page détermine quel article WordPress doit exister. La source de contenu détermine le balisage de blocs écrit dans cet article.

Lorsqu’un dossier de page contient un fichier page.json, Blockstudio recherche un fichier source voisin dans cet ordre :

Fichier Utilisation
index.php Balisage de blocs de type HTML, lu tel quel (le code PHP n’est pas exécuté)
index.blade.php Contenu de modèle Blade
index.twig Contenu de modèle Twig
index.md Contenu Markdown

page.json peut également fournir du contenu markdown ou html intégré au lieu d’un fichier voisin :

JSON
{
  "name": "intro",
  "title": "Intro",
  "markdown": "# Intro\n\nThis page is generated from inline markdown."
}
JSON
{
  "name": "notice",
  "title": "Notice",
  "html": "<h1>Notice</h1><p>This page is generated from inline HTML.</p>"
}

Les collections proposent deux autres modes de source :

  • Fichiers Markdown trouvés directement dans l’arborescence de la collection.
  • Entrées de chargeur renvoyées par loader.php.

Les entrées de chargeur peuvent utiliser markdown, html ou content avec contentType. Elles peuvent également pointer vers un file ou un template local. Les sources de fichiers et de modèles déduisent leur type d’après l’extension, sauf si contentType est défini explicitement.

Les valeurs contentType prises en charge sont php, blade, twig, markdown et html. Markdown est d’abord converti en HTML, puis analysé en blocs natifs WordPress. Les sources PHP, Blade, Twig et HTML passent par l’analyseur de pages Blockstudio standard.

Classes des blocs de base

Un class sur un élément HTML associé à un bloc de base devient son className. Une balise explicite de bloc de base peut utiliser directement className. Les deux formes préservent les classes de l’enveloppe enregistrée du bloc, ainsi que celles générées par WordPress :

HTML
<p class="intro">Introduction</p>
<block name="core/group" className="feature">
  <h2 class="title">Feature</h2>
</block>

Si les deux propriétés sont présentes, className a la priorité. Cette conversion ne s’applique qu’aux blocs de base : l’association d’un bloc personnalisé conserve son champ class inchangé. Les classes de style du bouton, telles que is-style-outline, appartiennent à l’enveloppe du bouton, et non à son lien.

Exécutez wp bs pages sync pour appliquer les corrections de l’analyseur aux pages synchronisées auparavant. Les mises à niveau de l’analyseur sont prises en compte lors de la prochaine synchronisation explicite, sans modification du fichier source. Les pages verrouillées et celles avec sync: false conservent leurs protections habituelles ; les requêtes de l’interface publique ne déclenchent jamais cette synchronisation.

Blocs WordPress sérialisés

Les sources de pages et de compositions peuvent également contenir des blocs sérialisés copiés depuis l’éditeur de code WordPress :

HTML
<!-- wp:paragraph {"className":"intro"} -->
<p class="intro">Introduction</p>
<!-- /wp:paragraph -->

Lorsque la source contient un délimiteur de bloc <!-- wp:... -->, Blockstudio utilise l’analyseur de blocs natif de WordPress pour l’ensemble de la source. Les attributs, les blocs imbriqués, les blocs dynamiques tels que Query Loop et les blocs Blockstudio conservent leur structure sérialisée. Le contenu HTML situé en dehors des commentaires de bloc reste du contenu libre natif HTML ; il n’est pas converti en blocs supplémentaires. Ne mélangez pas les balises de bloc HTML de Blockstudio à ce format en vous attendant à ce qu’elles soient converties. Les commentaires ordinaires HTML ne sélectionnent pas le mode des blocs sérialisés.

Pages Markdown

Utilisez Markdown lorsque le texte doit rester dans des fichiers tout en devenant un contenu de blocs WordPress modifiable après synchronisation. La source Markdown est convertie en balisage de blocs pendant la synchronisation. L’article synchronisé stocke les blocs, et non le corps Markdown brut.

Markdown peut être utilisé de trois façons :

Source En-tête requis ? Remarques
pages/example/index.md autonome Oui L’en-tête fournit l’identité de la page.
page.json avec index.md Non page.json définit la page et Markdown fournit le contenu.
Markdown dans une collection Non La collection déduit name et path à partir de l’emplacement du fichier.

Un index.md autonome sans en-tête est ignoré, car Blockstudio ne dispose d’aucune identité de page à synchroniser. Les fichiers Markdown d’une collection n’ont pas besoin d’en-tête, car le manifeste et le chemin du fichier de la collection fournissent cette identité.

Markdown
---
name: about
title: About
slug: about
postStatus: publish
---

# About

This Markdown content is synced as native WordPress blocks.

Vous pouvez également associer page.json à index.md. Dans ce cas, page.json définit la page et index.md fournit le contenu. L’en-tête de index.md remplace les valeurs page.json correspondantes.

JSON
{
  "name": "docs-reference",
  "title": "Reference",
  "path": "reference",
  "sync": true
}
Markdown
---
title: API Reference
order: 20
---

# Reference

This page uses `page.json` with Markdown content.

Pour une collection Markdown, le chemin du fichier devient le chemin logique de la page, sauf si l’en-tête le remplace :

Fichier Chemin par défaut
pages/docs/index.md .
pages/docs/getting-started.md getting-started
pages/docs/guide/install/index.md guide/install
pages/docs/guide/install.md guide/install

Les clés inconnues de l’en-tête sont conservées dans le tableau meta de la page. Vous pouvez ainsi joindre des données telles que section ou description et les lire depuis le PHP API.

Markdown est analysé en GitHub Flavored Markdown. Le code HTML brut est autorisé, les liens dangereux sont supprimés et un identifiant stable est attribué aux titres qui n’en ont pas explicitement. L’en-tête YAML imbriqué nécessite l’analyseur YAML intégré.

Markdown brut

Les sources de fichiers Markdown peuvent exposer leur source Markdown originale aux outils externes et aux systèmes de documentation. Le contenu Markdown intégré n’ayant pas de fichier source, il est synchronisé en blocs, mais ne produit pas de réponse .md brute.

Demandez la page avec un suffixe .md, par exemple https://example.com/docs/reference.md. Vous pouvez aussi envoyer un en-tête Accept: text/markdown à l’URL de page standard :

Shell
curl -H "Accept: text/markdown" https://example.com/docs/reference/

L’en-tête est retiré de la réponse. Les réponses Markdown brutes réussies renvoient Content-Type: text/markdown, X-Robots-Tag: noindex et un en-tête Link canonique à la page HTML. Les routes .md introuvables renvoient un véritable 404.

La négociation est compatible avec le prérendu statique static prerendering : une requête dont l’en-tête Accept contient text/markdown ne reçoit jamais de réponse depuis le stockage de prérendu ni depuis le module de réponse anticipée ; elle atteint donc WordPress et le gestionnaire Markdown. Les réponses HTML prérendues, la HTML d’une page qui négocie également Markdown, ainsi que la Markdown transmise via Accept, envoient Vary: Accept. Les caches qui tiennent compte de Vary gardent donc les deux réponses séparées. Un CDN qui indexe son cache uniquement sur URL doit définir sa propre règle pour contourner le cache lors de ces requêtes. Pages::negotiates_markdown( $post_id ) indique si une page répond aux requêtes Markdown.

La collection Markdown conserve la même structure URL pour le Markdown brut :

URL de la page Markdown URL brut
/docs/ /docs.md
/docs/getting-started/ /docs/getting-started.md
/docs/guide/install/ /docs/guide/install.md

Désactivez les réponses Markdown brutes avec le filtre blockstudio/pages/serve_markdown :

PHP
add_filter( 'blockstudio/pages/serve_markdown', '__return_false' );

Une requête .md URL qui ne correspond pas à une page basée sur Markdown ne renvoie un 404 que si le chemin se trouve dans une collection de pages. En dehors de toute collection, Blockstudio laisse la requête à WordPress et aux autres extensions.

Pages de composants

Une page de composant est rendue par un moteur de rendu de page au lieu d’être stockée sous forme de blocs. Blockstudio ne fournit pas de moteur de rendu. Un thème ou une extension en enregistre un pour les fichiers d’entrée qu’il prend en charge, par exemple un moteur de rendu React pour page.tsx, et Blockstudio l’appelle avec la page, l’article WordPress et le contenu rendu de l’emplacement.

Text
pages/legal-notice/
  page.json
  page.tsx
  data.php
JSON
{
  "name": "legal-notice",
  "title": "Legal Notice",
  "slug": "legal-notice",
  "postStatus": "publish",
  "render": { "entry": "page.tsx", "data": "data.php" }
}

render est explicite. Un répertoire contenant un fichier index.php et un fichier page.tsx, mais pas de fichier render, reste une page ordinaire ; ainsi, l’ajout d’un moteur de rendu ne provoque jamais le rendu en double d’une page existante. Les formes sont les suivantes :

Valeur Signification
"page.tsx" Entrée seule, sans chargeur de données
{ "entry": "page.tsx", "data": "data.php" } Entrée et chargeur de données
{ "entry": "page.tsx", "renderer": "react" } Entrée avec un identifiant de moteur de rendu explicite
false Aucun moteur de rendu, même si une valeur par défaut de collection en indique un

Les chemins sont résolus par rapport au répertoire de la page ou à la racine de la collection pour les entrées du chargeur. Ils doivent rester dans la source de découverte, sauf si blockstudio/pages/allow_external_loader_path l’autorise. Sans renderer, le moteur de rendu qui prend en charge l’extension de l’entrée est utilisé. Si render désigne une entrée ou un fichier de données manquant, un moteur de rendu inconnu ou une extension prise en charge par aucun moteur de rendu, il s’agit d’une erreur de découverte qui interrompt la réconciliation avant toute suppression.

Contenu stocké par la synchronisation

La synchronisation stocke un bloc blockstudio/page. Lorsque le répertoire de la page contient également une source index.*, cette source est analysée comme n’importe quelle source de page et devient les blocs internes du bloc, c’est-à-dire son emplacement :

HTML
<!-- wp:blockstudio/page /-->

<!-- wp:blockstudio/page -->
<!-- wp:paragraph -->
<p>[download_checkout]</p>
<!-- /wp:paragraph -->
<!-- /wp:blockstudio/page -->

Conservez dans l’emplacement le contenu géré par WordPress, comme les shortcodes. Une source constituée d’un seul shortcode, comme [download_checkout], est stockée sous forme de bloc core/shortcode, de sorte qu’aucun paragraphe ne soit ajouté autour de son résultat. Elle reste dans post_content, ce qui permet aux vérifications has_shortcode() de la détecter ; les blocs d’emplacement identifiés par clé fusionnent avec les modifications de l’éditeur comme le font les blocs imbriqués identifiés par clé ; et do_shortcode développe les shortcodes une seule fois, selon sa priorité habituelle the_content, après que le moteur de rendu leur a donné leur cadre.

La définition du rendu est stockée avec l’article sous forme de chemins theme: transportables. L’empreinte de la page couvre la définition, et non les octets de l’entrée ou du chargeur de données : la modification de page.tsx ou data.php laisse l’article inchangé et est visible par les visiteurs grâce au rendu et au graphe prérendu statique, qui enregistre l’entrée, le chargeur de données et chaque fichier signalé par le moteur de rendu.

Enregistrer un moteur de rendu

Enregistrez les moteurs de rendu sur l’action blockstudio/pages/renderers. Elle est déclenchée une fois par requête, avant la première découverte ou le premier rendu, afin que wp bs pages sync et les requêtes du frontend voient le même registre.

PHP
add_action(
	'blockstudio/pages/renderers',
	static function (): void {
		Blockstudio\Page_Renderers::register(
			'react',
			array(
				'extensions' => array( 'tsx' ),
				'layouts'    => array( 'layout.tsx' ),
				'render'     => 'my_theme_render_page',
			)
		);
	}
);

Les identifiants de moteur de rendu sont en minuscules. Une extension ou un nom de mise en page ne peut appartenir qu’à un seul moteur de rendu, et layout.php reste la mise en page propre à Blockstudio. La fonction appelable reçoit une requête :

Clé Valeur
kind page, ou layout pour une mise en page de moteur de rendu mise en page
renderer Identifiant du moteur de rendu
entry Chemin absolu de l’entrée
data Chemin absolu du chargeur de données, ou null
page Données canoniques de la page, y compris meta
post_id ID de l’article WordPress
slot Contenu rendu de l’emplacement, ou contenu de la page pour une mise en page
context frontend, rest, feed ou cli

Il renvoie le HTML, les fichiers lus lors du rendu et les ressources facultatives :

PHP
function my_theme_render_page( array $request ): array {
	return array(
		'html'         => '<main>...</main>',
		'dependencies' => array( '/abs/path/to/a/file/the/render/read.tsx' ),
		'assets'       => array( array( 'path' => '/abs/path/to/page.js' ) ),
	);
}

context provient du type de requête et jamais du visiteur ; un moteur de rendu ne peut donc pas rompre la parité des octets entre les utilisateurs connectés et anonymes en le lisant. Si un moteur de rendu échoue, il lève une exception : la page n’affiche pas un corps vide. Dans l’aperçu de l’éditeur REST, le bloc affiche plutôt l’erreur sous forme d’avis. Après un rendu réussi, l’action blockstudio/pages/rendered reçoit la page, le HTML et ses dépendances.

assets répertorie les fichiers de script et de style dont la page a besoin. Ils bénéficient du traitement des ressources de bloc (la convention *.inline.*, les modules ES, la minification et ?ver), et la page les imprime une seule fois, via le même tampon que celui qui imprime les ressources de bloc, de sorte qu’une page pré-rendue les inclut. Une ressource peut définir version pour remplacer sa valeur ?ver. Le code exécuté hors d’un moteur de rendu peut utiliser le même canal via Blockstudio\Assets::register_owner(), qui renvoie le commentaire marqueur à imprimer.

Éditeur

Dans l’éditeur, blockstudio/page affiche un aperçu de la page rendu côté serveur, avec l’emplacement sous forme de blocs internes qui suivent le templateLock de la page. Le bloc ne peut pas être inséré, dupliqué ni imbriqué dans un autre bloc.

Collections de pages

Une collection est un dossier doté d’un manifeste pages.json. Elle regroupe plusieurs sources de pages sous un même slug de collection, applique des valeurs par défaut, prend en charge les chemins imbriqués et peut enregistrer automatiquement un type d’article dédié.

Code
pages/
  docs/
    pages.json
    layout.php
    index.md
    guide/
      install/
        index.md
    reference/
      page.json
      index.md
    loader.php
JSON
{
  "collection": "docs",
  "title": "Documentation",
  "postType": "bs_docs",
  "postTypeArgs": {
    "label": "Docs",
    "rewrite": {
      "slug": "docs"
    },
    "supports": ["title", "editor", "page-attributes"]
  },
  "defaults": {
    "postStatus": "publish",
    "templateLock": "contentOnly"
  }
}
Propriété Type Description
collection / slug / name string Identifiant de la collection. collection est la forme la plus claire et devient la base publique URL.
title string Titre de collection lisible par un humain.
postType string Type de publication pour les pages générées. Par défaut, page. S’il n’existe pas, Blockstudio l’enregistre.
postTypeArgs object Arguments transmis à register_post_type() lorsque Blockstudio enregistre le type de publication de la collection.
defaults object Propriétés de page par défaut appliquées à chaque page de la collection. Une valeur render par défaut s’applique à une page uniquement si son entrée existe dans le répertoire des pages.
scope string collection (par défaut) ou site. Voir Collections de sites.
meta object Métadonnées personnalisées de la collection. Les clés de manifeste inconnues sont également enregistrées dans meta.

Les chemins des pages d’une collection sont des chemins logiques. Une page avec path: "guide/install" est synchronisée en tant que page enfant de guide, et guide est synchronisée en tant que page enfant de la racine de la collection si ces pages parentes existent.

Si une collection hiérarchique contient une page imbriquée, mais qu’aucune source de page parente intermédiaire n’existe, Blockstudio génère une page conteneur vide pour ce chemin afin de compléter la hiérarchie WordPress. Les types d’articles non hiérarchiques (sans prise en charge de page-attributes comme parent) ne génèrent pas de conteneurs vides. Ils utilisent le chemin de collection enregistré ; des chemins imbriqués comme guide/install et setup/install peuvent donc coexister même s’ils se terminent tous deux par install.

Types d’articles et URL des collections

Définissez postType dans le manifeste de la collection pour synchroniser toutes ses pages avec ce type d’article. Il n’est pas nécessaire de répéter la même valeur dans defaults. Chaque page peut toujours remplacer postType dans l’en-tête ou page.json.

Lorsque le type d’article n’existe pas, Blockstudio l’enregistre avec show_in_rest: true, une configuration d’éditeur semblable à celle des pages et le slug de la collection comme base publique URL. postTypeArgs peut remplacer les arguments d’enregistrement. Les règles de réécriture du type d’article de la collection sont actualisées automatiquement lorsque les types d’articles enregistrés ou les arguments de réécriture changent ; il n’est donc pas nécessaire de réenregistrer les permaliens WordPress.

Les URL des collections utilisent le slug de la collection suivi du chemin logique path de chaque page :

Chemin source Public URL
path: "." /docs/
path: "getting-started" /docs/getting-started/
path: "guide/install" /docs/guide/install/

Ce modèle URL fonctionne avec les types de publication de collection hiérarchiques et non hiérarchiques. Blockstudio redirige également les URL en double, telles que /docs/docs/ ou /docs/docs/getting-started/, vers l’URL canonique URL.

Les pages de collection exposent le Markdown brut aux mêmes URL (voir Markdown brut).

Si vous faites passer une collection de postType: "page" à un type de publication personnalisé, Blockstudio migre sur place les publications de collection déjà synchronisées lorsque leur identité de page enregistrée correspond. Les ID de publication, les métadonnées et le contenu existant sont ainsi conservés, tout en évitant les doublons avec l’ancien type. Les publications de collection obsolètes sont nettoyées, quel que soit leur statut, selon le filtre blockstudio/pages/orphan_action.

Collections de sites

Un manifeste contenant "scope": "site" regroupe toutes les pages situées en dessous sans en faire des pages de collection. Utilisez-le à la racine de l’arborescence des pages d’un site pour appliquer des valeurs par défaut communes et répertorier les pages du site avec blockstudio_page_tree( 'my-site' ).

JSON
{
  "collection": "my-site",
  "title": "My Site",
  "scope": "site",
  "defaults": {
    "postStatus": "publish",
    "templateLock": "all",
    "render": { "entry": "page.tsx", "data": "data.php" }
  }
}

Les pages d’une collection de site conservent exactement l’identité qu’elles ont sans le manifeste : l’ajout d’un manifeste à une arborescence existante ne met à jour aucune ligne de publication et ne crée ni ne met rien à la corbeille :

  • Les clés restent globales : Pages::get_page( 'home' ) et les clés de page stockées continuent de correspondre.
  • Les URL restent des URL de page WordPress. Aucune règle de réécriture de collection, aucun filtre de permalien ni aucune redirection avec double URL ne s’appliquent, et aucune page conteneur vide n’est générée.
  • Les chemins logiques, les identifiants, les pages parentes et les identités source sont ceux des pages autonomes, et les mises en page sont déterminées par l’ancêtre le plus proche.
  • Les manifestes pages.json imbriqués conservent leurs propres collections, et leurs sous-arborescences sont exclues de la collection de site.
  • Les valeurs par défaut s’appliquent à chaque page : une valeur render par défaut ne s’applique qu’aux pages dont le répertoire contient l’entrée correspondante ; les pages avec code court et Markdown conservent donc leurs sources.

Chargeurs de collections

Les collections peuvent inclure un loader.php local de confiance. Utilisez-le lorsque les pages de collection proviennent d’une autre source locale, comme un dossier de documentation externe, un package ou un manifeste généré.

Le chargeur s’exécute lors de la découverte et de la synchronisation explicites des pages. Il doit être déterministe et local. Évitez de récupérer du contenu distant depuis loader.php, car cela rendrait la synchronisation du déploiement dépendante de ce service.

PHP
<?php

return array(
  'meta' => array(
    'source' => 'loader',
  ),
  'paths' => array(
    __DIR__ . '/external-docs',
    array(
      'path' => __DIR__ . '/cli-docs',
      'prefix' => 'cli',
      'meta' => array(
        'doc_set' => 'cli',
      ),
    ),
  ),
  'pages' => array(
    array(
      'name' => 'docs-api',
      'title' => 'API',
      'path' => 'api',
      'content' => "# API\n\nGenerated markdown content.",
      'contentType' => 'markdown',
    ),
    array(
      'name' => 'docs-template',
      'title' => 'Template',
      'path' => 'template',
      'file' => __DIR__ . '/template.md',
    ),
  ),
);

Un chargeur peut renvoyer un tableau contenant les clés pages, meta et paths :

Clé Description
pages Liste de tableaux de pages. Chaque page accepte les mêmes clés reconnues que le page.json et le frontmatter Markdown.
meta Métadonnées fusionnées dans le tableau meta de chaque page générée par le chargeur.
paths Répertoires locaux supplémentaires à explorer dans le cadre de cette collection. Les entrées peuvent être des chaînes ou des objets de chemin.
render Définition de rendu pour chaque page Markdown découverte à partir de paths.

Pour simplifier, le chargeur peut renvoyer directement une liste de tableaux de pages.

Les entrées de page du chargeur peuvent fournir le contenu de plusieurs façons :

Forme Description
markdown Contenu Markdown intégré.
html Contenu HTML intégré.
content + contentType Contenu intégré générique. contentType doit correspondre à markdown ou html.
file Source provenant d’un fichier local. Le type est déduit de l’extension, sauf si contentType est défini.
template Alias de file.

Les références de fichiers du chargeur peuvent pointer vers des sources PHP, Blade, Twig, Markdown ou HTML. Les chemins relatifs sont résolus depuis la racine de la collection. Les chemins absolus et ceux situés hors de la racine de la collection ne sont autorisés que si le filtre blockstudio/pages/allow_external_loader_path le permet.

Par défaut, les pages du chargeur utilisent generated: true. Lorsqu’une page générée par le chargeur disparaît de ses résultats, Blockstudio considère la publication synchronisée comme orpheline lors de la synchronisation suivante ; elle est nettoyée selon le filtre blockstudio/pages/orphan_action.

Les répertoires listés dans paths sont explorés comme les dossiers de collection habituels. Ils peuvent contenir des fichiers Markdown ou des dossiers page.json. Si ces chemins sont situés hors de la racine de la collection, le même filtre de chemins externes s’applique.

Utilisez une entrée sous forme de chaîne si le répertoire externe doit conserver ses propres chemins logiques. Utilisez une entrée sous forme d’objet si le répertoire doit être monté sous un préfixe de chemin de collection :

PHP
'paths' => array(
  array(
    'path' => __DIR__ . '/cli-docs',
    'prefix' => 'cli',
    'meta' => array(
      'doc_set' => 'cli',
    ),
  ),
),

Avec cette configuration, cli-docs/index.md devient path: "cli" et cli-docs/getting-started.md devient path: "cli/getting-started" dans la collection. Les préfixes évitent aussi les collisions entre noms de pages générés, ce qui permet à plusieurs répertoires montés de contenir chacun index.md ou getting-started.md. Définissez preserveNames sur true dans l’objet de chemin si vous souhaitez conserver les valeurs name explicites des métadonnées de début de fichier page.json ou Markdown.

Propriétés de l’objet de chemin :

Propriété Type Description
path string Répertoire local à explorer. Les chemins relatifs sont résolus à partir de la racine de la collection.
prefix string Préfixe de chemin logique facultatif dans la collection.
preserveNames boolean Conserver les noms de page explicites au lieu de générer des noms à partir du chemin préfixé. Par défaut, false lorsque prefix est défini.
meta object Métadonnées fusionnées dans chaque page découverte à partir de ce chemin. Les métadonnées de page prévalent en cas de doublon de clé.
render string|object Définition de rendu pour les pages Markdown de ce chemin, qui remplace celle du chargeur render.

Rendu de Markdown via un composant

Avec render, les pages Markdown découvertes par un chargeur sont rendues par un moteur de rendu de page au lieu d’être stockées sous forme de blocs :

PHP
<?php

return array(
  'paths'  => array( __DIR__ . '/external-docs' ),
  'render' => array(
    'entry' => __DIR__ . '/document.tsx',
    'data'  => __DIR__ . '/document.php',
  ),
);

Elles restent des pages Markdown : le type de contenu, le chemin du contenu, les réponses .md et le frontmatter ne changent pas. La synchronisation stocke un bloc blockstudio/page dont le HTML interne contient le Markdown converti, assaini si la collection assainit son contenu, au lieu de blocs analysés ; post_content conserve ainsi le texte du document. Le moteur de rendu reçoit ce HTML comme emplacement et peut lire la source depuis page.content_path. Les chemins relatifs sont résolus à partir de la racine de la collection ; le filtre de chemin externe s’applique comme pour les chemins. Une page dont le frontmatter définit son propre render ou render: false est exclue.

Mises en page

Un fichier layout.php enveloppe le rendu frontend d’une page basée sur un fichier. Il ne remplace pas le post_content synchronisé stocké dans WordPress et n’enveloppe pas le canevas de l’éditeur. La mise en page ne s’exécute que lors des requêtes frontend pour une page individuelle.

Pour les collections, placez layout.php à côté de pages.json afin d’envelopper chaque page frontend de cette collection :

PHP
<?php $current = blockstudio_current_page(); ?>

<main class="docs-layout">
  <aside>
    <?php foreach (blockstudio_page_tree('docs') as $item) : ?>
      <?php $is_current = ($item['post_id'] ?? null) === ($current['post_id'] ?? null); ?>
      <a
        href="<?php echo esc_url($item['permalink'] ?? '#'); ?>"
        <?php echo $is_current ? 'aria-current="page"' : ''; ?>
      >
        <?php echo esc_html($item['title']); ?>
      </a>
    <?php endforeach; ?>
  </aside>

  <article>
    <?php echo blockstudio_page_content(); ?>
  </article>
</main>

blockstudio_page_content() affiche le corps de la page que WordPress rendrait normalement via the_content. Si une mise en page n’affiche pas blockstudio_page_content(), le contenu de la page est volontairement masqué.

Les mises en page peuvent utiliser les fonctions d’assistance de page :

PHP
blockstudio_current_page();
blockstudio_page_collection('docs');
blockstudio_pages('docs');
blockstudio_page_tree('docs');
blockstudio_page_children('docs-guide', 'docs');
blockstudio_page_content();

Les pages imbriquées hors collection peuvent également hériter de la mise en page layout.php de l’ancêtre le plus proche dans l’arborescence pages. Pour les pages de collection, la mise en page racine de la collection est enregistrée sur chaque publication synchronisée et suivie dans l’empreinte de la page ; ses modifications sont donc prises en compte lors de la synchronisation suivante.

Mises en page de moteur de rendu

Une mise en page peut également être une entrée de moteur de rendu, par exemple layout.tsx pour un moteur de rendu qui enregistre layouts: ["layout.tsx"]. Elle se trouve aux mêmes emplacements que layout.php, et un layout.data.php facultatif placé à côté sert de chargeur de données. Au moment du rendu, le moteur de rendu reçoit kind: "layout" et le contenu de la page rendu sous la forme de slot, avec la même priorité the_content que layout.php. Un répertoire peut contenir layout.php ou une mise en page de moteur de rendu, mais pas les deux ; la présence des deux constitue une erreur de découverte. L’échec d’une mise en page déclenche blockstudio/pages/layout_error et laisse le contenu de la page sans enveloppe, comme pour layout.php.

Mode d’édition des blocs

La propriété blockEditingMode définit la manière dont les blocs peuvent être modifiés dans l’éditeur. Définissez une valeur par défaut au niveau de la page dans page.json, puis remplacez-la pour chaque élément dans le modèle :

JSON
{
  "name": "about",
  "title": "About Us",
  "templateLock": "all",
  "blockEditingMode": "disabled"
}
HTML
<h1 blockEditingMode="contentOnly">Editable Title</h1>
<p>This paragraph inherits "disabled" from the page default.</p>
<block name="core/buttons" blockEditingMode="default">
  <block name="core/button" url="/contact">Fully editable button</block>
</block>
Valeur Description
"default" Édition complète. Les blocs peuvent être sélectionnés, déplacés et modifiés.
"contentOnly" Édition du texte uniquement. Le texte des blocs peut être modifié, mais leurs réglages et leur structure sont verrouillés.
"disabled" Aucune édition. Les blocs sont entièrement non interactifs.

Les remplacements par élément sont définis sous forme d’attributs HTML sur n’importe quel élément (<h1>, <p>, <div>, etc.) ou sur les éléments <block>. Les blocs conteneurs ancêtres des éléments concernés sont automatiquement définis sur contentOnly afin que leurs enfants restent accessibles. Cette propagation remonte de l’élément concerné jusqu’à la racine de la page : il suffit donc de définir blockEditingMode sur les éléments que vous souhaitez rendre modifiables.

Verrouillage du modèle

La propriété templateLock définit la manière dont les utilisateurs peuvent modifier la page dans l’éditeur :

Valeur Ajouter/Supprimer Déplacer Modifier le contenu
"all" Non Non Non
"insert" Non Oui Oui
"contentOnly" Non Non Oui
false Oui Oui Oui

Lorsqu’un templateLock est défini, Blockstudio désactive la possibilité de déverrouiller les blocs via le UI de l’éditeur.

Routes virtuelles

Certains documents ne sont associés à aucune publication : une référence de composant générée à partir de données, un catalogue ou un espace de compte. Enregistrez-les comme routes virtuelles au lieu d’ajouter vous-même un hook template_redirect :

PHP
add_action( 'init', function () {
    Blockstudio\Virtual_Routes::register(
        'components',
        function ( $component, string $rest ) {
            get_header();
            echo my_component_page( $component );
            get_footer();
        },
        [
            'prefix' => true,
            'match'  => fn ( string $rest ) => '' === $rest ? 'index' : my_component( $rest ),
            'title'  => fn ( $component ) => my_component_title( $component ),
            'urls'   => fn () => my_component_paths(),
        ]
    );
} );

Le chemin est relatif à la page d’accueil du site. Avec prefix, la route dessert également tous les chemins qu’elle englobe, et match reçoit le reste du chemin (une chaîne vide pour la route elle-même) et renvoie la valeur transmise au rappel de rendu, ou null pour laisser le URL à WordPress, qui répond alors à 404 comme d’habitude. Le rappel de rendu affiche le document ou le renvoie sous forme de chaîne ; title est une chaîne ou une fonction de rappel qui reçoit la valeur correspondante.

Pour une requête correspondante, Blockstudio empêche WordPress de la signaler comme 404 et redirect_canonical de la rediriger, efface l’état de page individuelle indiqué par la requête principale, envoie le statut (status, 200 par défaut) et effectue le rendu à la priorité template_redirect Virtual_Routes::PRIORITY. Cela se produit juste après l’ouverture du tampon de sortie de Blockstudio à Assets::BUFFER_PRIORITY : le document final reçoit donc ses ressources de blocs, ses ressources UI groupées et son Tailwind compilé, comme toute autre page, et ce avant redirect_canonical à la priorité 10. Un gestionnaire qui rend lui-même un document entier doit également s’exécuter après Assets::BUFFER_PRIORITY, sans quoi ce traitement est ignoré. Les chemins dans urls (par défaut, le chemin de la route elle-même, lorsqu’il ne s’agit pas d’une route préfixée) sont ajoutés aux compilations de prégénération statique, et Virtual_Routes::urls() les renvoie sous forme d’URL absolues pour un plan de site. Virtual_Routes::match( $path ) résout un chemin comme le ferait une requête.

Comportement de la synchronisation

Les publications de page ne sont modifiées que lors d’une opération de synchronisation explicite :

Shell
wp bs pages sync

La commande découvre l’inventaire complet des sources, crée ou met à jour les publications modifiées, supprime les orphelines confirmées, actualise le routage des collections et la configuration compilée templateFor, puis indique les modifications effectuées. Ajoutez --authoritative pour remplacer le contenu géré au lieu de préserver le contenu de l’éditeur associé à des clés, et --full pour signaler l’opération comme une réconciliation complète, quelle que soit l’identité de source enregistrée :

Shell
wp bs pages sync --authoritative --full

Les requêtes frontend, d’administration, AJAX, REST, cron et les requêtes génériques d’initialisation WP-CLI ne lancent pas la découverte complète des pages, ne consultent pas l’inventaire de réconciliation géré et n’écrivent pas de publications de page. Elles utilisent les publications WordPress déjà synchronisées, ainsi que la configuration compacte des collections et des modèles de type de publication enregistrée lors de la dernière opération explicite. Lors d’une première installation ou d’une mise à niveau à froid, les manifestes de collection peuvent être analysés une fois pour restaurer les métadonnées de routage ; cette initialisation en lecture seule ne synchronise jamais le contenu. Le point de terminaison d’actualisation Canvas authentifié et facultatif est une opération explicite de création API : Canvas l’appelle une fois à l’ouverture de l’espace de travail afin que les sources nouvellement ajoutées ou modifiées apparaissent dans l’inventaire initial. Le mode actif appelle le même point lorsque le changement d’une source de page est détecté.

Blockstudio\Pages::init() n’enregistre désormais que des hooks exécutés au moment de la requête. Les intégrations qui transmettaient auparavant un argument force à cette méthode doivent appeler Blockstudio\Pages::reconcile() ou exécuter wp bs pages sync à la place.

Pour éviter qu’une page soit écrasée après des modifications manuelles, définissez "sync": false dans page.json.

Emplacements source portables

Les fichiers de thème synchronisés sont stockés sous forme d’emplacements relatifs au thème plutôt que sous forme de chemins d’installation absolus. Les fichiers du thème enfant et du thème parent conservent des identités distinctes, même s’ils ont le même nom de fichier relatif. Les assistants de page renvoient toujours les valeurs absolues résolues template_path, content_path, layout_path et directory pour la requête en cours.

Cela permet à la synchronisation CLI et aux requêtes Web d’utiliser des racines de système de fichiers différentes, comme sur un hébergement cloisonné, sans perturber les réponses Markdown, les mises en page, l’analyse Tailwind ni le suivi des sources prérendues. Les chemins absolus de thème existants sont réancrés à la lecture lorsque le nom du répertoire du thème n’a pas changé. Aucune synchronisation, migration de base de données ni écriture de métadonnées au moment de la requête n’est nécessaire pour les lire ; la prochaine synchronisation explicite enregistrera les emplacements portables.

Un répertoire de thème qui est un lien symbolique, par exemple vers une copie de travail de développement, enregistre les mêmes emplacements theme:, que la source soit lue via le lien symbolique ou via sa cible, et les résout vers le répertoire de thème configuré.

Les fichiers situés en dehors des thèmes enfant et parent actifs restent pris en charge à leurs chemins absolus configurés, sous réserve des restrictions open_basedir de PHP. Ils ne sont pas automatiquement déplaçables : après avoir déplacé une source externe, mettez à jour son chemin configuré et lancez une synchronisation explicite.

Propriété des champs de publication

postStatus définit le statut initial. Les synchronisations suivantes préservent les statuts brouillon, en attente, privé, publié et planifié existants, y compris avec --authoritative. Un brouillon n’est pas republié simplement parce que son fichier indique postStatus: "publish". Le comportement existant de récupération des éléments orphelins reste inchangé : une synchronisation explicite restaure une publication gérée mise à la corbeille lorsque sa source est présente. Verrouillez la page ou désactivez la synchronisation pour empêcher cette restauration.

Le fichier reste la source de référence pour le titre, le slug, le type de publication, le parent et l’ordre configuré dans le menu. Les modifier dans WordPress ne change pas la définition de la source. La prochaine synchronisation explicite réapplique les valeurs du fichier et nomme les champs concernés dans pages.<name>.overwritten, avec un avertissement dans la sortie de tableau de CLI. Les permissions natives de WordPress s’appliquent toujours, y compris son slug vide pour les publications en attente lorsque l’utilisateur qui synchronise ne peut pas les publier.

Utilisez blockstudio/pages/update_post_data pour une intégration qui gère explicitement une autre politique de statut. Les blocs avec clés préservent le contenu des blocs géré par l’éditeur ; les clés ne changent pas la propriété du titre ou du slug de la publication.

Pour les pages de collection, les empreintes prennent en compte le manifeste, le chargeur, la source de la page, le fichier de mise en page, les métadonnées et les chemins sources associés. La prochaine synchronisation explicite appliquera les modifications apportées à ces entrées.

Lorsqu’une source de collection est supprimée, Blockstudio supprime la page générée afin que les anciennes pages de collection ne restent pas après la disparition du fichier source. Par défaut, les pages de collection orphelines sont déplacées dans la corbeille. Utilisez blockstudio/pages/orphan_action pour renvoyer trash, delete ou keep.

Lors des requêtes frontend, Blockstudio hydrate le registre de pages à partir des publications publiées déjà synchronisées. Les pages en brouillon et privées sont disponibles dans l’administration et dans les contextes de synchronisation, mais les fonctions d’assistance frontend n’hydratent que les pages publiées.

Réconciliation du déploiement

Blockstudio\Pages::reconcile() est le point d’entrée de déploiement PHP. Il découvre l’inventaire complet attendu, compare les empreintes des sources et du moteur de synchronisation, puis renvoie un rapport lisible par machine :

PHP
$report = Blockstudio\Pages::reconcile([
  'authoritative' => true,
  'plan_valid' => true,
  'source' => [
    'commit' => $commit,
    'dirtyHash' => $dirtyHash,
  ],
  'renames' => [
    [
      'from' => 'pages/old/index.php',
      'to' => 'pages/new/index.php',
    ],
  ],
]);

Le rapport contient discovered, created, updated, unchanged, locked, preserved, removed, removedPages, failed, fullReconciliation, les résultats par page, les erreurs de découverte et un sourceIdentity déterministe.

Les pages verrouillées comportent status: "locked" et sont comptabilisées séparément des pages inchangées. removedPages répertorie pour chaque page supprimée son name, son key, son postId et son action réel (trash ou delete) ; les publications conservées ou déjà mises à la corbeille ne sont pas comptabilisées comme nouvellement supprimées. La sortie de tableau de CLI nomme également les pages créées, mises à jour, verrouillées, supprimées et dont le contenu a été préservé, avec leurs identifiants de publication.

Après l’analyse et la fusion par clés, une publication finale identique n’appelle pas wp_update_post(), ne modifie pas post_modified, ne crée pas de révision et ne déclenche pas les hooks de mise à jour de publication. Son résultat est unchanged. Lorsque le contenu de la source diffère du contenu avec clés géré par l’éditeur, preserved: true identifie cette décision et le compteur de preserved au niveau supérieur l’inclut. La nouvelle empreinte de la source et les métadonnées de gestion sont toujours enregistrées, de sorte que la prochaine synchronisation sans changement ne fasse rien. preserved est un indicateur supplémentaire, et non un statut exclusif : une page peut préserver le contenu avec clés tout en mettant à jour un titre géré par le fichier ou en ajoutant un autre bloc.

authoritative: true peut supprimer un verrou de synchronisation de page et remplace le contenu par la définition du fichier au lieu de préserver le contenu de l’éditeur associé à des clés. Laissez-le sur false pour une synchronisation explicite normale. plan_valid: false, full: true, broad: true, une identité de source précédente manquante ou une empreinte du moteur de synchronisation modifiée signalent l’opération comme une réconciliation complète (fullReconciliation dans le rapport). Dans tous les cas, chaque opération compare l’inventaire complet. Les enregistrements de renommage Git servent uniquement d’indications d’identité. Ils ne remplacent jamais la comparaison de l’inventaire complet.

Lorsque les empreintes et les chemins d’exécution ne changent pas, aucune publication ni métadonnée de publication n’est écrite et aucun hook de mise à jour n’est déclenché. Si une source inchangée est déplacée vers un nouveau répertoire de version, la réconciliation actualise uniquement les chemins enregistrés du modèle, du contenu, de la mise en page et du répertoire ; elle ne met pas à jour post_content ni l’horodatage de modification de la publication. Les pages gérées manquantes ne sont supprimées qu’une fois la réconciliation complète terminée sans erreur de découverte ni d’écriture de page.

Une réconciliation directe API ne marque pas un déploiement comme réussi. Après avoir activé et vérifié l’artefact statique et les routes correspondants, enregistrez explicitement l’identité renvoyée :

PHP
Blockstudio\Pages::store_successful_source_identity(
  $report['sourceIdentity']
);

wp bs pages sync enregistre l’identité renvoyée après une opération réussie. L’initialisation ordinaire WP-CLI enregistre uniquement les types de publication et les règles de réécriture de collection persistés. Elle ne découvre ni ne synchronise les pages.

Épinglage de l’ID de publication

Par défaut, WordPress attribue automatiquement les ID de publication. Si une page est supprimée puis recréée, son ID change, ce qui rompt les références externes telles que les menus ou les liens codés en dur.

Utilisez postId pour épingler une page à un ID spécifique :

JSON
{
  "name": "about",
  "title": "About Us",
  "postId": 42
}

Lors de la création de la page, Blockstudio transmet l’ID à WordPress via import_id. Si l’ID est disponible, WordPress l’utilise exactement. Si l’ID est déjà utilisé par une publication sans rapport, WordPress attribue silencieusement un nouvel ID automatiquement.

Lorsqu’il recherche des pages existantes, Blockstudio vérifie d’abord l’ID épinglé, avant les métadonnées ou le slug. Ainsi, si une page est supprimée puis synchronisée à nouveau, elle récupère le même ID.

Fusion des blocs associés à des clés

Par défaut, lorsqu’un fichier de modèle change, Blockstudio remplace tout le contenu de la publication par le nouveau modèle. Toutes les modifications effectuées dans l’éditeur WordPress sont alors perdues.

Ajoutez un attribut key aux blocs pour préserver les modifications des utilisateurs entre les synchronisations de modèles. Lorsqu’un modèle contient des blocs associés à des clés, Blockstudio fusionne les modifications du modèle avec le contenu existant de la publication au lieu de le remplacer.

Ajout de clés

Utilisez l’attribut key sur n’importe quel élément HTML ou élément <block> :

HTML
<h1 key="title">Default Title</h1>
<p key="intro">Default intro text.</p>

<div key="features">
  <p>First feature.</p>
  <p>Second feature.</p>
</div>

<block name="core/cover" key="hero" url="https://example.com/bg.jpg">
  <h2>Hero Title</h2>
  <p>Hero description.</p>
</block>

<block
  name="acme/testimonial"
  key="featured-quote"
  quote="Default quote"
/>

Les clés doivent être uniques dans l’ensemble du modèle. Une clé protège tout le bloc et son contenu. Il n’est pas nécessaire d’associer des clés aux enfants individuels d’un bloc parent qui en possède une. Les blocs associés à des clés peuvent être déplacés à n’importe quel emplacement ou niveau d’imbrication entre deux mises à jour du modèle ; leur contenu utilisateur est conservé.

Les clés fonctionnent de la même manière pour les blocs personnalisés Blockstudio. La key correspond aux métadonnées structurelles de Page Sync ; les valeurs des champs personnalisés restent des attributs Blockstudio ordinaires. Lorsque l’éditeur modifie ces champs, la synchronisation ultérieure du modèle conserve les valeurs de l’éditeur tout en appliquant les modifications indépendantes du modèle. Les pages créées par des versions antérieures, dont la clé se trouve dans les données du champ personnalisé, sont migrées automatiquement lors de la prochaine synchronisation.

Fonctionnement de la fusion

Lorsqu’un fichier de modèle change et que la page est synchronisée à nouveau :

Bloc Comportement
Bloc associé à une clé Le contenu utilisateur et les valeurs de champ Blockstudio sont préservés. Les attributs et la structure gérés par le modèle sont appliqués.
Bloc sans clé Remplacé entièrement par la version du modèle (comme en l’absence de clés)

Exemples

Les modifications de l’utilisateur sont préservées dans les blocs associés à des clés :

  1. Le modèle définit <p key="intro">Default intro.</p>
  2. L’utilisateur modifie le paragraphe dans l’éditeur et le remplace par « Texte d’introduction personnalisé. »
  3. Le développeur met à jour le modèle, ajoute un bloc et modifie la mise en page
  4. Lors de la synchronisation, le paragraphe conserve « Texte d’introduction personnalisé. » et la nouvelle mise en page est appliquée

Les attributs du modèle restent appliqués :

  1. Le modèle contient un bloc de couverture avec key="hero" et un attribut url
  2. Le développeur remplace l’attribut url de la couverture par une nouvelle image d’arrière-plan
  3. Lors de la synchronisation, la nouvelle image d’arrière-plan est appliquée, tandis que les modifications de contenu de l’utilisateur à l’intérieur de la couverture sont préservées

Cas particuliers

Scénario Comportement
Ajout d’un nouveau bloc associé à une clé dans le modèle Apparaît avec le contenu par défaut du modèle
Suppression d’un bloc associé à une clé du modèle Supprimé de la publication
Modification du type de bloc (même clé) Le modèle l’emporte entièrement, sans fusion du contenu
Clés en double La deuxième occurrence est traitée comme un bloc sans clé
Modèle sans clé Remplacement complet (comme en l’absence de clés)
Synchronisation forcée Remplacement complet ; les clés sont ignorées
Publication verrouillée Aucune synchronisation

Association aux commandes d’édition

Les clés, templateLock et blockEditingMode vous permettent de contrôler précisément ce que les clients peuvent faire ou non. Voici quelques modèles de flux de travail courants.

Page entièrement verrouillée

Le développeur contrôle tout. La page est une mise en page statique que les clients ne peuvent pas modifier. Cela convient aux pages juridiques, aux conditions d’utilisation et à toute page qui ne doit être modifiée que par du code.

JSON
{
  "name": "terms",
  "title": "Terms of Service",
  "templateLock": "all"
}
HTML
<h1>Terms of Service</h1>
<p>Last updated: January 2025</p>
<p>These terms govern your use of our service...</p>

Aucune clé n’est nécessaire. Le modèle est l’unique source de vérité. Chaque synchronisation remplace entièrement la page.

Mise en page verrouillée avec contenu modifiable

Le modèle le plus courant. Verrouillez la structure de la page pour empêcher les clients d’ajouter, de supprimer ou de réorganiser des blocs, tout en leur permettant de modifier le texte à certains endroits. Les clés garantissent que leurs modifications sont conservées lors des mises à jour du modèle.

JSON
{
  "name": "landing",
  "title": "Landing Page",
  "templateLock": "all",
  "blockEditingMode": "disabled"
}
HTML
<block name="core/cover" key="hero" url="https://example.com/bg.jpg">
  <h1 blockEditingMode="contentOnly">Edit This Title</h1>
  <p blockEditingMode="contentOnly">Edit this description.</p>
</block>

<div key="features">
  <h2>Features</h2>
  <p blockEditingMode="contentOnly">Editable feature intro.</p>
</div>

<block name="core/buttons">
  <block name="core/button" url="/contact">Contact Us</block>
</block>

Le client peut modifier le titre principal, la description et l’introduction des fonctionnalités. Rien d’autre. Le texte du bouton, URL et l’image d’arrière-plan de couverture sont contrôlés par le développeur. Lorsque le développeur met à jour le modèle (e.g, ajoute un deuxième bouton), les sections identifiées par une clé conservent le texte du client.

Modèle évolutif avec contenu préservé

Pour les pages qui évoluent au fil du temps. Le développeur ajoute de nouvelles sections au modèle, et chaque synchronisation ajoute le nouveau contenu sans toucher à ce que le client a déjà personnalisé.

HTML
<h1 key="title">Welcome</h1>
<p key="intro">Our introduction.</p>
<div key="services">
  <h2>Our Services</h2>
  <p>We offer great things.</p>
</div>
HTML
<h1 key="title">Welcome</h1>
<p key="intro">Our introduction.</p>
<div key="services">
  <h2>Our Services</h2>
  <p>We offer great things.</p>
</div>
<div key="testimonials">
  <h2>Testimonials</h2>
  <p>What our clients say.</p>
</div>
<block name="core/buttons">
  <block name="core/button" url="/contact">Get in Touch</block>
</block>

La nouvelle section de témoignages et le bouton apparaissent lors de la synchronisation. Les modifications du client au titre, à l’introduction et aux services ne sont pas touchées.

Échafaudage ponctuel

Créez une page avec une structure de départ, puis transmettez-la entièrement. Définissez sync sur false afin que la synchronisation normale ne crée ni ne mette jamais à jour la page, puis créez-la une fois avec Blockstudio\Pages::force_sync('blog'). Ensuite, le client est entièrement propriétaire de la page.

JSON
{
  "name": "blog",
  "title": "Blog",
  "sync": false
}
HTML
<h1>Our Blog</h1>
<p>Welcome to our blog. Start writing!</p>

wp bs pages sync ignore cette page, donc force_sync() la crée une seule fois. Ensuite, le client peut ajouter, supprimer et réorganiser librement les blocs. Les modifications du modèle sont ignorées.

Liaisons de blocs

Une autre solution que la fusion par clé consiste à utiliser les WordPress Block Bindings API de core pour relier les blocs aux métadonnées des publications. Il ne s’agit pas d’une fonctionnalité Blockstudio : c’est une WordPress API native. Blockstudio transmet simplement l’attribut metadata au balisage du bloc généré. Le contenu réside dans les métadonnées de la publication plutôt que dans le balisage du bloc ; les synchronisations de modèles peuvent donc remplacer librement le balisage, car l’éditeur lit les métadonnées et non innerHTML.

Transmettez l’attribut metadata à tout élément HTML ou <block> :

HTML
<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 text.
</p>

<img
  metadata='{"bindings":{"url":{"source":"core/post-meta","args":{"key":"hero_image"}},"alt":{"source":"core/post-meta","args":{"key":"hero_image_alt"}}}}'
/>

Les clés de métadonnées doivent être enregistrées avec show_in_rest activé :

PHP
register_post_meta( 'page', 'hero_title', array(
    'show_in_rest'  => true,
    'single'        => true,
    'type'          => 'string',
    'default'       => 'Default Title',
) );

Clés et liaisons

Aspect Clés Liaisons
Contenu stocké dans Balisage du bloc (post_content) Métadonnées de publication (wp_postmeta)
Conservé lors de la synchronisation du modèle Oui (fusion par clé) Oui (les données résident dans les métadonnées)
Interrogeable via WP_Query Non Oui (meta_query)
Disponible dans REST API Non Oui
Enregistrement requis Non Oui (register_post_meta)
L’utilisateur peut déplacer les blocs Non (le modèle réimpose la structure) Non (le modèle réimpose la structure)

Les deux approches peuvent être utilisées dans le même modèle. Utilisez les clés pour les sections dont la structure des blocs est importante (e.g, un groupe avec plusieurs blocs enfants). Utilisez les liaisons pour les champs individuels dont vous souhaitez également rendre les données accessibles en dehors de l’éditeur de blocs.

Modèles de types de publication

Utilisez templateFor pour définir une page comme modèle par défaut d’un type de publication :

JSON
{
  "name": "product-template",
  "title": "Product Template",
  "templateFor": "product",
  "templateLock": "insert"
}

Toute nouvelle publication de ce type commencera avec la structure de blocs définie.

Chemins personnalisés

Par défaut, Blockstudio analyse get_template_directory() . '/pages'. Ajoutez des chemins supplémentaires avec le filtre :

PHP
add_filter( 'blockstudio/pages/paths', function( $paths ) {
    $paths[] = get_stylesheet_directory() . '/custom-pages';
    $paths[] = MY_PLUGIN_DIR . '/pages';
    return $paths;
} );

Les intégrations d’exécution qui composent des fichiers provenant de plusieurs racines peuvent remplacer l’analyse du système de fichiers par une source de découverte logique. Les manifestes de pages, les mises en page, les chargeurs et les modèles source sont alors résolus par chemin logique, même si les fichiers sélectionnés se trouvent dans différentes racines.

Filtres et actions

La découverte des pages, la synchronisation et le routage des collections exposent les points d’extension suivants :

Hook Type Description
blockstudio/pages/paths Filtre Ajouter des répertoires dans lesquels Blockstudio recherche des sources de pages.
blockstudio/pages/collection_post_type_args Filtre Ajuster les arguments de register_post_type() pour un CPT de collection.
blockstudio/pages/template_candidates Filtre Ajuster les noms de fichiers de modèles pris en compte pour une source de page.
blockstudio/pages/serve_markdown Filtre Activer ou désactiver les réponses Markdown brutes.
blockstudio/pages/orphan_action Filtre Renvoyer trash, delete ou keep pour le nettoyage des éléments orphelins.
blockstudio/pages/docs_allowed_html Filtre Ajuster les HTML autorisés pour le contenu généré de la documentation Markdown.
blockstudio/pages/allow_external_loader_path Filtre Autoriser le chargeur paths en dehors de la racine de la collection.
blockstudio/pages/manifest_scan_interval Filtre Définir l’âge maximal d’un cache de manifeste hérité antérieur à 7.6.2 pouvant initialiser la configuration d’exécution persistante lors d’une mise à niveau.
blockstudio/pages/create_post_data Filtre Modifier les données de publication avant la création d’une page synchronisée.
blockstudio/pages/update_post_data Filtre Modifier les données de publication avant la mise à jour d’une page synchronisée.
blockstudio/pages/sync_engine_inputs Filtre Ajouter une version d’analyseur, de correspondance ou de migration qui doit volontairement élargir le rapprochement une fois.
blockstudio/pages/post_created Action S’exécute après la création d’une publication de page synchronisée.
blockstudio/pages/post_updated Action S’exécute après la mise à jour d’une publication de page synchronisée.
blockstudio/pages/synced Action S’exécute une fois la synchronisation du registre de pages terminée.
blockstudio/pages/reconciled Action S’exécute après un rapprochement explicite et fournit son rapport lisible par machine.
blockstudio/pages/renderers Action Enregistrer les moteurs de rendu de pages avec Blockstudio\Page_Renderers::register(). Se déclenche une fois par requête.
blockstudio/pages/rendered Action S’exécute après le rendu d’une page de composant, avec la page, son HTML et ses dépendances.
blockstudio/pages/layout_error Action Se déclenche lorsqu’une mise en page ne peut pas être rendue, avec l’erreur, le chemin de la mise en page et la page.

PHP API

PHP
// Get all registered pages.
$pages = Blockstudio\Pages::pages();

// Get pages from one collection.
$docs = Blockstudio\Pages::pages('docs');

// Get the pages of one collection, sorted (same result as pages('docs')).
$docs = Blockstudio\Pages::in_collection('docs');

// Get a nested page tree.
$tree = Blockstudio\Pages::tree('docs');

// Get direct children for a page.
$children = Blockstudio\Pages::children('docs-guide', 'docs');

// Get collection metadata.
$collection = Blockstudio\Pages::collection('docs');

// Get a specific page.
$page = Blockstudio\Pages::get_page('about');

// Get the WordPress post ID for a page.
$postId = Blockstudio\Pages::get_post_id('about');

// Force sync a page explicitly (ignores fingerprints, locks, and sync: false).
Blockstudio\Pages::force_sync('about');

// Force sync all discovered pages explicitly.
Blockstudio\Pages::force_sync_all();

// Reconcile a complete deployment inventory without rewriting equal pages.
$report = Blockstudio\Pages::reconcile([
  'authoritative' => true,
  'plan_valid' => true,
  'source' => [
    'commit' => $commit,
    'dirtyHash' => $dirtyHash,
  ],
]);

// Store this only after the matching static artifact and routes verify.
Blockstudio\Pages::store_successful_source_identity($report['sourceIdentity']);

// Lock a page against non-authoritative reconciliation.
Blockstudio\Pages::lock('about');

// Unlock a page.
Blockstudio\Pages::unlock('about');

// Register a page renderer (inside the blockstudio/pages/renderers action).
Blockstudio\Page_Renderers::register('react', [
  'extensions' => ['tsx'],
  'layouts' => ['layout.tsx'],
  'render' => 'my_theme_render_page',
]);

// Find the renderer of an entry file.
$renderer = Blockstudio\Page_Renderers::for_entry('page.tsx');

// Register assets for rendered output and print the returned marker with it.
$marker = Blockstudio\Assets::register_owner('page-home', [$scriptPath]);

Consultez Rapprochement du déploiement pour la sémantique des arguments, les champs du rapport et la limite d’identité de source vérifiée.

Des fonctions d’assistance globales sont disponibles pour les modèles et les mises en page :

PHP
blockstudio_pages('docs');
blockstudio_page_tree('docs');
blockstudio_page_children('docs-guide', 'docs');
blockstudio_page_collection('docs');
blockstudio_page_content();
blockstudio_current_page();

Les tableaux de pages renvoyés par Blockstudio\Pages::pages(), Blockstudio\Pages::tree(), Blockstudio\Pages::children() et les fonctions d’assistance globales incluent l’identité de la publication synchronisée, les chemins source et modèle, les métadonnées de collection et de chemin, le type de contenu, la stratégie de synchronisation, le type et l’état de publication, la politique de modification, les métadonnées personnalisées et une clé permalink. Les métadonnées de collection sont chargées lors du dernier rapprochement explicite réussi. Les requêtes normales reconstruisent ces données d’exécution à partir de la configuration persistée et des métadonnées des publications synchronisées, sans lire les arbres de sources des pages. La classe Pages n’expose pas de méthode distincte pour les permaliens.

Créer des pages à partir de fichiers

Verrouillage des modèles, modes de modification des blocs, fusion par clés et contrôle des éléments que les clients peuvent modifier.