Seiten
Seiten sind dateibasierte Templates, die als Beiträge mit der WordPress-Datenbank synchronisiert werden.
Die Synchronisierung erfolgt explizit: Führe wp bs pages sync aus oder rufe die Pages-API auf, wenn du Änderungen an der Quelle übernehmen möchtest. Beim Laden des Frontends oder der WordPress-Administration werden weder alle Seiten vollständig ermittelt noch Seitenbeiträge geändert.
Seiten lassen sich als einzelner page.json-Ordner, als eigenständige Markdown oder als Sammlung mit einem pages.json-Manifest definieren. Sammlungen eignen sich für Dokumentationen, Wissensdatenbanken, Landingpage-Bibliotheken und andere Gruppen verschachtelter Seiten, die aus Dateien erstellt werden sollen.
page.json
Füge für eine mit JSON definierte Seite eine page.json-Konfigurationsdatei hinzu:
{
"name": "about",
"title": "About Us",
"slug": "about-us",
"postType": "page",
"postStatus": "publish",
"templateLock": "all"
}
Eigenschaften
| Eigenschaft | Typ | Standardwert | Beschreibung |
|---|---|---|---|
name |
string |
erforderlich | Eindeutige Kennung der Seite |
title |
string |
Automatisch aus dem Namen | Seitentitel |
slug |
string |
Wie der Name | URL-Slug der Seite |
path |
string |
"." |
Logischer Pfad innerhalb einer Sammlung |
order |
integer |
0 |
Menüreihenfolge des synchronisierten Beitrags |
postType |
string |
"page" |
WordPress-Beitragstyp |
postStatus |
string |
"draft" |
Status für neue Beiträge (publish, draft, pending, private) |
postId |
integer |
– | Seite mit einer bestimmten WordPress-Beitrags-ID verknüpfen |
blockEditingMode |
string |
– | Blockbearbeitungsmodus: "default", "contentOnly" oder "disabled" |
templateLock |
string|false |
"all" |
Sperrmodus: "all", "insert", "contentOnly" oder false |
templateFor |
string|null |
null |
Als Standardvorlage für einen Beitragstyp festlegen |
sync |
boolean |
true |
Gibt an, ob ein normaler expliziter Abgleich den Beitrag erstellen oder aktualisieren darf |
render |
string|object|false |
– | Seite mit einem registrierten Seiten-Renderer rendern (siehe Komponentenseiten) |
Zu den erkannten Schlüsseln in page.json, Frontmatter und Loader-Einträgen gehören blockEditingMode, collection, content, contentType, defaults, file, html, markdown, meta, name, order, path, postId, postStatus, postType, postTypeArgs, render, slug, template, templateFor, templateLock und title. Jeder oben nicht aufgeführte Schlüssel wird im Array meta der Seite gespeichert.
Inhaltsquellen
Eine Seitendefinition legt fest, welcher WordPress-Beitrag vorhanden sein soll. Die Inhaltsquelle bestimmt, welches Block-Markup in diesen Beitrag geschrieben wird.
Enthält ein Seitenordner ein page.json, sucht Blockstudio in dieser Reihenfolge nach einer passenden Quelldatei im selben Ordner:
| Datei | Verwendung |
|---|---|
index.php |
HTML-ähnliches Block-Markup, unverändert gelesen (PHP-Code wird nicht ausgeführt) |
index.blade.php |
Inhalt eines Blade-Templates |
index.twig |
Inhalt eines Twig-Templates |
index.md |
Markdown-Inhalt |
page.json kann statt einer Quelldatei im selben Ordner auch markdown oder html inline bereitstellen:
{
"name": "intro",
"title": "Intro",
"markdown": "# Intro\n\nThis page is generated from inline markdown."
}
{
"name": "notice",
"title": "Notice",
"html": "<h1>Notice</h1><p>This page is generated from inline HTML.</p>"
}
Sammlungen bieten zwei weitere Quellmodi:
- Markdown-Dateien, die direkt im Sammlungsbaum gefunden werden.
- Loader-Einträge, die von
loader.phpzurückgegeben werden.
Loader-Einträge können markdown, html oder content mit contentType verwenden. Sie können auch auf eine lokale file oder template verweisen. Bei Datei- und Template-Quellen wird der Typ anhand der Dateiendung ermittelt, sofern contentType nicht ausdrücklich festgelegt ist.
Unterstützte Werte für contentType sind php, blade, twig, markdown und html. Markdown wird zunächst in HTML umgewandelt und anschließend in native WordPress-Blöcke geparst. PHP-, Blade-, Twig- und HTML-Quellen werden vom regulären Blockstudio-Seitenparser verarbeitet.
Klassen auf Core-Blöcken
Eine class auf einem HTML-Element, das einem Core-Block zugeordnet ist, wird zu dessen className.
Ein explizites Core-Block-Tag kann direkt className verwenden. Beide Formen erhalten
die Klassen auf dem gespeicherten Wrapper des Blocks sowie die Klassen, die WordPress
generiert:
<p class="intro">Introduction</p>
<block name="core/group" className="feature">
<h2 class="title">Feature</h2>
</block>
Wenn beide Eigenschaften vorhanden sind, hat className Vorrang. Diese Konvertierung
gilt nur für Core-Blöcke: Bei einer Zuordnung zu einem benutzerdefinierten Block bleibt dessen Feld class
unverändert. Button-Stilklassen wie is-style-outline gehören zum
Button-Wrapper, nicht zu seinem Link.
Führe wp bs pages sync aus, um Parserkorrekturen auf zuvor synchronisierte
Seiten anzuwenden. Parser-Upgrades werden bei der nächsten expliziten Synchronisierung ohne Bearbeitung der Quelldatei erkannt. Gesperrte Seiten und Seiten mit sync: false behalten ihren
üblichen Schutz; Frontend-Anfragen führen diese Synchronisierung niemals aus.
Serialisierte WordPress-Blöcke
Seiten- und Musterquellen können auch serialisierte Blöcke enthalten, die aus dem WordPress-Code-Editor kopiert wurden:
<!-- wp:paragraph {"className":"intro"} -->
<p class="intro">Introduction</p>
<!-- /wp:paragraph -->
Enthält die Quelle einen <!-- wp:... -->-Blocktrenner, verwendet Blockstudio den nativen Blockparser von WordPress für die gesamte Quelle. Attribute, verschachtelte Blöcke, dynamische Blöcke wie Query Loop und Blockstudio-Blöcke behalten ihre serialisierte Struktur. HTML außerhalb der Blockkommentare bleibt nativer Freitext in HTML; er wird keinen zusätzlichen Blöcken zugeordnet. Mische die HTML-Block-Tags von Blockstudio nicht mit diesem Format und erwarte, dass sie konvertiert werden. Gewöhnliche HTML-Kommentare aktivieren nicht den Modus für serialisierte Blöcke.
Markdown-Seiten
Verwende Markdown, wenn der Fließtext in Dateien liegen, nach der Synchronisierung aber weiterhin als bearbeitbarer WordPress-Blockinhalt verfügbar sein soll. Die Markdown-Quelle wird während der Synchronisierung in Block-Markup umgewandelt. Der synchronisierte Beitrag speichert Blöcke, nicht den rohen Markdown-Inhalt.
Markdown lässt sich auf drei Arten verwenden:
| Quelle | Frontmatter erforderlich? | Hinweise |
|---|---|---|
Eigenständiges pages/example/index.md |
Ja | Frontmatter legt die Seitenidentität fest. |
page.json plus index.md |
Nein | page.json definiert die Seite und Markdown liefert den Inhalt. |
| Markdown in einer Sammlung | Nein | Die Sammlung leitet name und path aus dem Dateipfad ab. |
Ein eigenständiges index.md ohne Frontmatter wird übersprungen, da Blockstudio keine Seitenidentität zum Synchronisieren hat. Bei Markdown in einer Sammlung ist kein Frontmatter erforderlich, da das Sammlungsmanifest und der Dateipfad diese Identität festlegen.
---
name: about
title: About
slug: about
postStatus: publish
---
# About
This Markdown content is synced as native WordPress blocks.
Du kannst page.json auch mit index.md kombinieren. In diesem Fall definiert page.json die Seite und index.md liefert den Inhalt. Frontmatter in index.md überschreibt übereinstimmende Werte aus page.json.
{
"name": "docs-reference",
"title": "Reference",
"path": "reference",
"sync": true
}
---
title: API Reference
order: 20
---
# Reference
This page uses `page.json` with Markdown content.
Bei Markdown-Sammlungen wird der Dateipfad zum logischen Seitenpfad, sofern Frontmatter ihn nicht überschreibt:
| Datei | Standardpfad |
|---|---|
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 |
Unbekannte Frontmatter-Schlüssel bleiben im meta-Array der Seite erhalten. So kannst du Daten wie section oder description hinterlegen und über das PHP-API auslesen.
Markdown wird als GitHub Flavored Markdown geparst. Rohes HTML ist erlaubt, unsichere Links werden entfernt und Überschriften ohne explizite ID erhalten eine stabile ID. Für verschachteltes YAML-Frontmatter wird der mitgelieferte YAML-Parser benötigt.
Rohes Markdown
Markdown-Dateiquellen können ihre ursprüngliche Quelle als Markdown für externe Tools und Dokumentationsanwendungen bereitstellen. Inline-Markdown hat keine Quelldatei. Es wird daher zwar mit Blöcken synchronisiert, erzeugt aber keine rohe .md-Antwort.
Rufe die Seite mit einem .md-Suffix auf, zum Beispiel https://example.com/docs/reference.md. Oder sende einen Accept: text/markdown-Header an die normale Seiten-URL:
curl -H "Accept: text/markdown" https://example.com/docs/reference/
Frontmatter wird aus der Antwort entfernt. Erfolgreiche rohe Markdown-Antworten senden Content-Type: text/markdown, X-Robots-Tag: noindex und einen kanonischen Link-Header zurück an die HTML-Seite. Für nicht vorhandene .md-Routen wird tatsächlich der Statuscode 404 zurückgegeben.
Die Aushandlung funktioniert mit statischem Prerendering: Eine Anfrage, deren Accept-Header text/markdown enthält, wird nie aus dem Prerender-Speicher oder dem Drop-in für die frühe Auslieferung beantwortet. Sie erreicht daher WordPress und den Markdown-Handler. Vorgerenderte HTML-Antworten, die HTML einer Seite, die auch Markdown aushandelt, und das über Accept beantwortete Markdown senden Vary: Accept. Dadurch halten Caches, die Vary beachten, die beiden Varianten getrennt. Ein CDN, das seinen Cache ausschließlich anhand von URL ausrichtet, braucht eine eigene Regel, um den Cache für solche Anfragen zu umgehen. Pages::negotiates_markdown( $post_id ) zeigt an, ob eine Seite Markdown-Anfragen beantwortet.
Sammlungs-Markdown behalten für rohes Markdown dieselbe URL-Form bei:
| Seiten-URL | Rohes Markdown URL |
|---|---|
/docs/ |
/docs.md |
/docs/getting-started/ |
/docs/getting-started.md |
/docs/guide/install/ |
/docs/guide/install.md |
Deaktiviere rohe Markdown-Antworten mit dem Filter blockstudio/pages/serve_markdown:
add_filter( 'blockstudio/pages/serve_markdown', '__return_false' );
Eine .md-URL, die keiner durch Markdown gestützten Seite entspricht, gibt nur dann 404 zurück, wenn der Pfad innerhalb einer Seitensammlung liegt. Außerhalb aller Sammlungen lässt Blockstudio die Anfrage unverändert, damit WordPress und andere Plugins sie verarbeiten können.
Komponentenseiten
Eine Komponentenseite wird von einem Seiten-Renderer gerendert, statt als
Blöcke gespeichert zu werden. Blockstudio enthält keinen Renderer. Ein Theme oder Plugin registriert einen
für die von ihm verarbeiteten Eintragsdateien, etwa einen React-Renderer für page.tsx, und
Blockstudio ruft ihn mit der Seite, dem Beitrag WordPress und dem gerenderten Slot-
Inhalt auf.
pages/legal-notice/
page.json
page.tsx
data.php
{
"name": "legal-notice",
"title": "Legal Notice",
"slug": "legal-notice",
"postStatus": "publish",
"render": { "entry": "page.tsx", "data": "data.php" }
}
render ist explizit. Ein Verzeichnis mit einem index.php und einem page.tsx, aber ohne
render bleibt eine gewöhnliche Seite. So wird eine vorhandene Seite nicht doppelt gerendert, wenn ein Renderer hinzugefügt wird. Die möglichen Formen sind:
| Wert | Bedeutung |
|---|---|
"page.tsx" |
Nur Eintrag, ohne Data Loader |
{ "entry": "page.tsx", "data": "data.php" } |
Eintrag und Data Loader |
{ "entry": "page.tsx", "renderer": "react" } |
Eintrag mit expliziter Renderer-ID |
false |
Kein Renderer, auch wenn ein Sammlung-Standardwert einen nennt |
Pfade werden relativ zum Seitenverzeichnis aufgelöst, bei Loader-Einträgen relativ zum Stammverzeichnis der Sammlung. Sie müssen innerhalb der Quelle der Erkennung bleiben, es sei denn, blockstudio/pages/allow_external_loader_path erlaubt dies. Ohne renderer wird der Renderer verwendet, der die Erweiterung des Eintrags verarbeitet. Wenn render einen fehlenden Eintrag oder eine fehlende Datendatei, einen unbekannten Renderer oder eine Erweiterung bezeichnet, für die kein Renderer zuständig ist, liegt ein Fehler bei der Erkennung vor. Dadurch schlägt der Abgleich fehl, bevor etwas entfernt wird.
Was bei der Synchronisierung gespeichert wird
Bei der Synchronisierung wird ein Block vom Typ blockstudio/page gespeichert. Wenn das Seitenverzeichnis auch eine Quelle index.* enthält, wird diese wie jede andere Seitenquelle geparst und bildet die inneren Blöcke des Blocks, also seinen Slot:
<!-- wp:blockstudio/page /-->
<!-- wp:blockstudio/page -->
<!-- wp:paragraph -->
<p>[download_checkout]</p>
<!-- /wp:paragraph -->
<!-- /wp:blockstudio/page -->
Belasse Inhalte, die WordPress gehören, wie Shortcodes, im Slot. Eine Quelle, die nur aus einem Shortcode besteht, etwa [download_checkout],
wird als Block vom Typ core/shortcode gespeichert, sodass seine Ausgabe nicht von einem Absatz umgeben wird. Sie bleibt in
post_content, damit has_shortcode()-Prüfungen sie sehen, Schlüssel-Slot-Blöcke mit Änderungen im Editor wie verschachtelte Schlüsselblöcke zusammengeführt werden und do_shortcode die
Shortcodes einmalig mit seiner üblichen Priorität the_content erweitert, nachdem der Renderer sie eingerahmt hat.
Die Renderdefinition wird zusammen mit dem Beitrag als portable Pfade theme: gespeichert. Der Seiten-Fingerabdruck umfasst die Definition, nicht die Bytes des Eintrags oder des Data Loaders. Änderungen an page.tsx oder data.php lassen den Beitrag unverändert und erreichen Besucher über das Rendering und den statischen Prerender-Graphen, der den Eintrag, den Data Loader und jede vom Renderer gemeldete Datei erfasst.
Einen Renderer registrieren
Registriere Renderer mit der Aktion blockstudio/pages/renderers. Sie wird pro Anfrage einmal vor der ersten Erkennung oder dem ersten Rendern ausgelöst, sodass wp bs pages sync– und Frontend-Anfragen dieselbe Registry verwenden.
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',
)
);
}
);
Renderer-IDs bestehen aus Kleinbuchstaben. Eine Erweiterung oder ein Layoutname kann nur einem Renderer zugeordnet sein, und layout.php bleibt das eigene Layout von Blockstudio. Der Aufruf erhält eine Anfrage:
| Schlüssel | Wert |
|---|---|
kind |
page oder layout für ein Renderer-Layout |
renderer |
Renderer-ID |
entry |
Absoluter Pfad zum Eintrag |
data |
Absoluter Pfad zum Data Loader oder null |
page |
Kanonische Seitendaten einschließlich meta |
post_id |
ID des Beitrags WordPress |
slot |
Gerenderter Slot-Inhalt oder Seiteninhalt für ein Layout |
context |
frontend, rest, feed oder cli |
Es gibt HTML, die vom Rendern gelesenen Dateien und optionale Assets zurück:
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 stammt aus dem Anfragetyp und niemals vom Besucher. Ein Renderer kann daher die Byte-Parität zwischen angemeldeten und anonymen Besuchern nicht durch das Auslesen dieses Werts beeinträchtigen. Schlägt ein Renderer fehl, wirft er einen Fehler: Die Seite wird nicht mit leerem Inhalt gerendert. In einer REST-Editorvorschau zeigt der Block den Fehler stattdessen als Hinweis an. Nach erfolgreichem Rendern erhält die blockstudio/pages/rendered-Aktion die Seite, HTML und ihre Abhängigkeiten.
assets listet die Skript- und CSS-Dateien auf, die die Seite benötigt. Sie durchlaufen die Verarbeitung für Block-Assets (die *.inline.*-Konvention, ES-Module, Minifizierung und ?ver), und die Seite gibt sie einmal über denselben Puffer aus, der auch Block-Assets ausgibt. So enthält eine vorgerenderte Seite diese Dateien. Ein Asset kann version setzen, um seinen Wert ?ver zu ersetzen. Code außerhalb eines Renderers kann denselben Kanal über Blockstudio\Assets::register_owner() nutzen. Das gibt den Markierungskommentar zurück, der ausgegeben werden soll.
Editor
Im Editor zeigt blockstudio/page eine serverseitig gerenderte Vorschau der Seite mit dem Slot als inneren Blöcken, die dem templateLock der Seite folgen. Der Block kann nicht eingefügt, dupliziert oder in einen anderen Block verschachtelt werden.
Seitensammlungen
Eine Sammlung ist ein Ordner mit einem pages.json-Manifest. Sie fasst zahlreiche Seitenquellen unter einem Sammlungs-Slug zusammen, legt Standardwerte fest, unterstützt verschachtelte Pfade und kann automatisch einen eigenen Beitragstyp registrieren.
pages/
docs/
pages.json
layout.php
index.md
guide/
install/
index.md
reference/
page.json
index.md
loader.php
{
"collection": "docs",
"title": "Documentation",
"postType": "bs_docs",
"postTypeArgs": {
"label": "Docs",
"rewrite": {
"slug": "docs"
},
"supports": ["title", "editor", "page-attributes"]
},
"defaults": {
"postStatus": "publish",
"templateLock": "contentOnly"
}
}
| Eigenschaft | Typ | Beschreibung |
|---|---|---|
collection / slug / name |
string |
Slug der Sammlung. collection ist die eindeutigste Form und wird zur Basis der öffentlichen URL. |
title |
string |
Lesbarer Titel der Sammlung. |
postType |
string |
Inhaltstyp für generierte Seiten. Standardmäßig page. Wenn er nicht existiert, registriert Blockstudio ihn. |
postTypeArgs |
object |
Argumente, die an register_post_type() übergeben werden, wenn Blockstudio den Inhaltstyp der Sammlung registriert. |
defaults |
object |
Standardseiteneigenschaften, die auf jede Seite der Sammlung angewendet werden. Ein Standardwert für render gilt nur für eine Seite, wenn ihr Eintrag im Seitenverzeichnis vorhanden ist. |
scope |
string |
collection (Standard) oder site. Siehe Site-Sammlungen. |
meta |
object |
Benutzerdefinierte Metadaten der Sammlung. Unbekannte Manifest-Schlüssel werden ebenfalls in meta gespeichert. |
Seitenpfade in Sammlungen sind logische Pfade. Eine Seite mit path: "guide/install" wird als Unterseite von guide synchronisiert; guide wird als Unterseite des Sammlungsstammverzeichnisses synchronisiert, sofern diese übergeordneten Seiten vorhanden sind.
Enthält eine hierarchische Sammlung eine verschachtelte Seite, aber keine Quelldatei für eine übergeordnete Zwischenebene, erstellt Blockstudio für diesen Pfad eine leere Containerseite. So bleibt die WordPress-Hierarchie vollständig. Bei nicht hierarchischen Beitragstypen (ohne Unterstützung für page-attributes) werden keine leeren Container erstellt. Ihre Routen richten sich nach dem gespeicherten Sammlungspfad. Daher können verschachtelte Pfade wie guide/install und setup/install nebeneinander bestehen, obwohl beide mit install enden.
Sammlungs-Beitragstypen und URLs
Lege postType im Sammlungsmanifest fest, um alle Seiten der Sammlung mit diesem Beitragstyp zu synchronisieren. Du musst denselben Wert nicht in defaults wiederholen. Einzelne Seiten können postType weiterhin im Frontmatter oder in page.json überschreiben.
Wenn der Beitragstyp nicht vorhanden ist, registriert Blockstudio ihn mit show_in_rest: true, einer seitenähnlichen Editor-Konfiguration und dem Sammlungs-Slug als öffentlicher URL-Basis. postTypeArgs kann die Registrierungsargumente überschreiben. Rewrite-Regeln für Sammlungs-Beitragstypen werden automatisch aktualisiert, wenn sich registrierte Sammlungs-Beitragstypen oder Rewrite-Argumente ändern. Du musst daher die WordPress-Permalinks nicht erneut speichern.
Sammlungs-URLs setzen sich aus dem Sammlungs-Slug und dem logischen path jeder Seite zusammen:
| Quellpfad | Öffentliche URL |
|---|---|
path: "." |
/docs/ |
path: "getting-started" |
/docs/getting-started/ |
path: "guide/install" |
/docs/guide/install/ |
Dieses URL-Modell funktioniert sowohl für hierarchische als auch für nicht hierarchische Sammlungs-Beitragstypen. Blockstudio leitet außerdem doppelte URLs wie /docs/docs/ oder /docs/docs/getting-started/ auf die kanonische URL um.
Sammlungsseiten stellen rohes Markdown unter denselben URLs bereit (siehe Rohes Markdown).
Änderst du eine Sammlung von postType: "page" zu einem benutzerdefinierten Beitragstyp, migriert Blockstudio bereits synchronisierte Sammlungsbeiträge direkt, wenn ihre gespeicherte Seitenidentität übereinstimmt. Dadurch bleiben Beitrags-IDs, Metadaten und vorhandener Inhalt erhalten und doppelte Beiträge mit dem alten Typ werden vermieden. Veraltete Sammlungsbeiträge werden für alle Beitragsstatus gemäß dem Filter blockstudio/pages/orphan_action bereinigt.
Site-Sammlungen
Ein Manifest mit "scope": "site" gruppiert alle darunterliegenden Seiten, ohne sie in Sammlungsseiten umzuwandeln. Verwende es im Stammverzeichnis des Seitenbaums einer Website, um gemeinsame Standardwerte anzuwenden und die Seiten der Website mit blockstudio_page_tree( 'my-site' ) aufzulisten.
{
"collection": "my-site",
"title": "My Site",
"scope": "site",
"defaults": {
"postStatus": "publish",
"templateLock": "all",
"render": { "entry": "page.tsx", "data": "data.php" }
}
}
Die Seiten einer Site-Sammlung behalten genau dieselbe Identität wie ohne das Manifest. Wenn du also eine zu einem bestehenden Baum hinzufügst, werden keine Beitragszeilen aktualisiert und nichts erstellt oder gelöscht:
- Schlüssel bleiben global:
Pages::get_page( 'home' )und gespeicherte Seitenschlüssel stimmen weiterhin überein. - URLs bleiben WordPress-Seiten-URLs. Es gelten keine Rewrite-Regeln für Sammlungen, kein Permalink-Filter und keine Weiterleitung mit doppeltem URL. Außerdem werden keine leeren Containerseiten generiert.
- Logische Pfade, Slugs, übergeordnete Seiten und Quellidentitäten entsprechen denen eigenständiger Seiten; Layouts werden anhand des nächsten Vorfahren aufgelöst.
- Verschachtelte
pages.json-Manifeste behalten ihre eigenen Sammlungen, und ihre Teilbäume bleiben von der Site-Sammlung ausgeschlossen. - Standardwerte gelten pro Seite: Ein Standardwert für
rendergilt nur für Seiten, deren Verzeichnis den entsprechenden Eintrag enthält. So behalten Seiten mit Shortcodes und Markdown ihre Quellen.
Sammlungs-Loader
Sammlungen können einen vertrauenswürdigen lokalen loader.php enthalten. Verwende ihn, wenn die Seiten einer Sammlung aus einer anderen lokalen Quelle stammen, etwa einem externen Dokumentationsordner, einem Paket oder einem generierten Manifest.
Der Loader wird bei der expliziten Seitenermittlung und Synchronisierung ausgeführt. Er sollte deterministisch und lokal sein. Rufe aus loader.php keine entfernten Inhalte ab, da die Synchronisierung für Deployments sonst von diesem Dienst abhängen würde.
<?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',
),
),
);
Ein Loader kann ein Array mit den Schlüsseln pages, meta und paths zurückgeben:
| Schlüssel | Beschreibung |
|---|---|
pages |
Eine Liste von Seiten-Arrays. Jede Seite unterstützt dieselben erkannten Schlüssel wie das Frontmatter von page.json und Markdown. |
meta |
Metadaten, die mit dem meta-Array jeder vom Loader generierten Seite zusammengeführt werden. |
paths |
Zusätzliche lokale Verzeichnisse, die als Teil dieser Sammlung durchsucht werden. Einträge können Zeichenfolgen oder Pfadobjekte sein. |
render |
Eine Renderdefinition für jede Markdown-Seite, die über paths gefunden wird. |
Als Kurzform kann der Loader eine einfache Liste von Seiten-Arrays zurückgeben.
Loader-Seiteneinträge können auf folgende Arten Inhalte bereitstellen:
| Form | Beschreibung |
|---|---|
markdown |
Inline-Markdown-Inhalt. |
html |
Inline-HTML-Inhalt. |
content + contentType |
Allgemeiner Inline-Inhalt. contentType muss zu markdown oder html aufgelöst werden. |
file |
Lokale Dateiquelle. Der Typ wird anhand der Dateiendung ermittelt, sofern contentType nicht festgelegt ist. |
template |
Alias für file. |
Dateiverweise im Loader können auf Quellen im Format PHP, Blade, Twig, Markdown oder HTML verweisen. Relative Pfade werden vom Sammlungsstammverzeichnis aus aufgelöst. Absolute Pfade und Pfade außerhalb des Sammlungsstammverzeichnisses sind nur zulässig, wenn der Filter blockstudio/pages/allow_external_loader_path dies erlaubt.
Loader-Seiten verwenden standardmäßig generated: true. Wenn eine generierte Loader-Seite nicht mehr in der Loader-Ausgabe erscheint, behandelt Blockstudio den synchronisierten Beitrag beim nächsten Abgleich als verwaist und bereinigt ihn gemäß dem Filter blockstudio/pages/orphan_action.
In paths aufgeführte Verzeichnisse werden wie normale Sammlungsordner durchsucht. Sie können Markdown-Dateien oder page.json-Ordner enthalten. Liegen diese Pfade außerhalb des Sammlungsstammverzeichnisses, gilt derselbe Filter für externe Pfade.
Verwende einen Zeichenfolgeneintrag, wenn das externe Verzeichnis seine eigenen logischen Pfade behalten soll. Verwende einen Objekteintrag, wenn das Verzeichnis unter einem Pfadpräfix der Sammlung eingebunden werden soll:
'paths' => array(
array(
'path' => __DIR__ . '/cli-docs',
'prefix' => 'cli',
'meta' => array(
'doc_set' => 'cli',
),
),
),
Mit dieser Konfiguration wird cli-docs/index.md zu path: "cli" und cli-docs/getting-started.md zu path: "cli/getting-started" in der Sammlung. Präfixe sorgen außerdem dafür, dass generierte Seitennamen eindeutig sind, sodass mehrere eingebundene Verzeichnisse jeweils index.md oder getting-started.md enthalten können. Setze preserveNames im Pfadobjekt auf true, wenn explizite name-Werte aus page.json oder Markdown-Frontmatter stattdessen beibehalten werden sollen.
Eigenschaften des Pfadobjekts:
| Eigenschaft | Typ | Beschreibung |
|---|---|---|
path |
string |
Lokales Verzeichnis, das durchsucht werden soll. Relative Pfade werden vom Stammverzeichnis der Sammlung aus aufgelöst. |
prefix |
string |
Optionales logisches Pfadpräfix innerhalb der Sammlung. |
preserveNames |
boolean |
Explizite Seitennamen beibehalten, statt Namen aus dem Pfad mit Präfix zu generieren. Standardmäßig false, wenn prefix gesetzt ist. |
meta |
object |
Metadaten, die mit jeder über diesen Pfad gefundenen Seite zusammengeführt werden. Metadaten der Seite haben bei doppelten Schlüsseln Vorrang. |
render |
string|object |
Eine Renderdefinition für die Markdown-Seiten dieses Pfads, die die render des Loaders überschreibt. |
Markdown über eine Komponente rendern
Mit render werden die Markdown-Seiten, die ein Loader findet, über einen Seiten-Renderer ausgegeben, statt als Blöcke gespeichert zu werden:
<?php
return array(
'paths' => array( __DIR__ . '/external-docs' ),
'render' => array(
'entry' => __DIR__ . '/document.tsx',
'data' => __DIR__ . '/document.php',
),
);
Es bleiben Markdown-Seiten: Inhaltstyp, Inhaltspfad, .md-Antworten und Frontmatter bleiben unverändert. Sync speichert einen einzelnen blockstudio/page-Block, dessen inneres HTML der konvertierte Markdown ist, bereinigt, wenn die Sammlung ihren Inhalt bereinigt, statt geparster Blöcke. So behält post_content den Dokumenttext. Der Renderer erhält dieses HTML als Slot und kann die Quelle über page.content_path auslesen. Relative Pfade werden vom Stammverzeichnis der Sammlung aus aufgelöst; der externe Pfadfilter gilt wie für die Pfade. Eine Seite, deren Frontmatter ein eigenes render oder render: false festlegt, wird ausgeschlossen.
Layouts
Eine layout.php-Datei umschließt die Frontend-Darstellung einer dateibasierten Seite. Sie ersetzt weder das synchronisierte post_content in WordPress noch umschließt sie die Editor-Leinwand. Das Layout wird nur bei Frontend-Anfragen für einzelne Seiten ausgeführt.
Lege bei Sammlungen layout.php neben pages.json ab, um jede Frontend-Seite dieser Sammlung einzurahmen:
<?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() gibt den Seiteninhalt aus, den WordPress normalerweise über the_content rendern würde. Gibt ein Layout blockstudio_page_content() nicht aus, wird der Seiteninhalt absichtlich ausgeblendet.
Layouts können die Hilfsfunktionen für Seiten verwenden:
blockstudio_current_page();
blockstudio_page_collection('docs');
blockstudio_pages('docs');
blockstudio_page_tree('docs');
blockstudio_page_children('docs-guide', 'docs');
blockstudio_page_content();
Verschachtelte Seiten außerhalb von Sammlungen können auch das nächstgelegene übergeordnete layout.php innerhalb des pages-Baums übernehmen. Bei Sammlungsseiten wird das Layout des Sammlungsstammverzeichnisses in jedem synchronisierten Beitrag gespeichert und als Teil des Seiten-Fingerprints überwacht. Änderungen am Layout werden bei der nächsten Synchronisierung übernommen.
Renderer-Layouts
Ein Layout kann auch ein Renderer-Eintrag sein, etwa layout.tsx für einen Renderer, der layouts: ["layout.tsx"] registriert. Es wird an denselben Stellen wie layout.php gefunden, und ein optionales layout.data.php daneben dient als zugehöriger Daten-Loader. Beim Rendern erhält der Renderer kind: "layout" und den gerenderten Seiteninhalt als slot, mit derselben Priorität the_content wie layout.php. Ein Verzeichnis kann entweder layout.php oder ein Renderer-Layout enthalten, aber nicht beides. Beides führt zu einem Erkennungsfehler. Bei einem Layoutfehler wird blockstudio/pages/layout_error ausgelöst und der Seiteninhalt bleibt unverpackt, wie bei layout.php.
Blockbearbeitungsmodus
Die Eigenschaft blockEditingMode steuert, wie Blöcke im Editor bearbeitet werden können. Lege einen Standardwert für die Seite in page.json fest und überschreibe ihn für einzelne Elemente in der Vorlage:
{
"name": "about",
"title": "About Us",
"templateLock": "all",
"blockEditingMode": "disabled"
}
<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>
| Wert | Beschreibung |
|---|---|
"default" |
Vollständige Bearbeitung. Blöcke können ausgewählt, verschoben und bearbeitet werden. |
"contentOnly" |
Nur Textbearbeitung. Blocktext ist bearbeitbar, Einstellungen und Struktur sind jedoch gesperrt. |
"disabled" |
Keine Bearbeitung. Blöcke sind vollständig nicht interaktiv. |
Überschreibungen für einzelne Elemente werden als HTML-Attribute für beliebige Elemente (<h1>, <p>, <div> usw.) oder für <block>-Elemente festgelegt. Übergeordnete Containerblöcke der überschriebenen Elemente werden automatisch auf contentOnly gesetzt, damit ihre untergeordneten Elemente zugänglich bleiben. Diese Vererbung läuft vom überschriebenen Element bis zum Seitenstamm. Du musst blockEditingMode also nur für die Elemente festlegen, die bearbeitbar sein sollen.
Vorlagensperre
Die Eigenschaft templateLock steuert, wie Nutzer die Seite im Editor bearbeiten können:
| Wert | Hinzufügen/Entfernen | Verschieben | Inhalt bearbeiten |
|---|---|---|---|
"all" |
Nein | Nein | Nein |
"insert" |
Nein | Ja | Ja |
"contentOnly" |
Nein | Nein | Ja |
false |
Ja | Ja | Ja |
Wenn ein templateLock festgelegt ist, deaktiviert Blockstudio die Möglichkeit, Blöcke über UI des Editors zu entsperren.
Virtuelle Routen
Manche Dokumente haben keinen zugrunde liegenden Beitrag: etwa eine aus Daten generierte Komponentenreferenz, ein Katalog oder ein Kontobereich. Registriere sie als virtuelle Routen, statt selbst template_redirect einzubinden:
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(),
]
);
} );
Der Pfad ist relativ zum Stammverzeichnis der Website. Mit prefix bedient die Route auch alle darunterliegenden Pfade. match erhält den verbleibenden Teil (eine leere Zeichenfolge für die Route selbst) und gibt den Wert zurück, den der Render-Callback erhält, oder null, um URL an WordPress weiterzugeben, das wie üblich mit 404 antwortet. Der Render-Callback gibt das Dokument aus oder gibt es als Zeichenfolge zurück; title ist eine Zeichenfolge oder eine Closure, die den Trefferwert erhält.
Bei einer passenden Anfrage verhindert Blockstudio, dass WordPress einen 404-Fehler meldet und redirect_canonical eine Weiterleitung ausführt, setzt den von der Hauptabfrage gemeldeten Einzelstatus zurück, sendet den Statuscode (status, standardmäßig 200) und rendert mit der Priorität template_redirect Virtual_Routes::PRIORITY. Das geschieht unmittelbar nachdem der Ausgabepuffer von Blockstudio bei Assets::BUFFER_PRIORITY geöffnet wird. So erhält das fertige Dokument wie jede andere Seite seine Block-Assets, gebündelten UI-Assets und kompiliertes Tailwind, und zwar vor redirect_canonical mit Priorität 10. Ein Handler, der ein vollständiges Dokument selbst rendert, muss ebenfalls nach Assets::BUFFER_PRIORITY ausgeführt werden, sonst wird diese Verarbeitung übersprungen. Die Pfade in urls (standardmäßig der Routenpfad selbst, sofern es keine Präfixroute ist) werden zu statischen Prerender-Builds hinzugefügt, und Virtual_Routes::urls() gibt sie als absolute URLs für eine Sitemap zurück. Virtual_Routes::match( $path ) löst einen Pfad so auf wie eine Anfrage.
Synchronisierungsverhalten
Seitenbeiträge ändern sich nur durch einen expliziten Synchronisierungsvorgang:
wp bs pages sync
Der Befehl ermittelt das vollständige Quellinventar, erstellt oder aktualisiert geänderte Beiträge, entfernt bestätigte verwaiste Beiträge, aktualisiert das Routing der Sammlung und die kompilierte templateFor-Konfiguration und meldet alle Änderungen. Füge --authoritative hinzu, um verwaltete Inhalte zu ersetzen, statt Inhalte aus dem Editor beizubehalten, und --full, damit der Durchlauf unabhängig von der gespeicherten Quellidentität als vollständiger Abgleich gemeldet wird:
wp bs pages sync --authoritative --full
Normale Frontend-, Admin-, AJAX-, REST-, cron- und allgemeine WP-CLI-Bootstrap-Anfragen führen keine vollständige Seitenermittlung aus, fragen das Inventar für den verwalteten Abgleich nicht ab und schreiben keine Seitenbeiträge. Sie verwenden bereits synchronisierte WordPress-Beiträge sowie die kompakte, beim letzten expliziten Vorgang gespeicherte Konfiguration für Sammlungen und Beitragstypvorlagen. Bei einer Neuinstallation oder einem Upgrade können einmalig Sammlungsmanifeste durchsucht werden, um Routing-Metadaten wiederherzustellen. Dieser schreibgeschützte Bootstrap synchronisiert niemals Inhalte. Der authentifizierte, optionale Canvas-Aktualisierungsendpunkt ist eine explizite Aktion API zum Erstellen: Canvas ruft ihn einmal auf, wenn der Arbeitsbereich geöffnet wird, damit neu hinzugefügte oder geänderte Quellen im anfänglichen Inventar erscheinen. Der Live-Modus ruft dieselbe Schnittstelle auf, wenn er eine Änderung an einer Seitenquelle erkennt.
Blockstudio\Pages::init() registriert jetzt nur noch Hooks für Anfragen. Integrationen,
die zuvor ein Argument vom Typ force an diese Methode übergeben haben, müssen stattdessen Blockstudio\Pages::reconcile() aufrufen oder wp bs pages sync ausführen.
Um zu verhindern, dass eine Seite nach manuellen Änderungen überschrieben wird, setze "sync": false in page.json.
Portable Quellspeicherorte
Synchronisierte Theme-Dateien werden als Theme-relative Speicherorte statt als absolute Installationspfade gespeichert. Dateien aus Child-Themes und Parent-Themes behalten getrennte Identitäten, selbst wenn sie denselben relativen Dateinamen haben. Seitenhelfer geben für die aktuelle Anfrage weiterhin aufgelöste absolute Werte für template_path, content_path, layout_path und directory zurück.
Dadurch können CLI Synchronisierung und Webanfragen unterschiedliche Dateisystemwurzeln verwenden, etwa bei gehosteten Umgebungen mit eingeschränktem Dateisystemzugriff, ohne Markdown Antworten, Layouts, das Scannen des Editors nach Tailwind oder die Quellverfolgung beim Prerendering zu beeinträchtigen. Vorhandene absolute Theme-Pfade werden beim Lesen neu zugeordnet, wenn der Name des Theme-Verzeichnisses unverändert ist. Zum Lesen sind weder eine Synchronisierung noch eine Datenbankmigration oder ein Metadatenschreibvorgang während der Anfrage erforderlich; bei der nächsten expliziten Synchronisierung werden die portablen Speicherorte gespeichert.
Wenn ein Theme-Verzeichnis ein Symlink ist, zum Beispiel in einen Entwicklungs-Checkout, werden dieselben theme: Speicherorte gespeichert, unabhängig davon, ob eine Quelle über den Symlink oder dessen Ziel gelesen wurde. Sie werden dem konfigurierten Theme-Verzeichnis zugeordnet.
Dateien außerhalb der aktiven Child- und Parent-Themes werden weiterhin unter ihren konfigurierten absoluten Pfaden unterstützt, vorbehaltlich der Einschränkungen von PHP open_basedir. Sie lassen sich nicht automatisch verschieben: Aktualisiere nach dem Verschieben einer externen Quelle ihren konfigurierten Pfad und führe eine explizite Synchronisierung aus.
Zuständigkeit für Beitragsfelder
postStatus legt den anfänglichen Status fest. Bei späteren Synchronisierungen bleiben vorhandene Status wie Entwurf, ausstehend, privat, veröffentlicht und geplant erhalten, auch mit --authoritative. Ein Entwurf wird nicht erneut veröffentlicht, nur weil in seiner Datei postStatus: "publish" steht. Das bestehende Verhalten zur Wiederherstellung verwaister Beiträge bleibt unverändert: Eine explizite Synchronisierung stellt einen in den Papierkorb verschobenen verwalteten Beitrag wieder her, wenn seine Quelle vorhanden ist. Sperre die Seite oder deaktiviere die Synchronisierung, um diese Wiederherstellung zu verhindern.
Die Datei ist weiterhin maßgeblich für Titel, Slug, Beitragstyp, übergeordneten Beitrag und die konfigurierte Menüreihenfolge. Änderungen daran in WordPress ändern die Quelldefinition nicht. Bei der nächsten expliziten Synchronisierung werden die Dateiwerten erneut angewendet und die betroffenen Felder in pages.<name>.overwritten genannt; in der Tabellenausgabe von CLI erscheint eine Warnung. Die nativen Berechtigungen von WordPress gelten weiterhin, einschließlich des leeren Slugs für ausstehende Beiträge, wenn der synchronisierende Benutzer sie nicht veröffentlichen kann.
Verwende blockstudio/pages/update_post_data für eine Integration, die ausdrücklich eine andere Statusrichtlinie festlegt. Bei Blöcken mit Schlüssel bleibt der vom Editor verwaltete Blockinhalt erhalten; Schlüssel ändern nicht, wer für Titel oder Slug des Beitrags zuständig ist.
Bei Sammlungsseiten umfassen die Fingerprints das Manifest, den Loader, die Seitenquelle, die Layoutdatei, Metadaten und zugehörige Quellpfade. Die nächste explizite Synchronisierung übernimmt Änderungen an diesen Eingaben.
Wird eine Sammlungsquelle entfernt, entfernt Blockstudio die generierte Seite, damit nach dem Löschen der Quelldatei keine veralteten Sammlungsseiten zurückbleiben. Standardmäßig werden verwaiste Sammlungsseiten in den Papierkorb verschoben. Verwende blockstudio/pages/orphan_action, um trash, delete oder keep zurückzugeben.
Bei Frontend-Anfragen füllt Blockstudio die Seitenregistrierung anhand bereits synchronisierter und veröffentlichter Beiträge. Entwürfe und private Seiten sind im Admin- und Synchronisierungskontext verfügbar, aber Frontend-Hilfsfunktionen laden nur veröffentlichte Seiten.
Abgleich bei der Bereitstellung
Blockstudio\Pages::reconcile() ist der PHP-Einstiegspunkt für die Bereitstellung. Er ermittelt das vollständige gewünschte Inventar, vergleicht Quell- und Synchronisierungs-Engine-Fingerprints und gibt einen maschinenlesbaren Bericht zurück:
$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',
],
],
]);
Der Bericht enthält discovered, created, updated, unchanged, locked, preserved, removed, removedPages, failed, fullReconciliation, Ergebnisse pro Seite, Erkennungsfehler und eine deterministische sourceIdentity.
Gesperrte Seiten haben status: "locked" und werden getrennt von unveränderten Seiten gezählt. removedPages führt für jede entfernte Seite name, key, postId und die tatsächliche action auf (trash oder delete); beibehaltene oder bereits in den Papierkorb verschobene Beiträge zählen nicht als neu entfernt. Die Tabellenausgabe von CLI nennt außerdem erstellte, aktualisierte, gesperrte, entfernte und inhaltlich beibehaltene Seiten samt ihren Beitrags-IDs.
Nach dem Parsen und dem Zusammenführen der Blöcke mit Schlüsseln ruft ein identischer fertiger Beitrag wp_update_post() nicht auf, ändert post_modified nicht, erstellt keine Revision und löst keine Hooks zur Beitragsaktualisierung aus. Das Ergebnis lautet unchanged. Wenn sich der Inhalt der Quelle vom vom Editor verwalteten Inhalt der Blöcke mit Schlüsseln unterscheidet, kennzeichnet preserved: true diese Entscheidung, und der Zähler für preserved auf oberster Ebene berücksichtigt sie. Der neue Quell-Fingerabdruck und die verwalteten Metadaten werden weiterhin gespeichert, sodass die nächste unveränderte Synchronisierung nichts tut. preserved ist ein zusätzliches Flag und kein exklusiver Status: Eine Seite kann Inhalte von Blöcken mit Schlüsseln beibehalten und gleichzeitig einen dateiverwalteten Titel aktualisieren oder einen weiteren Block hinzufügen.
authoritative: true kann eine Page-Sync-Sperre aufheben und ersetzt Inhalte anhand der Dateidefinition, statt Inhalte aus dem Editor mit Schlüsseln beizubehalten. Lass die Option für eine normale explizite Synchronisierung auf false. plan_valid: false, full: true, broad: true, eine fehlende vorherige Quellidentität oder ein geänderter Fingerprint der Synchronisierungs-Engine kennzeichnen den Durchlauf als vollständigen Abgleich (fullReconciliation im Bericht). In jedem Durchlauf wird unabhängig davon das vollständige Inventar verglichen. Git-Umbenennungsdatensätze dienen nur als Identitätshinweise. Sie ersetzen niemals den Vergleich des vollständigen Inventars.
Bei identischen Fingerprints und unveränderten Laufzeitpfaden erfolgen keine Schreibvorgänge an Beiträgen oder Postmeta und es werden keine Aktualisierungs-Hooks ausgelöst. Wird eine unveränderte Quelle in ein neues Release-Verzeichnis verschoben, aktualisiert der Abgleich nur die gespeicherten Pfade für Vorlage, Inhalt, Layout und Verzeichnis. post_content und der Änderungszeitstempel des Beitrags werden nicht aktualisiert. Fehlende verwaltete Seiten werden erst entfernt, wenn der vollständige Abgleich ohne Ermittlungs- oder Schreibfehler für Seiten abgeschlossen wurde.
Ein direkter Abgleich mit API kennzeichnet eine Bereitstellung nicht als erfolgreich. Nachdem du das passende statische Artefakt und die Routen aktiviert und überprüft hast, speichere die zurückgegebene Identität ausdrücklich:
Blockstudio\Pages::store_successful_source_identity(
$report['sourceIdentity']
);
wp bs pages sync speichert die zurückgegebene Identität nach einem erfolgreichen Durchlauf.
Der reguläre WP-CLI-Bootstrap registriert nur gespeicherte Sammlungsbeitragstypen und Rewrite-Regeln. Er ermittelt oder synchronisiert keine Seiten.
Fixierung von Beitrags-IDs
Standardmäßig weist WordPress Beitrags-IDs automatisch zu. Wird eine Seite gelöscht und neu erstellt, ändert sich die ID, wodurch externe Verweise wie Menüs oder fest codierte Links ungültig werden.
Verwende postId, um einer Seite eine bestimmte ID zuzuweisen:
{
"name": "about",
"title": "About Us",
"postId": 42
}
Beim Erstellen der Seite übergibt Blockstudio die ID über import_id an WordPress. Ist die ID verfügbar, verwendet WordPress genau diese. Ist die ID bereits durch einen nicht zugehörigen Beitrag belegt, weist WordPress stillschweigend eine neue ID zu.
Beim Suchen nach vorhandenen Seiten prüft Blockstudio zuerst die fixierte ID und danach die Metadaten oder den Slug. Wird eine Seite gelöscht und erneut synchronisiert, erhält sie dadurch dieselbe ID zurück.
Zusammenführen von Blöcken nach Schlüssel
Ändert sich eine Vorlagendatei, ersetzt Blockstudio standardmäßig den gesamten Beitragsinhalt durch die neue Vorlage. Dadurch gehen alle Änderungen im Editor WordPress verloren.
Füge Blöcken ein key-Attribut hinzu, um Änderungen von Nutzern über Vorlagensynchronisierungen hinweg beizubehalten. Enthält eine Vorlage Blöcke mit Schlüsseln, führt Blockstudio Änderungen an der Vorlage mit dem vorhandenen Beitragsinhalt zusammen, statt ihn zu ersetzen.
Schlüssel hinzufügen
Verwende das Attribut key für beliebige Elemente vom Typ HTML oder <block>:
<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"
/>
Schlüssel müssen in der gesamten Vorlage eindeutig sein. Ein Schlüssel schützt den gesamten Block und seinen kompletten Inhalt. Untergeordnete Elemente innerhalb eines Blocks mit Schlüssel müssen keinen eigenen Schlüssel haben. Blöcke mit Schlüsseln können zwischen Vorlagenaktualisierungen an eine beliebige Position oder auf eine beliebige Verschachtelungsebene verschoben werden. Ihre Nutzerinhalte bleiben dabei erhalten.
Schlüssel funktionieren genauso für Blockstudio-Blöcke. Das key ist strukturelle Page-Sync-Metadaten. Werte benutzerdefinierter Felder bleiben normale Blockstudio-Attribute. Ändert ein Editor diese Felder, behält eine spätere Vorlagensynchronisierung die Editorwerte bei und übernimmt weiterhin unabhängige Vorlagenänderungen. Seiten, die mit älteren Versionen erstellt wurden und den Schlüssel in den Daten benutzerdefinierter Felder enthalten, werden bei der nächsten Synchronisierung automatisch migriert.
So funktioniert das Zusammenführen
Wenn sich eine Vorlagendatei ändert und die Seite erneut synchronisiert wird:
| Block | Verhalten |
|---|---|
| Block mit Schlüssel | Nutzerinhalte und Feldwerte von Blockstudio bleiben erhalten. Von der Vorlage verwaltete Attribute und Strukturen werden übernommen. |
| Block ohne Schlüssel | Wird vollständig durch die Vorlagenversion ersetzt (wie ohne Schlüssel). |
Beispiele
Änderungen von Nutzern bleiben in Blöcken mit Schlüssel erhalten:
- Die Vorlage definiert
<p key="intro">Default intro.</p> - Ein Nutzer ändert den Absatz im Editor in „Benutzerdefinierter Einleitungstext.“
- Ein Entwickler aktualisiert die Vorlage, fügt einen neuen Block hinzu und ändert das Layout.
- Bei der Synchronisierung bleibt der Absatz „Benutzerdefinierter Einleitungstext.“ erhalten, während das neue Layout übernommen wird.
Attribute aus der Vorlage werden weiterhin übernommen:
- Die Vorlage enthält einen Cover-Block mit
key="hero"und einemurl-Attribut. - Ein Entwickler ändert das Attribut
urldes Covers, um ein neues Hintergrundbild festzulegen. - Bei der Synchronisierung wird das neue Hintergrundbild übernommen, aber die Inhaltsänderungen des Nutzers innerhalb des Covers bleiben erhalten.
Sonderfälle
| Szenario | Verhalten |
|---|---|
| Neuer Block mit Schlüssel zur Vorlage hinzugefügt | Erscheint mit dem Standardinhalt der Vorlage. |
| Block mit Schlüssel aus der Vorlage entfernt | Wird aus dem Beitrag gelöscht. |
| Blocktyp geändert (derselbe Schlüssel) | Die Vorlage hat vollständig Vorrang; Inhalte werden nicht zusammengeführt. |
| Doppelte Schlüssel | Das zweite Vorkommen wird wie ein Block ohne Schlüssel behandelt. |
| Keine Schlüssel in der Vorlage | Vollständiger Ersatz (gleiches Verhalten wie ohne Schlüssel). |
| Erzwungene Synchronisierung | Vollständiger Ersatz; Schlüssel werden ignoriert. |
| Gesperrter Beitrag | Keine Synchronisierung. |
Mit Bearbeitungssteuerungen kombinieren
Schlüssel, templateLock und blockEditingMode ermöglichen dir eine genaue Steuerung darüber, was Kunden tun können und was nicht. Hier sind gängige Arbeitsabläufe.
Vollständig gesperrte Seite
Der Entwickler hat die volle Kontrolle. Die Seite ist ein statisches Layout, das Kunden überhaupt nicht bearbeiten können. Das eignet sich für rechtliche Seiten, Nutzungsbedingungen oder Seiten, die sich nur durch Code ändern sollen.
{
"name": "terms",
"title": "Terms of Service",
"templateLock": "all"
}
<h1>Terms of Service</h1>
<p>Last updated: January 2025</p>
<p>These terms govern your use of our service...</p>
Schlüssel sind nicht erforderlich. Die Vorlage ist die einzige maßgebliche Quelle. Jede Synchronisierung überschreibt die gesamte Seite.
Gesperrtes Layout mit bearbeitbaren Inhalten
Das häufigste Muster. Sperre die Seitenstruktur, damit Kunden keine Blöcke hinzufügen, entfernen oder neu anordnen können, aber lasse sie Text an bestimmten Stellen bearbeiten. Durch Schlüssel bleiben ihre Änderungen bei Vorlagenaktualisierungen erhalten.
{
"name": "landing",
"title": "Landing Page",
"templateLock": "all",
"blockEditingMode": "disabled"
}
<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>
Der Kunde kann den Hero-Titel, die Beschreibung und die Einleitung der Feature-Sektion bearbeiten. Sonst nichts. Der Buttontext, URL und das Hintergrundbild des Covers werden vom Entwickler gesteuert. Aktualisiert der Entwickler die Vorlage (e.g. und fügt einen zweiten Button hinzu), bleiben die Texte des Kunden in den Abschnitten mit Schlüssel erhalten.
Vorlage mit beibehaltenen Inhalten erweitern
Für Seiten, die mit der Zeit wachsen. Der Entwickler fügt der Vorlage neue Abschnitte hinzu und jede Synchronisierung ergänzt die neuen Inhalte, ohne die bisherigen Anpassungen des Kunden anzutasten.
<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>
<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>
Der neue Referenzen-Abschnitt und der Button erscheinen bei der Synchronisierung. Die Änderungen des Kunden an Titel, Einleitung und Angeboten bleiben unberührt.
Einmaliges Grundgerüst
Erstelle eine Seite mit einer Grundstruktur und übergib sie dann vollständig. Setze sync auf false, damit die normale Synchronisierung die Seite weder erstellt noch aktualisiert, und erstelle sie einmalig mit Blockstudio\Pages::force_sync('blog'). Danach gehört die Seite vollständig dem Kunden.
{
"name": "blog",
"title": "Blog",
"sync": false
}
<h1>Our Blog</h1>
<p>Welcome to our blog. Start writing!</p>
wp bs pages sync überspringt diese Seite, sodass force_sync() sie einmalig erstellt. Danach kann der Kunde Blöcke beliebig hinzufügen, entfernen und neu anordnen. Vorlagenänderungen werden ignoriert.
Blockbindungen
Eine Alternative zum Zusammenführen nach Schlüsseln ist die Verwendung der Blockbindungen von WordPress Core, um Blöcke mit Postmeta zu verknüpfen: Blockbindungen API. Das ist keine Funktion von Blockstudio, sondern ein natives WordPress API. Blockstudio gibt das Attribut metadata einfach an das generierte Block-Markup weiter. Die Inhalte liegen in Postmeta statt im Block-Markup. Daher können Vorlagensynchronisierungen das Markup beliebig überschreiben, da der Editor die Inhalte aus den Metadaten und nicht aus innerHTML liest.
Übergib das Attribut metadata an beliebige Elemente vom Typ HTML oder <block>:
<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"}}}}'
/>
Die Metaschlüssel müssen mit aktiviertem show_in_rest registriert werden:
register_post_meta( 'page', 'hero_title', array(
'show_in_rest' => true,
'single' => true,
'type' => 'string',
'default' => 'Default Title',
) );
Schlüssel und Bindungen im Vergleich
| Aspekt | Schlüssel | Bindungen |
|---|---|---|
| Inhalte gespeichert in | Block-Markup (post_content) |
Postmeta (wp_postmeta) |
| Bleibt bei Vorlagensynchronisierung erhalten | Ja (nach Schlüssel zusammengeführt) | Ja (Daten liegen in den Metadaten) |
Über WP_Query abfragbar |
Nein | Ja (meta_query) |
| Verfügbar in REST API | Nein | Ja |
| Registrierung erforderlich | Nein | Ja (register_post_meta) |
| Nutzer können Blöcke verschieben | Nein (die Vorlage setzt die Struktur erneut durch) | Nein (die Vorlage setzt die Struktur erneut durch) |
Beide Ansätze können in derselben Vorlage verwendet werden. Verwende Schlüssel für Abschnitte, bei denen die Blockstruktur wichtig ist (e.g, etwa eine Gruppe mit mehreren untergeordneten Elementen). Verwende Bindungen für einzelne Felder, wenn die Daten auch außerhalb des Blockeditors verfügbar sein sollen.
Beitragstypvorlagen
Verwende templateFor, um eine Seite als Standardvorlage für einen Beitragstyp festzulegen:
{
"name": "product-template",
"title": "Product Template",
"templateFor": "product",
"templateLock": "insert"
}
Alle neuen Beiträge dieses Typs beginnen mit der definierten Blockstruktur.
Benutzerdefinierte Pfade
Standardmäßig durchsucht Blockstudio get_template_directory() . '/pages'. Füge mit dem Filter weitere Pfade hinzu:
add_filter( 'blockstudio/pages/paths', function( $paths ) {
$paths[] = get_stylesheet_directory() . '/custom-pages';
$paths[] = MY_PLUGIN_DIR . '/pages';
return $paths;
} );
Laufzeitintegrationen, die Dateien aus mehreren Stammverzeichnissen zusammenstellen, können die Dateisystemsuche durch eine logische Erkennungsquelle ersetzen. Seitenmanifeste, Layouts, Loader und Quellvorlagen werden dann über logische Pfade aufgelöst, auch wenn die ausgewählten Dateien in verschiedenen Stammverzeichnissen liegen.
Filter und Aktionen
Die Ermittlung von Seiten, die Synchronisierung und das Routing von Sammlungen bieten folgende Erweiterungspunkte:
| Hook | Typ | Beschreibung |
|---|---|---|
blockstudio/pages/paths |
Filter | Fügt Verzeichnisse hinzu, die Blockstudio nach Seitenquellen durchsucht. |
blockstudio/pages/collection_post_type_args |
Filter | Passt die Argumente von register_post_type() für einen Collection-CPT an. |
blockstudio/pages/template_candidates |
Filter | Passt die Vorlagendateinamen an, die für eine Seitenquelle berücksichtigt werden. |
blockstudio/pages/serve_markdown |
Filter | Aktiviert oder deaktiviert rohe Markdown Antworten. |
blockstudio/pages/orphan_action |
Filter | Gibt trash, delete oder keep für die Bereinigung verwaister Einträge zurück. |
blockstudio/pages/docs_allowed_html |
Filter | Passt die zulässigen HTML für generierte Markdown-Dokumentationsinhalte an. |
blockstudio/pages/allow_external_loader_path |
Filter | Erlaubt paths des Loaders außerhalb des Collection-Stammverzeichnisses. |
blockstudio/pages/manifest_scan_interval |
Filter | Legt das Höchstalter eines zwischengespeicherten Manifests aus der Zeit vor 7.6.2 fest, das beim Upgrade als Grundlage für die gespeicherte Laufzeitkonfiguration dienen darf. |
blockstudio/pages/create_post_data |
Filter | Ändert Beitragsdaten, bevor eine synchronisierte Seite erstellt wird. |
blockstudio/pages/update_post_data |
Filter | Ändert Beitragsdaten, bevor eine synchronisierte Seite aktualisiert wird. |
blockstudio/pages/sync_engine_inputs |
Filter | Fügt eine Parser-, Zuordnungs- oder Migrationsversion hinzu, die den Abgleich einmalig absichtlich erweitert. |
blockstudio/pages/post_created |
Aktion | Wird ausgeführt, nachdem ein synchronisierter Seitenbeitrag erstellt wurde. |
blockstudio/pages/post_updated |
Aktion | Wird ausgeführt, nachdem ein synchronisierter Seitenbeitrag aktualisiert wurde. |
blockstudio/pages/synced |
Aktion | Wird ausgeführt, nachdem die Seitensammlung vollständig synchronisiert wurde. |
blockstudio/pages/reconciled |
Aktion | Wird nach einem expliziten Abgleich mit seinem maschinenlesbaren Bericht ausgeführt. |
blockstudio/pages/renderers |
Aktion | Registriert Seiten-Renderer mit Blockstudio\Page_Renderers::register(). Wird einmal pro Anfrage ausgeführt. |
blockstudio/pages/rendered |
Aktion | Wird nach dem Rendern einer Komponenten-Seite mit der Seite, ihrem HTML und ihren Abhängigkeiten ausgeführt. |
blockstudio/pages/layout_error |
Aktion | Wird ausgeführt, wenn ein Layout nicht gerendert werden kann, und erhält den Fehler, den Layout-Pfad und die Seite. |
PHP API
// 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]);
Siehe Abgleich der Bereitstellung für die Bedeutung der Argumente, Berichtsfelder und die verifizierte Grenze der Quellidentität.
Für Vorlagen und Layouts stehen globale Hilfsfunktionen zur Verfügung:
blockstudio_pages('docs');
blockstudio_page_tree('docs');
blockstudio_page_children('docs-guide', 'docs');
blockstudio_page_collection('docs');
blockstudio_page_content();
blockstudio_current_page();
Von Blockstudio\Pages::pages(), Blockstudio\Pages::tree(), Blockstudio\Pages::children() und den globalen Hilfsfunktionen zurückgegebene Seiten-Arrays enthalten die Identität des synchronisierten Beitrags, Quell- und Vorlagenpfade, Collection-/Pfadmetadaten, Inhaltstyp, Synchronisierungsrichtlinie, Beitragstyp/-status, Bearbeitungsrichtlinie, benutzerdefinierte Metadaten und einen permalink-Schlüssel. Collection-Metadaten werden aus dem letzten erfolgreichen expliziten Abgleich geladen. Bei normalen Anfragen werden diese Laufzeitdaten aus der persistierten Konfiguration und den Metadaten synchronisierter Beiträge rekonstruiert, ohne die Seitenquellbäume zu lesen. Die Pages-Klasse stellt keine separate Permalink-Methode bereit.
Dateibasierte Seiten erstellen
Vorlagensperren, Blockbearbeitungsmodi, schlüsselbasiertes Zusammenführen und die Steuerung dessen, was Clients bearbeiten können.