Seiten und Muster
Mit Blockstudio kannst du WordPress-Seiten, Blockmuster und Vorlagen für den Site-Editor als Dateien in deinem Theme definieren. Schreibe Vorlagen im Stil von HTML, und der Parser von Blockstudio wandelt sie in native WordPress-Blöcke um.
- Seiten werden als WordPress-Beiträge mit der Datenbank synchronisiert, sodass Dateivorlagen und Seiteninhalte übereinstimmen.
- Muster werden über
register_block_pattern()im Arbeitsspeicher registriert und stehen im Block-Inserter bereit, wo Nutzer sie beliebig einfügen können. - Website-Vorlagen stellen dateibasierte
wp_template– undwp_template_part-Quellen für den WordPress-Site-Editor bereit.
Alle drei Funktionen verwenden denselben Parser HTML und dieselbe Blocksyntax.
Dateibasierte Seiten erstellen
Eine praktische Anleitung zu dateibasierten Seitenvorlagen, Synchronisierung und Sperrung.
Ordnerstruktur
theme/
├── pages/
│ ├── about/
│ │ ├── page.json
│ │ └── index.php
│ └── contact/
│ ├── page.json
│ └── index.twig
├── patterns/
├── hero/
│ ├── pattern.json
│ └── index.php
└── cta/
├── pattern.json
└── index.blade.php
├── templates/
└── front-page/
├── template.json
└── index.php
└── parts/
└── header/
├── part.json
└── index.php
Jeder Unterordner enthält eine JSON-Konfigurationsdatei (page.json, pattern.json, template.json oder part.json) sowie eine Vorlagendatei.
Vorlagen-Engines
Vorlagen können als einfaches Markup in index.php oder mit Twig oder Blade geschrieben werden:
| Datei | Engine | Voraussetzung |
|---|---|---|
index.php |
Keine (wird unverändert gelesen, PHP-Code wird nicht ausgeführt) | Keine |
index.twig |
Twig | Timber |
index.blade.php |
Blade | illuminate/view |
Wenn mehrere Vorlagendateien vorhanden sind, gilt folgende Prioritätsreihenfolge: index.php > index.blade.php > index.twig.
Da Vorlagen bei der Initialisierung und damit vor jedem Request-Kontext kompiliert werden, haben Twig- und Blade-Vorlagen keinen Zugriff auf dynamische Variablen. Sie eignen sich für integrierte Funktionen und Filter wie {{ "text"|upper }} oder {{ strtoupper("text") }}.
Zuordnung von HTML zu Blöcken
Standard-HTML-Elemente werden automatisch in die entsprechenden WordPress-Blöcke umgewandelt.
Text
| HTML | Block |
|---|---|
<p> |
core/paragraph |
<h1> – <h6> |
core/heading |
<ul> |
core/list (ungeordnet) |
<ol> |
core/list (geordnet) |
<li> |
core/list-item |
<blockquote> |
core/quote |
<code> |
core/code |
<pre> |
core/preformatted |
Listen behalten ihre Struktur. Ein <ul> oder <ol> innerhalb eines <li> wird zu einem inneren core/list-Block dieses core/list-item – genau die Struktur, die der Editor speichert. So können Listen beliebig tief verschachtelt werden. Ein class an einer Liste oder einem Element wird zu dessen className. So lässt sich ein Blockstil wie is-style-checks über eine Seitendatei festlegen; <block name="core/list" className="..."> funktioniert genauso.
Medien
| HTML | Block |
|---|---|
<img> |
core/image |
<figure> |
core/image (mit Beschriftung) |
<audio> |
core/audio |
<video> |
core/video |
Layout
| HTML | Block |
|---|---|
<div>, <section> |
core/group |
<main>, <header>, <footer>, <article>, <aside> |
core/group, bei dem das Element sein eigenes tagName bleibt |
<hr> |
core/separator |
<details> |
core/details |
<table> |
core/table |
Blocksyntax
Verwende für Blöcke ohne direktes HTML-Äquivalent das Element <block>:
<block name="core/cover" url="https://example.com/hero.jpg">
<h1>Welcome</h1>
<p>Content inside the cover block.</p>
</block>
Kernblöcke
<!-- Pullquote -->
<block name="core/pullquote">
<p>An important quote.</p>
</block>
<!-- Verse -->
<block name="core/verse">Roses are red,
Violets are blue.</block>
<!-- Cover -->
<block name="core/cover" url="https://example.com/image.jpg">
<h2>Cover Title</h2>
</block>
<!-- Embed -->
<block name="core/embed" url="https://youtube.com/watch?v=..." providerNameSlug="youtube" />
<!-- Spacer -->
<block name="core/spacer" height="50px" />
<!-- Gallery -->
<block name="core/gallery">
<img src="https://example.com/1.jpg" alt="Image 1" />
<img src="https://example.com/2.jpg" alt="Image 2" />
</block>
<!-- Columns -->
<block name="core/columns">
<block name="core/column">
<h3>Column 1</h3>
</block>
<block name="core/column">
<h3>Column 2</h3>
</block>
</block>
<!-- Buttons -->
<block name="core/buttons">
<block name="core/button" url="/get-started">Get Started</block>
</block>
<!-- Row (flex layout) -->
<block name="core/group" layout='{"type":"flex","flexWrap":"nowrap"}'>
<p>Item 1</p>
<p>Item 2</p>
</block>
Benutzerdefinierte Blöcke
Dieselbe Syntax funktioniert für jeden registrierten Block:
<block name="blockstudio/section">
<h1>Welcome</h1>
</block>
<block name="acf/hero" title="Hero Title" background="dark">
<p>Inner content becomes InnerBlocks.</p>
</block>
Attribute
HTML-Attribute auf <block>-Elementen werden als Blockattribute übergeben. Unterstützt werden folgende JSON-Werte:
<block name="core/heading" level="3">Custom Heading</block>
<block name="core/group" layout='{"type":"flex","orientation":"vertical"}'>
<p>Stacked content.</p>
</block>
<img src="https://example.com/photo.jpg" alt="Photo" width="800" height="400" />
Attributwerte werden einmal dekodiert, so wie ein Browser sie liest, daher speichern data-animate="[&>span]:fade" und data-animate="[&>span]:fade" denselben Wert.
Bei einem Element, das einem Blockstudio-Block zugeordnet ist, wird jedes Attribut mit dem Block gespeichert. Deklarierte Felder gelangen in das Template; die globalen Attribute, die der Block nicht deklariert (id, style, role, title, lang, dir, hidden, tabindex, aria-* und data-*), werden beim Rendern auf das Wurzelelement des Blocks gesetzt, genau wie bei Block-Tags. In Seiten- und Pattern-Quellen benennt ein html--Präfix lediglich eines dieser globalen Attribute. Daher wird html-role="note" als role weitergegeben, während Event-Handler wie html-onclick nie gerendert werden. Alles andere, einschließlich eines nicht deklarierten class, bleibt im Beitragsinhalt, ohne auf der Seite zu erscheinen, und wp bs pages sync meldet es für jede Seite, die es verarbeitet.
Benutzerdefinierte Block-Renderer
Der HTML-Parser verwendet eine registrierungsbasierte Architektur. Füge mit blockstudio/block_tags/builders einen Builder für einen benutzerdefinierten Block hinzu:
add_filter( 'blockstudio/block_tags/builders', function( $builders, $parser ) {
$builders['acf/hero'] = function( array $attrs, string $inner_content ) {
$inner_blocks = Blockstudio\Block_Tags::parse_inner_blocks( $inner_content );
return array(
'blockName' => 'acf/hero',
'attrs' => $attrs,
'innerBlocks' => $inner_blocks,
'innerHTML' => '',
'innerContent' => array_fill( 0, count( $inner_blocks ), null ),
);
};
return $builders;
}, 10, 2 );
Verwende ihn anschließend in einem beliebigen Template:
<block name="acf/hero" background="dark">
<h1>Welcome</h1>
</block>
Du kannst auch überschreiben, wie Core-Blöcke gerendert werden:
add_filter( 'blockstudio/parser/renderers', function( $renderers, $parser ) {
$renderers['core/paragraph'] = function( array $attrs, string $inner_content ) {
$content = trim( $inner_content );
$attrs['align'] = $attrs['align'] ?? 'center';
return array(
'blockName' => 'core/paragraph',
'attrs' => $attrs,
'innerBlocks' => array(),
'innerHTML' => '<p class="has-text-align-center">' . $content . '</p>',
'innerContent' => array( '<p class="has-text-align-center">' . $content . '</p>' ),
);
};
return $renderers;
}, 10, 2 );
Builder-Callbacks erhalten die geparsten Attribute und den unverarbeiteten inneren Inhalt. Sie müssen ein WordPress-Block-Array zurückgeben. Unter Benutzerdefinierte Renderer findest du die vollständige Filterreihenfolge und ein Container-Beispiel.
Signatur der Builder-Funktion
/**
* @param array $attrs Parsed element or block-tag attributes.
* @param string $inner_content Raw inner content.
* @return array WordPress block array.
*/
function my_builder( array $attrs, string $inner_content ): array {}
Elementzuordnung
Standardmäßig werden übliche HTML-Elemente wie <h1>, <p> und <img> Core-WordPress-Blöcken zugeordnet. Mit dem Filter blockstudio/parser/element_mapping kannst du diese Zuordnung überschreiben und jedes HTML-Element einem anderen Block zuweisen:
add_filter( 'blockstudio/parser/element_mapping', function( $mapping ) {
$mapping['h1'] = 'custom/heading';
$mapping['h2'] = 'custom/heading';
$mapping['p'] = 'custom/paragraph';
$mapping['img'] = 'custom/image';
return $mapping;
}, 10, 2 );
Ist dieser Filter aktiv, erzeugt jedes <h1> in deinen Templates einen custom/heading-Block statt core/heading. Die Attribute des Elements werden an den Zielblock weitergegeben. Ist für den Namen des Zielblocks ein Renderer registriert, wird dieser verwendet. Andernfalls wird eine generische Blockstruktur erstellt.
Das ist nützlich, wenn dein Theme oder Plugin benutzerdefinierte Blocktypen bereitstellt, die in allen Seiten- und Pattern-Templates die Standardtypen ersetzen sollen.
Bei einfachen <p>-Zuordnungen kann Blockstudio innere HTML direkt in ein Richtext-Attribut content eines registrierten Nicht-Core-Blockstudio-Blocks leiten. Der Zielblock muss ein Attribut mit id: "content" und type: "richtext" deklarieren.
Inline-Formatierungen (a, b, br, code, del, em, i, img, ins, mark, s, small, span, strong, sub, sup, u) bleiben im weitergeleiteten Wert erhalten, selbst wenn dasselbe Tag einem Element zugeordnet ist, wie es standardmäßig bei code und img der Fall ist. Ein Absatz, dessen einziges untergeordnetes Element ein Bild ist, wird zu dem Block, dem <img> zugeordnet ist – denselben, den Markdown für ein alleinstehendes Bild erzeugt. Verschachtelte Block-Tags und Block-HTML werden weiterhin als innere Blöcke geparst.
Zuordnungswerte können auch Callables sein, wenn der Zielblock von den Elementattributen abhängt:
add_filter( 'blockstudio/parser/element_mapping', function( $mapping ) {
$mapping['div'] = function( array $attrs ) {
if ( isset( $attrs['width'] ) ) {
return 'theme/row';
}
if ( isset( $attrs['gap'] ) ) {
return 'theme/flow';
}
return 'theme/div';
};
return $mapping;
} );
Benutzerdefinierte Blöcke, die Containerelementen wie <section> und <div> zugeordnet sind, parsen verschachtelte HTML-Elemente rekursiv. So werden innere Überschriften, Bilder, Block-Tags und Absätze zu nativen untergeordneten Blöcken.
Vollständiges Beispiel
Ein vollständiges Seitentemplate, das mehrere Blocktypen kombiniert:
<div>
<h1>Welcome to Our Site</h1>
<p>This is an <strong>introduction</strong> with <em>formatting</em>.</p>
<block name="core/columns">
<block name="core/column">
<h3>Feature One</h3>
<p>First feature description.</p>
</block>
<block name="core/column">
<h3>Feature Two</h3>
<p>Second feature description.</p>
</block>
</block>
<block name="core/cover" url="https://example.com/hero.jpg">
<h2>Our Mission</h2>
<p>Building amazing things together.</p>
</block>
<details>
<summary>FAQ</summary>
<p>Answers to common questions.</p>
</details>
<block name="core/buttons">
<block name="core/button" url="/contact">Contact Us</block>
<block name="core/button" url="/learn-more">Learn More</block>
</block>
</div>