Vorlagen mit Block-Tags zusammensetzen
Sobald ein Projekt einige Blöcke enthält, müssen Vorlagen miteinander interagieren. Ein Feature-Block soll drei Karten ausgeben. Eine Landingpage braucht einen Abschnitt mit einer Schaltfläche darin. Du kannst für jeden Block bs_render_block() aufrufen, aber eine Vorlage voller PHP-Aufrufe mit verschachtelten Arrays ist schwer zu lesen und noch schwerer zu verschachteln.
Mit Block-Tags schreibst du einen Block direkt an die Stelle, an der seine Ausgabe erscheinen soll, als HTML-Tag:
<bs:acme-card title="Fast" text="Rendered on the server." />
Dasselbe Tag hat je nach Verwendungsort zwei unterschiedliche Bedeutungen. In einer Blockvorlage oder im Beitragsinhalt wird es durch das gerenderte HTML des Blocks ersetzt. In einer Seite, einem Pattern oder einer Site-Template-Quelle wird es zu einem echten WordPress-Block, der im Editor erscheint. In dieser Anleitung erstellen wir einige Blöcke, setzen sie auf beide Arten zusammen, fügen für kürzere Namen ein Projektpräfix hinzu und zeigen anschließend, wie du diese Kurzformen in die portable Schreibweise überführst.
Die Blöcke
Drei kleine Blöcke genügen. Eine Karte mit zwei Feldern:
{
"$schema": "https://blockstudio.dev/schema/block",
"apiVersion": 3,
"name": "acme/card",
"title": "Card",
"blockstudio": {
"attributes": [
{ "id": "title", "type": "text", "label": "Title", "default": "" },
{ "id": "text", "type": "textarea", "label": "Text", "default": "" }
]
}
}
<article useBlockProps class="acme-card">
<h3><?php echo esc_html( $a['title'] ); ?></h3>
<p><?php echo esc_html( $a['text'] ); ?></p>
</article>
Ein Abschnitt, der beliebigen Inhalt umschließt, der in ihn eingefügt wird, mit einem heading-Feld, das wie das der Karte deklariert ist:
<section useBlockProps class="acme-section">
<h2><?php echo esc_html( $a['heading'] ); ?></h2>
<InnerBlocks />
</section>
Und eine Schaltfläche in einem zweiten Namespace, acme-ui/button, mit den Feldern label und href:
<a useBlockProps class="acme-button" href="<?php echo esc_url( $a['href'] ); ?>"><?php echo esc_html( $a['label'] ); ?></a>
Tags in einer Blockvorlage
Blockvorlagen rendern Tags automatisch. Eine Einstellung ist nicht erforderlich. Ein Feature-Block kann direkt zwei Karten und einen Core-Trenner ausgeben:
<div useBlockProps class="acme-features">
<bs:acme-card title="Fast" text="Rendered on the server." />
<block name="acme/card" title="Typed" text="Fields come from block.json." />
<block name="core/separator" />
</div>
Das Rendern von acme/features ergibt:
<!--blockstudio/acme/features--><div class="acme-features wp-block-acme-features">
<!--blockstudio/acme/card--><article class="acme-card wp-block-acme-card">
<h3>Fast</h3>
<p>Rendered on the server.</p>
</article>
<!--blockstudio/acme/card--><article class="acme-card wp-block-acme-card">
<h3>Typed</h3>
<p>Fields come from block.json.</p>
</article>
<hr class="wp-block-separator has-alpha-channel-opacity">
</div>
Jedem Blockstudio-Block in der Ausgabe geht ein <!--blockstudio/namespace/slug-->-Kommentar voraus. Der Seitenpuffer entfernt ihn aus der Antwort. Wenn die Ausgabe den Puffer umgeht, verwende bs_strip_render_markers().
Die beiden Syntaxvarianten sind gleichwertig. <bs:acme-card> kodiert den Blocknamen im Tag, und <block name="acme/card"> übergibt ihn als Attribut. Jedes andere Attribut wird zu einem Feldwert, sodass title die Kartenvorlage als $a['title'] erreicht. Auch Core-Blöcke funktionieren; sie werden mit WordPress und den integrierten Block-Renderern gerendert.
Tags mit öffnendem und schließendem Tag sowie innerem Inhalt
Ein Tag-Paar übergibt seine Inhalte an den Block. Bei einem Blockstudio-Block füllen sie <InnerBlocks /> aus, und darin verschachtelte Tags werden zuerst gerendert:
<bs:acme-section heading="Why Acme">
<bs:acme-card title="Fast" text="Rendered on the server." />
<bs:acme-ui-button label="Get started" href="/start" />
</bs:acme-section>
<!--blockstudio/acme/section--><section class="acme-section wp-block-acme-section">
<h2>Why Acme</h2>
<div>
<!--blockstudio/acme/card--><article class="acme-card wp-block-acme-card">
<h3>Fast</h3>
<p>Rendered on the server.</p>
</article>
<!--blockstudio/acme-ui/button--><a class="acme-button wp-block-acme-ui-button" href="/start">Get started</a>
</div>
</section>
Wie aus einem Tag-Namen ein Blockname wird
Der Name eines <bs:>-Tags enthält keinen Schrägstrich, daher sucht Blockstudio nach einem. Es ersetzt der Reihe nach jeden Bindestrich durch einen Schrägstrich und verwendet den ersten registrierten Treffer. <bs:acme-card> wird bereits beim ersten Versuch zu acme/card aufgelöst. Bei <bs:acme-ui-button> wird zunächst acme/ui-button ausprobiert, aber nichts gefunden; anschließend wird acme-ui/button aufgelöst. Namespaces mit Bindestrichen funktionieren daher ohne Konfiguration, solange nicht beide möglichen Namen existieren.
Kürzere Namen mit Präfixen
<bs:acme-ui-button> ist eindeutig, aber lang. Ein Projektpräfix ordnet einem kurzen Tag-Präfix einen oder mehrere Namespaces zu. Richte es in blockstudio.json ein:
{
"$schema": "https://blockstudio.dev/schema/blockstudio",
"blockTags": {
"prefixes": {
"acme": ["acme"],
"ui": ["acme-ui"]
}
}
}
Oder registriere dieselbe Zuordnung über PHP:
add_filter( 'blockstudio/block_tags/prefixes', function ( $prefixes ) {
$prefixes['acme'] = array( 'acme' );
$prefixes['ui'] = array( 'acme-ui' );
return $prefixes;
} );
Nun wird <acme-card> zu acme/card und <ui-button> zu acme-ui/button aufgelöst. Wenn ein Präfix mehrere Namespaces auflistet, werden sie der Reihe nach durchsucht. Der erste registrierte Block gewinnt, sodass ein Projektblock einen Bibliotheksblock mit demselben Slug überschreiben kann.
Präfixe lassen sich auch kombinieren. <acme-ui-button> sucht zuerst nach acme/ui-button. Dieser Block existiert nicht, und der Rest des Tags, ui-button, ist selbst ein registriertes Präfixtag. Daher wird die Auflösung mit acme-ui/button fortgesetzt. Ein direkter Treffer hat immer Vorrang vor einem verschachtelten.
<bs:acme-section heading="Why Acme">
<acme-card title="Fast" text="Rendered on the server." />
<acme-ui-button label="Get started" href="/start" />
</bs:acme-section>
Damit wird genau dasselbe HTML wie mit der obigen kanonischen Version gerendert.
Für Präfixe gelten einige Regeln:
- Ein Präfix besteht aus Kleinbuchstaben und Zahlen, beginnt mit einem Buchstaben und enthält keine Bindestriche.
- Ein Präfixtag, das zu keinem registrierten Block aufgelöst wird, bleibt unverändert in der Ausgabe.
<acme-missing title="x" />bleibt also wie geschrieben erhalten. - Exakte Aliase aus dem Filter
blockstudio/block_tags/tag_aliaseshaben Vorrang vor Präfixen. Ein Alias ordnet ein Tag mit Bindestrichen einem Block zu. Beispielsweise sorgt$aliases['acme-cta'] = 'acme-ui/button';dafür, dass<acme-cta>die Schaltfläche rendert.
Präfix- und Alias-Tags werden in Blockvorlagen neben <bs:>– und <block>-Tags aus Blockstudio 7.5 gerendert.
Attribute
Attribute, die einer Feld-ID entsprechen, werden zu Feldwerten. Zwei Präfixe haben eine andere Funktion:
data-*-Attribute werden auf das Stammelement des gerenderten Blocks kopiert.html-*-Attribute werden auf das Stammelement kopiert, nachdem das Präfix entfernt wurde. Aushtml-id="intro"wird alsoid="intro".
<bs:acme-card title="Hi" text="There" data-track="card" html-id="intro" html-class="featured" />
<article data-track="card" id="intro" class="featured">
<h3>Hi</h3>
<p>There</p>
</article>
html-class setzt das Attribut, es hängt nichts daran an: Die eigenen acme-card wp-block-acme-card-Klassen des Blocks gehen verloren. Wenn ein Aufrufer Klassen zu einem Block hinzufügen soll, deklariere dafür ein Feld und füge sie in der Vorlage zusammen.
Jedes andere Attribut, das kein deklariertes Feld ist, wird verworfen. Ein einfaches class="wide" auf <bs:acme-card> rendert die Karte ohne dieses Attribut. Blockstudio 7.7 meldet solche Attribute mit einem Hinweis _doing_it_wrong(), wenn WP_DEBUG aktiviert ist.
Dieselben Tags in Seitenquellen
In dateibasierten Seiten, Patterns und Site Templates werden Tags nicht gerendert. Beim Einlesen der Quelle werden sie in Blöcke umgewandelt und erscheinen dadurch im Editor. Diese Seitenquelle:
<bs:acme-section heading="Why Acme">
<p>Everything below is a real block.</p>
<acme-card title="Fast" text="Rendered on the server." />
<acme-ui-button label="Get started" href="/start" />
</bs:acme-section>
wird in dieses Block-Markup umgewandelt (Zeilenumbrüche zur besseren Lesbarkeit hinzugefügt):
<!-- wp:acme/section {"blockstudio":{"attributes":{"heading":"Why Acme"}}} -->
<!-- wp:paragraph --><p>Everything below is a real block.</p><!-- /wp:paragraph -->
<!-- wp:acme/card {"blockstudio":{"attributes":{"title":"Fast","text":"Rendered on the server."}}} /-->
<!-- wp:acme-ui/button {"blockstudio":{"attributes":{"label":"Get started","href":"/start"}}} /-->
<!-- /wp:acme/section -->
Feldwerte landen unter blockstudio.attributes. Dort speichern Blockstudio-Blöcke sie, und der Absatz sowie die beiden inneren Blöcke werden zu inneren Blöcken des Abschnitts. Präfixe und Aliase werden hier genauso aufgelöst wie in Vorlagen.
Tags im Beitragsinhalt
Inhalte aus dem Editor oder Widgets werden standardmäßig nicht durchsucht. Aktiviere das Rendern auf Seitenebene in blockstudio.json:
{
"blockTags": {
"enabled": true
}
}
Anschließend werden Tags in the_content und widget_text mit Priorität 5 gerendert. Mit derselben Option wird ein Filter registriert, der Tags in beliebigen Zeichenfolgen rendert:
$html = apply_filters( 'blockstudio/block_tags/render', $content );
Mit den Mustern allow und deny kannst du einschränken, welche Tags gerendert werden dürfen. Sie akzeptieren fnmatch()-Platzhalter und gelten für jede Syntax und beide Render-Modi:
{
"blockTags": {
"enabled": true,
"deny": ["acme-ui/*"]
}
}
Mit dieser Regel bleiben <acme-ui-button> und <bs:acme-ui-button> ungerendert in der Ausgabe. deny hat Vorrang vor allow. Die Filter blockstudio/block_tags/allow und blockstudio/block_tags/deny ändern dieselben Listen aus PHP.
Die Analyse prüft die kanonische Schreibweise
Die PHPStan-Erweiterung validiert Block-Tags in PHP-, Twig- und Blade-Vorlagen. Ein falsch geschriebenes Feld oder ein falscher Blockname wird zusammen mit dem Block gemeldet, zu dem er aufgelöst wurde:
3 Block tag "acme/card" has unknown attribute "txt" in index.php
🪪 blockstudio.blockTag.attribute
4 Block tag references unknown block "acme/cards" in index.php
🪪 blockstudio.blockTag.unknown
In Version 7.6 gilt dies für Tags <bs:> und <block>. Ein Präfixtag wie <acme-card txt="..."> wird nicht geprüft. Blockstudio 7.7 erweitert die Regel auf Präfixtags, Seitenquellen und zugeordnete HTML-Elemente. Der Hinweis listet außerdem die globalen Attribute auf, die ein Tag weitergeben darf.
Kurzformen in die kanonische Schreibweise überführen
Präfix- und Alias-Tags sind praktische Hilfen für ein Projekt. Sie werden nur aufgelöst, wenn die Filter und Einstellungen des Projekts geladen sind. Eine Vorlage, die in ein anderes Projekt oder eine Blockbibliothek kopiert wird oder im Kontext eines Coding-Agenten landet, verliert daher ihre Bedeutung. <bs:namespace-slug> erfasst den tatsächlichen Blocknamen und wird überall aufgelöst. Deshalb verwenden auch die Beispiele, Diagnosen und generierten Ausgaben von Blockstudio diese Schreibweise.
Ein eigenständiger Befehl wandelt Kurzformen in diese Schreibweise um. Angenommen, die Quellen eines Projekts verwenden noch die Kurzformen, einschließlich eines Alias, eines Tags für einen nicht mehr vorhandenen Block und eines Beispiels in einem Codebeispiel:
<div useBlockProps class="acme-features">
<acme-card title="Fast" text="Rendered on the server." />
<acme-ui-button label="Get started" href="/start" />
</div>
<acme-section heading="Why Acme">
<acme-cta label="Talk to us" href="/contact" />
<acme-quote text="Missing block" />
</acme-section>
<pre><code><acme-card /> <acme-card title="Example" /></code></pre>
Der Befehl lädt WordPress nicht. Daher erhält er die Projektkonfiguration als JSON-Dateien, die außerhalb des durchsuchten Verzeichnisbaums liegen:
{ "acme": ["acme"], "ui": ["acme-ui"] }
["acme/card", "acme/section", "acme/features", "acme-ui/button"]
{ "acme-cta": "acme-ui/button" }
Beginne mit einem Probelauf. Er ist auch der Standard:
php vendor/blockstudio/blockstudio/bin/migrate-block-tags.php \
--root="$PWD" \
--prefix-map=/tmp/acme-tags/prefixes.json \
--known-blocks=/tmp/acme-tags/blocks.json \
--aliases=/tmp/acme-tags/aliases.json \
--report=/tmp/acme-tags/report.json \
--dry-run
Report: /tmp/acme-tags/report.json
Dry run: 2 files, 2 changed, 5 replacements, 1 unknown, 0 ambiguous, 1 manual.
Der Bericht führt alle Zuordnungen auf, die angewendet würden, sowie alle Fälle, bei denen keine Vermutung angestellt wird:
{
"mappings": [
{ "legacy": "acme-card", "canonical": "bs:acme-card", "block": "acme/card", "occurrences": 1 },
{ "legacy": "acme-cta", "canonical": "bs:acme-ui-button", "block": "acme-ui/button", "occurrences": 1 },
{ "legacy": "acme-section", "canonical": "bs:acme-section", "block": "acme/section", "occurrences": 2 },
{ "legacy": "acme-ui-button", "canonical": "bs:acme-ui-button", "block": "acme-ui/button", "occurrences": 1 }
],
"unknown": [
{ "path": "pages/home/index.php", "line": 3, "column": 4, "tag": "acme-quote", "reason": "no-known-block" }
],
"manual": [
{ "path": "pages/home/index.php", "line": 5, "column": 33, "tag": "acme-card", "reason": "code-sample" }
]
}
Der Bericht ist hier gekürzt. Außerdem hält er Konfigurationen sowie Vorher- und Nachher-Hashes für jede Datei fest. Die öffnenden und schließenden Tags des Abschnitts zählen als zwei Vorkommen. acme-quote entspricht dem Präfix acme, bezeichnet aber keinen bekannten Block und ist daher unbekannt. Das acme-card in <pre><code> ist ein Beispiel, kein Markup. Es wird zur manuellen Prüfung gemeldet und niemals umgeschrieben. Dasselbe gilt für HTML-Kommentare und Inline-Code.
Die Anwendung wird verweigert, solange unbekannte, mehrdeutige oder dynamische Tags vorhanden sind:
Error: Unresolved tags remain; no files were written. Review a dry-run report or pass --allow-unresolved.
Der Befehl wird mit 2 beendet. Korrigiere das unbekannte Tag, indem du es hier entfernst, und führe den Befehl mit --apply statt --dry-run aus:
Applied: 2 files, 2 changed, 5 replacements, 0 unknown, 0 ambiguous, 1 manual.
Nur die Tagnamen ändern sich. Attribute bleiben bytegenau erhalten:
<bs:acme-section heading="Why Acme">
<bs:acme-ui-button label="Talk to us" href="/contact" />
</bs:acme-section>
Ein erneuter Probelauf mit dem Ergebnis meldet 0 changed, 0 replacements. Die Präfixe können anschließend registriert bleiben, sodass nichts kaputtgeht, während andere Branches noch die Kurzform verwenden.
Nächste Schritte
- Rendering: die vollständige Tag-Syntax, benutzerdefinierte Renderer und der Parser
- Einstellungen: alle Optionen von
blockTags - Dateibasierte Seiten erstellen: Seitenquellen, in denen Tags zu bearbeitbaren Blöcken werden
- Block-Tags migrieren: alle Optionen des Migrationsbefehls
- Vorlagen mit PHPStan prüfen: die Analyse ausführen, die Tags validiert