Zum Inhalt springen

Website-Vorlagen

Mit Site Templates können Block-Themes WordPress wp_template und wp_template_part-Quellen mit derselben dateibasierten Syntax wie Blockstudio-Seiten und -Patterns definieren.

Verwende Website-Vorlagen, wenn du das Theme-Layout steuern möchtest, das WordPress über die Vorlagenhierarchie des Site-Editors auswählt: Startseite, einzelne Beiträge, Archive, Suche, 404-Seiten, Header, Footer und andere Vorlagenteile.

Seiten, Muster oder Website-Vorlagen?

Funktion Erstellt Am besten geeignet für
Seiten Beiträge oder Einträge benutzerdefinierter Beitragstypen Echte Inhaltsseiten, Dokumentationsseiten, Landingpages und aufrufbare Inhalte.
Muster Blockmuster Wiederverwendbare Abschnitte, die Redakteure einfügen.
Website-Vorlagen wp_template– und wp_template_part-Dateiquellen Theme-Layout, das vom Site-Editor und der Vorlagenhierarchie WordPress gesteuert wird.

Website-Vorlagen erstellen keine normalen Seiten. Sie stellen die Dateiquelle bereit, die WordPress beim Auflösen einer Block-Theme-Vorlage verwendet. Passt ein Nutzer die Vorlage im Site-Editor an, speichert WordPress diese Anpassung in der Datenbank. Sie hat Vorrang vor der Dateiquelle, bis sie zurückgesetzt wird.

Ordnerstruktur

Lege vollständige Vorlagen in templates/ und Vorlagenteile in parts/ ab:

Text
theme/
  templates/
    front-page/
      template.json
      index.php
    single/
      template.json
      index.twig
  parts/
    header/
      part.json
      index.php
    footer/
      part.json
      index.php

Jeder Ordner enthält ein Manifest und eine Quelldatei.

Datei Engine
index.php Block-Markup ähnlich HTML, unverändert gelesen (PHP-Code wird nicht ausgeführt)
index.blade.php Blade
index.twig Twig
index.html Block-Markup ähnlich HTML

Wenn mehrere Quelldateien vorhanden sind, verwendet Blockstudio diese Reihenfolge:

  1. index.php
  2. index.blade.php
  3. index.twig
  4. index.html

WordPress erkennt auch rekursiv .html-Dateien und stellt normalerweise ein verschachteltes index.html unter dem aus dem Pfad abgeleiteten Slug bereit, zum Beispiel header/index. Gehört diese Datei zu einem Blockstudio-Manifest, entfernt Blockstudio das pfadbasierte Duplikat und stellt nur das im Manifest deklarierte slug bereit. Verschachtelte native .html-Vorlagen ohne Blockstudio-Manifest bleiben unverändert.

Die Quelle wird einmalig in natives WordPress-Block-Markup kompiliert. Sie sollte weder von der aktuellen Anfrage noch vom aktuellen Beitrag abhängen. Platziere Laufzeitverhalten in dynamischen Blöcken.

template.json

template.json definiert eine vollständige Vorlage für den Site-Editor.

JSON
{
  "slug": "front-page",
  "title": "Front Page",
  "description": "Homepage template",
  "postTypes": ["page"]
}

Eigenschaften

Eigenschaft Typ Standard Beschreibung
slug / name string Ordnername WordPress-Vorlagen-Slug. Verwende exakte Hierarchie-Slugs wie front-page, single, archive-product oder 404.
title string Titel aus dem Slug Anzeigetitel im Website-Editor.
description string "" Beschreibung im Website-Editor anzeigen.
postTypes string[] [] Inhaltstypen für benutzerdefinierte Vorlagen. Bei Vorlagen der Kernhierarchie kann diese Angabe entfallen.
source / template / file string Automatisch erkannte Indexdatei Optionaler Quelldateipfad relativ zum Vorlagenordner.
status string "publish" Vorlagenstatus.
sync boolean false Für die spätere Materialisierung in der Datenbank reserviert. Benutzeranpassungen in v1 werden nie überschrieben.
meta object {} Benutzerdefinierte Metadaten für Hilfs-APIs. Unbekannte Manifest-Schlüssel werden ebenfalls hier gespeichert.

