Website-Editor: Templates und Teile aus Dateien
Ein Block-Theme beschreibt sein Layout in templates/*.html und parts/*.html:
Dateien voller serialisierter Block-Kommentare wie
<!-- wp:template-part {"slug":"header"} /-->. Niemand schreibt diese gern von
Hand, daher werden sie meist im Website-Editor erstellt und exportiert. Das funktioniert,
bis zwei Personen dasselbe Template bearbeiten oder jemand einen Diff aus maskiertem JSON in HTML-Kommentaren lesen muss.
Blockstudio lässt dich dieselben Templates so schreiben wie dateibasierte
Seiten: als Ordner mit einem kleinen JSON-Manifest und einer Quelldatei in HTML-ähnlichem
Markup, mit einfachen Elementen, <block>-Tags und deinen eigenen Blockstudio-Blöcken.
Blockstudio kompiliert die Quelle zu nativem Block-Markup und übergibt sie als Theme-Datei an WordPress.
Der Website-Editor funktioniert weiterhin wie gewohnt: Nutzer können ein Template
anpassen, und beim Zurücksetzen wird die Dateiversion wiederhergestellt.
Dieser Leitfaden erstellt einen Header- und einen Footer-Teil, Templates für die Startseite und einzelne Beiträge sowie ein benutzerdefiniertes Template, das Redakteure für Seiten auswählen können. Anschließend zeigt er, wie WordPress sie auflöst.
Ordnerstruktur
Templates gehören in templates/, Template-Teile in parts/. Jedes ist ein Ordner
mit Manifest und einer Quelldatei:
theme/
├── templates/
│ ├── front-page/
│ │ ├── template.json
│ │ └── index.php
│ ├── single/
│ │ ├── template.json
│ │ └── index.php
│ └── page-landing/
│ ├── template.json
│ └── index.php
└── parts/
├── header/
│ ├── part.json
│ └── index.php
└── footer/
├── part.json
└── index.html
Das sind dieselben Ordner templates/ und parts/, die WordPress für ein Block-Theme
liest. Blockstudio durchsucht zuerst das aktive Theme und dann das übergeordnete Theme.
Ordner mit template.json oder part.json sind Quellen für Blockstudio; einfache
.html-Dateien daneben bleiben native WordPress-Templates.
Die Quelldatei kann index.php, index.blade.php, index.twig oder
index.html sein; geprüft wird in dieser Reihenfolge. Twig erfordert Timber, Blade sein Renderer-Paket, wie unter
Template-Engines beschrieben.
Schritt 1: Der Header-Teil
Jeder Teil benötigt ein part.json. Das area gibt dem Website-Editor an, wo der Teil hingehört:
{
"slug": "header",
"title": "Header",
"description": "Site header with logo and navigation",
"area": "header"
}
Die Quelle verwendet dieselbe Syntax wie Blockstudio-Seiten und -Patterns. Ein <div>
wird zu einem Gruppenblock, Attribute werden zu Blockattributen und <block>
Elemente erzeugen jeden registrierten Block:
<div layout='{"type":"flex","justifyContent":"space-between"}'>
<block name="core/site-title" />
<block name="core/navigation" overlayMenu="mobile" />
</div>
Blockstudio kompiliert es zu diesem Block-Markup:
<!-- wp:group {"layout":{"type":"flex","justifyContent":"space-between"}} --><div class="wp-block-group is-layout-flex"><!-- wp:site-title /--><!-- wp:navigation {"overlayMenu":"mobile"} /--></div><!-- /wp:group -->
Das hättest du sonst von Hand geschrieben. Deine eigenen Blöcke funktionieren genauso: <block name="acme/announcement" />, ein <bs:acme-announcement />-Tag oder ein konfiguriertes Tag-Präfix werden alle zum Block-Kommentar für diesen Block kompiliert.
Schritt 2: Der Footer-Teil
Ein Teil kann aus nur einem Absatz bestehen. Dieses Beispiel verwendet index.html, um zu zeigen, dass die Quelle Markup und kein Programm ist:
{
"slug": "footer",
"title": "Footer",
"area": "footer"
}
<p>Built with Acme.</p>
Es wird zu <!-- wp:paragraph --><p>Built with Acme.</p><!-- /wp:paragraph --> kompiliert.
Schritt 3: Templates für Startseite und einzelne Beiträge
Templates verwenden template.json. slug muss ein exakter Name aus der Template-Hierarchie von WordPress sein, zum Beispiel front-page, single, page, archive, 404 oder single-product. Blockstudio wird niemals davor gesetzt.
{
"slug": "front-page",
"title": "Front Page",
"description": "Homepage template"
}
<block name="core/template-part" slug="header" tagName="header" />
<main>
<block name="core/post-content" />
</main>
<block name="core/template-part" slug="footer" tagName="footer" />
Das Template für einzelne Beiträge folgt demselben Aufbau und verwendet Beitragsblöcke:
{
"slug": "single",
"title": "Single Post"
}
<block name="core/template-part" slug="header" tagName="header" />
<main>
<block name="core/post-title" level="1" />
<block name="core/post-date" />
<block name="core/post-content" />
</main>
<block name="core/template-part" slug="footer" tagName="footer" />
Das kompilierte Template für einzelne Beiträge:
<!-- wp:template-part {"slug":"header","tagName":"header"} /--><!-- wp:group {"tagName":"main"} --><main class="wp-block-group"><!-- wp:post-title {"level":1} /--><!-- wp:post-date /--><!-- wp:post-content /--></main><!-- /wp:group --><!-- wp:template-part {"slug":"footer","tagName":"footer"} /-->
<main> wurde zu einem Gruppenblock mit tagName: "main", und die Template-Teilblöcke verweisen über ihren Slug auf die Teile aus Schritt 1 und 2. Wenn WordPress das Template rendert, werden diese Verweise zu den dateibasierten Teilen aufgelöst. Die Ausgabe der Startseite beginnt dann mit <header class="wp-block-template-part">, das Website-Titel und Navigation enthält, und endet mit <footer class="wp-block-template-part">, das den Footer-Absatz enthält.
Schritt 4: Ein benutzerdefiniertes Template für Seiten
Templates, deren Slug nicht zur Hierarchie gehört, sind benutzerdefinierte Templates. Gib mit postTypes an, für welche Inhaltstypen sie gelten, damit Redakteure sie im Template-Auswahlmenü auswählen können:
{
"slug": "page-landing",
"title": "Landing Page",
"description": "Full-width page without a header",
"postTypes": ["page"]
}
<main>
<block name="core/post-content" />
</main>
<block name="core/template-part" slug="footer" tagName="footer" />
get_block_templates( array( 'post_type' => 'page' ), 'wp_template' ) enthält jetzt page-landing, und das Template-Objekt umfasst post_types: ["page"].
Quellen werden einmal kompiliert
Die Quelle wird einmal gelesen und zu Block-Markup kompiliert, nicht bei jeder Anfrage. Dabei gibt es weder einen aktuellen Beitrag noch einen Anfragekontext. index.php wird als Markup gelesen: darin enthaltener PHP-Code wird nicht ausgeführt, daher kompiliert <?php echo get_bloginfo( 'name' ); ?> zu nichts. Alles, was von der Anfrage abhängt, gehört in einen Block, der zur Laufzeit rendert: core/site-title statt eines ausgegebenen Website-Namens, core/post-title statt the_title() oder einen eigenen dynamischen Blockstudio-Block.
Kompilierte Ergebnisse werden mit Dateiüberwachungs-Metadaten zwischengespeichert. Wird ein Manifest oder eine Quelldatei bearbeitet, wird der Cache-Inhalt für dieses Element ungültig. Die nächste Anfrage erhält die Änderung ohne separaten Build-Schritt.
Wie WordPress die Dateien erkennt
Blockstudio ist in dieselben Suchvorgänge eingebunden, die WordPress für Theme-Templates verwendet. In get_block_templates() erscheinen die dateibasierten Templates zusammen mit source: "theme" und origin: "theme" wie native Theme-Dateien, und get_block_template( 'acme//header', 'wp_template_part' ) gibt den Header-Teil mit seinem area zurück.
Die Suchreihenfolge lautet:
- Eine im Website-Editor vorgenommene Anpassung, die in der Datenbank gespeichert ist.
- Eine native
.html-Datei im aktiven Theme. - Die dateibasierte Quelle Blockstudio.
- Fallbacks aus übergeordnetem Theme oder Plugin.
Diese Reihenfolge erhält den Workflow des Website-Editors. Bearbeitet jemand den Footer und speichert ihn, legt WordPress einen wp_template_part-Beitrag an, und get_block_template() gibt diese Anpassung mit source: "custom" zurück.
Spätere Änderungen an parts/footer/index.html werden nicht angezeigt, solange die Anpassung besteht. Wird der Teil zurückgesetzt oder der Beitrag gelöscht, greift die Suche auf die Datei zurück und gibt erneut die neueste kompilierte Quelle zurück.
Blockstudio schreibt Änderungen aus dem Website-Editor nicht in Dateien zurück. Soll eine Änderung zum neuen Standard werden, kopiere sie in die Quelldatei und setze die Anpassung zurück.
Verschachtelte index.html und Slugs
WordPress erkennt Dateien mit .html rekursiv in templates/ und parts/. Ein Manifest-Ordner mit index.html, etwa parts/footer/index.html, würde daher auch als nativer Teil mit dem pfadbasierten Slug footer/index erscheinen. Seit Blockstudio 7.6.6 wird ein Manifest-eigenes index.html nur unter dem angegebenen Slug bereitgestellt, sodass der Website-Editor einen Footer statt zwei auflistet. Verschachtelte .html-Dateien ohne Manifest bleiben unverändert.
Templates von PHP prüfen
Die Klasse Blockstudio\Site_Templates liest und kompiliert die Quellen. Das ist bei Tests und Deployment-Prüfungen nützlich:
$templates = Blockstudio\Site_Templates::templates();
$header = Blockstudio\Site_Templates::get_part( 'header' );
echo $header['area']; // header
echo $header['content']; // compiled block markup
$errors = Blockstudio\Site_Templates::errors();
Jedes Element umfasst slug, title, description, type (wp_template oder wp_template_part), status, source_type, postTypes für Templates oder area für Teile, meta und das kompilierte content. Übergib eine Liste, um nur ausgewählte Elemente zu kompilieren, und lies mit selection_errors() die Probleme für diese Auswahl aus:
$selected = Blockstudio\Site_Templates::templates( array( 'front-page' ) );
$errors = Blockstudio\Site_Templates::selection_errors( 'templates' );
Weitere Ordner hinzufügen
Damit Blockstudio-Quellen getrennt von nativen Templates bleiben oder über ein Plugin bereitgestellt werden können, füge mit Filtern Erkennungswurzeln hinzu:
add_filter( 'blockstudio/site_templates/template_paths', function ( $paths ) {
$paths[] = get_stylesheet_directory() . '/site-templates';
return $paths;
} );
add_filter( 'blockstudio/site_templates/part_paths', function ( $paths ) {
$paths[] = get_stylesheet_directory() . '/site-parts';
return $paths;
} );
Die Filter blockstudio/site_templates/template_content und part_content passen eine Quelle vor dem Parsen an, während blockstudio/site_templates/parser den Parser für ein einzelnes Element austauscht. Die vollständige Liste steht in der Tabelle zu Site-Templates-Hooks.
Wann du was verwendest
| Du möchtest | Verwende |
|---|---|
| Das Theme-Layout, das WordPress für ein URL auswählt: Header, Footer, Einzelansicht, Archiv | Website-Templates und -Teile |
| Eine aufrufbare Seite, deren Inhalt in Dateien liegt | Dateibasierte Seiten |
| Einen wiederverwendbaren Abschnitt, den Redakteure einfügen | Patterns |
Templates erstellen keine Beiträge. Das tun Seiten. Ein Dokumentationsbereich ist zum Beispiel eine Seitensammlung, deren Beiträge über ein Template gerendert werden, das du weiterhin hier erstellen kannst.
Nächste Schritte
- Referenz zu Website-Templates: alle Eigenschaften des Manifests, das PHP API und sämtliche Hooks.
- Übersicht zu Seiten und Patterns: der Parser HTML, Block-Tags und die Elementzuordnung für Template-Quellen.
- Eine Dokumentationswebsite erstellen: Seitensammlungen mit Markdown, Loadern und Layouts.