Vorlagen-Slugs haben kein Präfix. WordPress benötigt für die Vorlagenhierarchie exakte Namen:

Text
index
home
front-page
single
single-post
single-product
archive
archive-product
page
page-about
404
search
taxonomy-product_cat

part.json

part.json definiert einen Vorlagenteil für den Site-Editor.

JSON
{
  "slug": "header",
  "title": "Header",
  "description": "Main site header",
  "area": "header"
}

Eigenschaften

Eigenschaft Typ Standard Beschreibung
slug / name string Ordnername WordPress-Slug des Vorlagenteils.
title string Titel aus dem Slug Anzeigetitel im Site-Editor.
description string "" Anzeigebeschreibung im Site-Editor.
area string "uncategorized" Bereich des Vorlagenteils. Übliche Werte sind header, footer und sidebar.
source / template / file string Automatisch erkannte Indexdatei Optionaler Pfad zur Quelldatei relativ zum Ordner des Vorlagenteils.
status string "publish" Status des Vorlagenteils.
meta object {} Benutzerdefinierte Metadaten für Hilfs-APIs. Unbekannte Manifest-Schlüssel werden ebenfalls hier gespeichert.

Markup erstellen

Für Website-Vorlagenquellen wird derselbe Parser wie für Seiten und Muster verwendet:

PHP
<div class="site-shell">
  <block name="core/template-part" slug="header" />

  <main>
    <h1>Welcome</h1>
    <p>This template is compiled from Blockstudio files.</p>
    <block name="core/post-content" />
  </main>

  <block name="core/template-part" slug="footer" />
</div>

Das Element <main> wird zu einem core/group-Block, der als <main> dargestellt wird, und seine untergeordneten Elemente, einschließlich des Block-Tags core/post-content, werden zu seinen inneren Blöcken. Du kannst Folgendes verwenden:

  • Standard-HTML-Elemente wie <h1>, <p>, <ul>, <div> sowie die Gliederungselemente <main>, <header>, <footer>, <article> und <aside>
  • <block name="namespace/block">
  • <bs:namespace-block>
  • konfigurierte Präfixe für Block-Tags
  • Blockstudio-Blöcke und Komponenten

Wenn WordPress die kompilierte Vorlage rendert, erhalten Vorlagenteil-Blöcke das Attribut des aktiven Themes.

Anpassungen im Site-Editor

Blockstudio stellt die Dateiquelle bereit. WordPress verwaltet Nutzeranpassungen.

Die Suchreihenfolge lautet:

  1. Anpassung aus der Site-Editor-Datenbank
  2. native .html-Datei des aktiven Themes
  3. dateibasierte Quelle von Blockstudio
  4. Fallbacks des übergeordneten Themes oder Plugins

Wenn ein Nutzer eine dateibasierte Vorlage von Blockstudio im Site-Editor speichert, erstellt WordPress einen normalen Datenbankeintrag vom Typ wp_template oder wp_template_part. Dieser gespeicherte Eintrag hat Vorrang vor künftigen Dateiänderungen. Wird die Anpassung zurückgesetzt oder gelöscht, wird wieder die neueste dateibasierte Quelle angezeigt.

Blockstudio schreibt Änderungen aus dem Website-Editor nicht in Dateien unter v1 zurück.

Leistung

Die Vorlagenerkennung wird pro Anfrage zwischengespeichert und zusammen mit Dateiüberwachungsmetadaten gespeichert. Änderungen an einem Manifest oder einer Quelldatei machen den Cache der kompilierten Inhalte ungültig. Datenbankanpassungen werden nicht zwischengespeichert: WordPress prüft sie weiterhin zuerst.

Laufzeitintegrationen, die Dateien aus mehreren Stammverzeichnissen zusammensetzen, können eine logische Erkennungsquelle für Vorlagen und Vorlagenteile bereitstellen. Manifeste und ausgewählte Quellvorlagen können in verschiedenen physischen Stammverzeichnissen liegen und dabei denselben logischen Theme-Baum bilden.

PHP API

PHP
$templates = Blockstudio\Site_Templates::templates();
$parts = Blockstudio\Site_Templates::parts();

$template = Blockstudio\Site_Templates::get_template('front-page');
$header = Blockstudio\Site_Templates::get_part('header');

$paths = Blockstudio\Site_Templates::get_paths();

Übergib eine explizite Liste, um nur exakte Slugs, Pfade oder Quellpfade zu lesen und zu kompilieren:

PHP
$templates = Blockstudio\Site_Templates::templates([
    'front-page',
]);

$parts = Blockstudio\Site_Templates::parts([
    'header',
]);

$errors = Blockstudio\Site_Templates::selection_errors('templates');

Wird das Argument weggelassen, bleibt das vollständige Verhalten der Registry erhalten. Eine leere Liste liefert keine Einträge zurück. Herkömmliche Slug- und Pfadanfragen beschränken die Erkennung auf passende Verzeichnisse. Für benutzerdefinierte Manifest-Slugs kann ein Metadaten-Scan nötig sein, doch nicht zugehörige Quellen werden weiterhin weder kompiliert noch zurückgegeben.

Vorlagen-Hilfsfunktionen sind ebenfalls verfügbar:

PHP
blockstudio_site_templates();
blockstudio_site_template_parts();
blockstudio_site_template('front-page');
blockstudio_site_template_part('header');

Hooks

Der vollständige Erweiterungsumfang für Website-Vorlagen ist:

Hook Typ Beschreibung
blockstudio/site_templates/template_paths Filter Passt die Erkennungs-Stammverzeichnisse vollständiger Vorlagen an.
blockstudio/site_templates/part_paths Filter Passt die Erkennungs-Stammverzeichnisse für Vorlagenteile an.
blockstudio/site_templates/paths Filter Passt beide Pfadlisten als templates und parts an.
blockstudio/site_templates/template_candidates Filter Passt die Kandidaten für Quelldateien eines Manifests an.
blockstudio/site_templates/templates Filter Passt die von der Registry API zurückgegebenen Vorlagen an.
blockstudio/site_templates/parts Filter Passt die von der Registry API zurückgegebenen Vorlagenteile an.
blockstudio/site_templates/template_content Filter Passt die kompilierte Quelle einer vollständigen Vorlage vor dem Parsen an.
blockstudio/site_templates/part_content Filter Passt die kompilierte Quelle eines Vorlagenteils vor dem Parsen an.
blockstudio/site_templates/parser Filter Ersetzt die Instanz von Html_Parser für ein Element.
blockstudio/site_templates/source_compiled Aktion Wird unmittelbar vor dem Kompilieren einer ausgewählten Quelle ausgeführt.
blockstudio/site_templates/discovered Aktion Wird nach einem Durchlauf zur erstmaligen Erkennung und Kompilierung ausgeführt.
blockstudio/site_templates/registered Aktion Wird ausgeführt, nachdem die neu aufgebaute Registry gespeichert wurde.

Erkennungspfade hinzufügen oder ersetzen:

PHP
add_filter('blockstudio/site_templates/template_paths', function ($paths) {
    $paths[] = get_stylesheet_directory() . '/site-templates';
    return $paths;
});

add_filter('blockstudio/site_templates/part_paths', function ($paths) {
    $paths[] = get_stylesheet_directory() . '/site-parts';
    return $paths;
});

add_filter('blockstudio/site_templates/paths', function ($paths) {
    return $paths;
});

Erkannte Daten filtern:

PHP
add_filter('blockstudio/site_templates/templates', function ($templates) {
    return $templates;
});

add_filter('blockstudio/site_templates/parts', function ($parts) {
    return $parts;
});

Quelle vor dem Parsen filtern:

PHP
add_filter('blockstudio/site_templates/template_content', function ($content, $template) {
    return $content;
}, 10, 2);

add_filter('blockstudio/site_templates/part_content', function ($content, $part) {
    return $content;
}, 10, 2);

Quellkandidaten oder Parser ändern:

PHP
add_filter(
    'blockstudio/site_templates/template_candidates',
    function ($candidates, $directory, $manifest) {
        $candidates[] = $directory . '/template.custom.php';
        return $candidates;
    },
    10,
    3
);

add_filter(
    'blockstudio/site_templates/parser',
    function ($parser, $item) {
        return $parser;
    },
    10,
    2
);

discovered und registered sind Lifecycle-Aktionen zum Neuaufbau des Caches. Bei einem Treffer im warmen Registry-Cache werden sie nicht ausgelöst.