Zum Inhalt springen

Programmatisches Rendern

Da Gutenberg das wichtigste Werkzeug zum Erstellen einfach bearbeitbarer Websites für Kunden geworden ist, bietet es sich an, alle erforderlichen Website-Bereiche als Blöcke umzusetzen. Dieser Ansatz eignet sich für die meisten Fälle. Fortgeschrittene Nutzer und spezielle Anwendungsfälle können es jedoch erfordern, vorhandene Blöcke außerhalb des Editors zu verwenden.

Blockstudio bietet zwei Möglichkeiten, Blöcke programmatisch zu rendern:

  • PHP-Funktionen: bs_render_block und bs_block zum Rendern aus PHP-Code
  • HTML-Tags: <bs:block-name>-Tags, die überall auf der Seite durch die Blockausgabe ersetzt werden

Alle spezifischen Funktionen von Blockstudio wie Inline-Stile, Skripte und bereichsbezogene Stile werden unterstützt.

Islands funktionieren auch über diese Renderpfade. Ein dynamisches Island, das mit bs_render_block(), bs_block() oder einem Block-Tag gerendert wird, gibt denselben Platzhaltermarker zurück wie ein Block aus dem Beitragsinhalt. Sobald dieser Marker in der Antwort enthalten ist, wird die Laufzeitumgebung des Frontends eingebunden.

Strukturierte Kompositionen und vollständige Dokumente

Für langlebige Werkzeuge, Vorschauen, Exporte und Komponentenübersichten solltest du den versionierten Blockstudio\Render API verwenden. Er akzeptiert eine einzelne Deklaration oder eine geordnete Liste und rendert sie ohne Echo-Ausgabe:

PHP
use Blockstudio\Render;

$composition = [
  'root' => 'theme/card',
  'example' => [
    'data' => [
      'heading' => 'Example card',
    ],
    'layers' => [
      [
        'name' => 'theme/button',
        'data' => [
          'label' => 'Continue',
        ],
      ],
    ],
  ],
];

$normalized = Render::normalize($composition);
$html = Render::composition($composition);
$document = Render::document($composition, [
  'title' => 'Component preview',
  'contentElement' => 'main',
  'contentClasses' => ['component-preview'],
]);

Die kanonische normalisierte Deklaration hat vier Schlüssel:

PHP
[
  'name' => 'theme/card',
  'attributes' => [],
  'content' => '',
  'children' => [],
]

data, inner, innerBlocks, root, layers und example dienen der Eingabe und werden bei der Normalisierung entfernt. Verschachtelte Deklarationen werden rekursiv über dieselbe Blockstudio-Pipeline gerendert.

Render::document() gibt schemaVersion, html, body, blocks, assets, warnings und errors zurück. Der Wert assets trennt head, footer, styles, scripts, modules, interactivity, ui und tailwind. Die Blockliste und die Assets umfassen Abhängigkeiten, auf die ausgewählte Vorlagen verweisen, schließen aber nicht zugehörige und nur für den Editor bestimmte Assets aus.

Vollständige Dokumente können bodyClasses/bodyAttributes festlegen und den gerenderten Inhalt optional mit contentElement, contentClasses und contentAttributes umschließen. Für den Wrapper ist nur ein sicherer Elementname zulässig; das zurückgegebene body enthält weiterhin den unumschlossenen gerenderten Inhalt. Die Optionen head und footer fügen vertrauenswürdiges Dokument-Markup an den jeweiligen Positionen ein und sind in der zurückgegebenen Asset-Abhängigkeitsliste enthalten.

Um ein Dokument um HTML zusammenzustellen, das bereits gerendert wurde, gib die bekannten Namen der Stammblöcke an:

PHP
$document = Render::document_from_html(
  $rendered_html,
  ['theme/hero', 'theme/button'],
  ['title' => 'Homepage preview']
);

Verwende Render::content() für serialisierte WordPress-Blockinhalte. Wenn du in einer Anfrage mehrere unabhängige Dokumente renderst, solltest du dazwischen Blockstudio\Batch_Render::reset() aufrufen. Canvas::documents() erledigt das automatisch.

Rendering außerhalb der Seite

Blockstudio fügt vor jedem gerenderten Block einen <!--blockstudio/namespace/slug-->-Kommentar ein. Auf einer Frontend-Seite liest der Puffer diese Kommentare, um zu erkennen, welche Blöcke vorhanden sind, lädt deren Assets und entfernt die Kommentare, bevor die Antwort gesendet wird.

Ausgaben, die diesen Puffer nicht durchlaufen, behalten die Kommentare. Das gilt für REST-Antworten, Feeds, AJAX-Handler und HTML, die du nach do_blocks(), Render::content() oder bs_render_block() an anderer Stelle speicherst oder versendest. Verwende bs_strip_render_markers(), um sie zu entfernen:

PHP
$html = bs_strip_render_markers(do_blocks($post->post_content));

Die Funktion entfernt die Kommentare registrierter Blockstudio-Blöcke und lässt alles andere unverändert, einschließlich anderer HTML-Kommentare. Sie gleicht dieselben Markierungen ab, die der Seitenpuffer entfernt. Rufe sie nach der Blockregistrierung auf (init oder später).

Entferne kein Markup, das noch auf einer gepufferten Frontend-Seite ausgegeben wird. Die Seite benötigt die Kommentare, um zu erkennen, welche Block-Assets geladen werden müssen, und Blockstudio entfernt sie am Ende selbst.

Durch das Entfernen der Kommentare werden keine Assets hinzugefügt. Block-CSS- und JavaScript-Dateien werden nur vom Seitenpuffer eingefügt. Verwende bs_block_assets() oder Render::document(), wenn der Verbraucher sie ebenfalls benötigt.

Blöcke untersuchen

Verwende bs_block_fields() nach der Blockregistrierung (auf init oder später), um die aufgelösten Felddefinitionen abzurufen, ohne interne Registrys auszulesen:

PHP
$fields = bs_block_fields('theme/card');

if ($fields === null) {
  // Unknown block, or not a Blockstudio block.
}

Der Rückgabewert ist das Array der registrierten Felddefinitionen, einschließlich Attributfiltern, erweiterten benutzerdefinierten Feldern, Überschreibungen und verschachtelten Gruppen, Tabs und Repeaters. Ein Blockstudio-Block ohne Felder gibt [] zurück. Das Ergebnis ist eine Kopie: Änderungen daran wirken sich nicht auf den registrierten Block aus.

Dies sind Definitionen, keine gespeicherten Werte. Um gespeichertes Markup zu validieren, verwende bs_validate_block(), statt einen separaten Feld-Walker zu pflegen. Um die Werte zu beschreiben, die ein Block akzeptiert, verwende bs_block_schema(). WordPress-verwaltete Attribute bleiben davon getrennt.

Felder, die von Erweiterungen hinzugefügt werden, sind nicht Teil von bs_block_fields(). Verwende bs_block_extension_fields(), um sie abzurufen. Die Funktion gleicht Erweiterungen anhand des Blocknamens ab und funktioniert daher auch für Core- und Drittanbieterblöcke:

PHP
$fields = array_merge(
  bs_block_fields('core/paragraph') ?? [],
  bs_block_extension_fields('core/paragraph')
);

Der Rückgabewert führt die Felddefinitionen jeder passenden Erweiterung in der Reihenfolge ihrer Registrierung auf und hat dieselbe Struktur wie bs_block_fields(). Für einen Block ohne passende Erweiterung wird [] zurückgegeben. Erweiterungswerte werden im selben attrs.blockstudio.attributes-Objekt wie die eigenen Feldwerte des Blocks gespeichert, sodass alle IDs denselben Namensraum verwenden. Wenn zwei Erweiterungen dieselbe ID definieren, werden beide Definitionen zurückgegeben und bearbeiten denselben Wert; beim Rendern gilt die Definition der später registrierten Erweiterung.

Um die Werte eines gespeicherten Blocks so auszulesen, wie sie dessen Template erhält, verwende bs_block_values().

Verwende bs_block_assets(), um die ermittelten CSS und JavaScript des Blocks zu untersuchen. Für ein vollständiges Vorschaudokument einschließlich verschachtelter Blöcke und gemeinsam genutzter Laufzeitabhängigkeiten verwende Render::document() wie oben beschrieben.

Gespeicherte Werte validieren

Verwende bs_validate_block() nach der Blockregistrierung (init oder später), um programmatisch erzeugte oder importierte Blockattribute vor dem Speichern zu überprüfen:

PHP
$block = parse_blocks($content)[0];
$findings = bs_validate_block($block['blockName'], $block['attrs']);

if ($findings === null) {
  // No Blockstudio fields or matching extensions apply.
} elseif ($findings === []) {
  // No stored-value problems were found.
} else {
  // Review the findings before saving.
}

Übergib das vollständige attrs-Array, nicht nur blockstudio.attributes. Ein Blockstudio-Render akzeptiert deklarierte Felder auch auf der obersten Ebene, und verschachtelte Werte haben Vorrang, wenn beides angegeben ist. Erweiterungen von Core- und Drittanbieterblöcken lesen nur blockstudio.attributes. Ein leerer Blockstudio-Block wird verwaltet und gibt [] zurück, nicht null.

Die Validierung erfolgt ausdrücklich und schreibgeschützt. Sie rendert keine Vorlagen, ändert keine Werte, speichert keine Beiträge, fragt keine Medien ab und führt keine Populate-Callbacks aus. Sie wird bei Speichervorgängen, der Seitensynchronisierung und beim Rendern nicht automatisch ausgeführt. Sie ist weder ein Bereinigungsfilter noch eine Autorisierungsprüfung oder eine Prüfung, ob ein Anhang vorhanden ist.

Jeder Befund enthält diese stabilen Schlüssel:

PHP
[
  'code' => 'unknown_option',
  'path' => 'steps/1/style',
  'source' => 'block',
  'message' => 'This value is not among the field options.',
  'value' => 'c',
  'expected' => ['a', 'b'],
]

Verwende in Tools code, nicht das übersetzte message. source ist block oder extension. Pfade verwenden Speicher-Keys und nullbasierte Zeilen- oder Auswahlindizes von Repeatern, ohne führenden Schrägstrich. Wörtliche ~ und / in einem Key werden als ~0 und ~1 maskiert. Eine Gruppe auf oberster Ebene stellt ihren untergeordneten Feldern ein Präfix voran (cta_title); anonyme Gruppen und Tabs fügen keine Ebene hinzu. Gruppen mit einer ID innerhalb einer anderen Gruppe oder eines Repeaters werden vom Builder nicht unterstützt, daher werden ihre Keys nicht akzeptiert. Nachrichtenfelder haben keinen gespeicherten Wert. Ein Dateifeld erlaubt den zugehörigen <id>__size. Auf der obersten Ebene eines Blockstudio-Blocks gelten Verwaltungs-Keys und globale HTML-Attribute, die an das gerenderte Element weitergereicht werden, nicht als unbekannte Felder. Dadurch sind beliebige Keys in Repeater-Zeilen oder Erweiterungen von Core-Blöcken nicht zulässig.

Code Bedeutung expected
unknown_field Kein beibehaltenes Feld deklariert diesen Speicher-Key. Bekannte Speicher-Keys.
unknown_option Eine Auswahl gehört nicht zu den bekannten Optionen. Zulässige Optionswerte.
wrong_type Die gespeicherte Form wird vom Feld nicht unterstützt. Erwartete Speicherfamilie oder -typ.
too_few_rows, too_many_rows Ein vorhandener Repeater liegt außerhalb seiner min oder max. Die Zeilengrenze.
definition_conflict Anwendbare Definitionen für einen Key erfordern unterschiedliche Speicherformen. Quelle und Feldtyp jeder Definition.
shadowed_value Ein verschachtelter Wert überschreibt einen anderen Feldwert auf oberster Ebene. Der gewinnende verschachtelte Wert.
extension_top_level Das Template kann einen Wert auf oberster Ebene lesen, Erweiterungsbindungen jedoch nicht. Der erforderliche Pfad unter blockstudio/attributes.
unknown_attribute Ein Key auf oberster Ebene eines Blockstudio-Blocks wird vom Render-Pfad nicht gelesen und verworfen. Registrierte Attributnamen, Erweiterungsfelder und blockstudio.
missing_container attributes, disabled, name oder editor ist auf oberster Ebene gespeichert und blockstudio fehlt. Der erforderliche Pfad unter blockstudio.
invalid_container blockstudio oder blockstudio.attributes ist kein Objekt. object.

Die Meldung eines unknown_field-Befunds nennt den nächstgelegenen Speicherschlüssel auf derselben Ebene, wenn er höchstens drei Bearbeitungsschritte entfernt ist – die Regel, die auch unbekannte Einstellungen verwenden: This storage key is not declared by the block or its extensions. Did you mean "title"? expected führt weiterhin alle bekannten Schlüssel auf. Beim Abgleich wird die Groß- und Kleinschreibung ignoriert, und berücksichtigt werden nur Speicherschlüssel aus diesem Container. Die Meldungen sind übersetzt; Integrationen sollten code, path und expected verwenden, statt den Meldungstext auszuwerten.

Ein Key auf oberster Ebene eines Blockstudio-Blocks, der weder ein registriertes Attribut ist (seine Felder sowie die Attribute, die WordPress für supports, lock und metadata hinzufügt), noch ein Feld einer passenden Erweiterung, noch blockstudio, noch ein Verwaltungs-Key oder weitergereichtes HTML-Attribut, wird verworfen, bevor das Template ausgeführt wird. Ein solcher Key, etwa eine falsch eingegebene Feld-ID oder ein Werteobjekt ohne seinen blockstudio-Wrapper, führt zu einem Befund, weil der Block ohne diesen Wert gerendert wird. Blöcke, die nur Erweiterungsfelder enthalten, werden nicht auf Keys auf oberster Ebene geprüft.

Die akzeptierten Formen richten sich nach dem Rendering: Mehrfachauswahlen und Kontrollkästchen können eine Liste, ein Optionsobjekt oder einen importierten Skalar enthalten, einschließlich des numerischen Werts null. Für Zahlen werden numerische Zeichenfolgen akzeptiert. Dateien können Anhang-IDs, ID-Objekte, Listen oder Zeichenfolgenreferenzen enthalten. Link- und Icon-Werte müssen Objekte sein; benutzerdefinierte Feldtypen verwenden ihren registrierten Attributtyp. Ein attributes-Feld enthält eine Liste von Paaren mit einem nicht leeren Namen attribute und einem Skalar value; optionale Metadaten wie data.media bleiben erhalten.

WordPress validiert registrierte Attribute auf oberster Ebene vor dem Rendering. Dadurch kann eine Form abgelehnt werden, die innerhalb von blockstudio.attributes akzeptiert wird. Beispielsweise funktioniert ein Radio-Wert von "a" im verschachtelten Objekt, wird auf oberster Ebene aber verworfen, wo sein registrierter Typ object ist. Ein solcher Wert führt zu wrong_type. Verwende für dieselbe Speicherform das verschachtelte Objekt, das der Editor schreibt.

Fehlende Felder sind nicht erforderlich. Leere verschachtelte Werte (null, false, '', []) und deaktivierte Felder führen zu keinen Wertfehlern. Ein ausdrücklich leerer Repeater wird weiterhin anhand von min geprüft; ein fehlender oder deaktivierter Repeater nicht. Ein leerer Wert auf oberster Ebene wird gemeldet, wenn WordPress ihn verwirft und stattdessen einen nicht leeren Standardwert wiederherstellt. Derselbe Wert im verschachtelten Objekt kann ihn leeren. Definitionskonflikte werden auch gemeldet, wenn für den Key kein gespeicherter Wert vorhanden ist.

Statische Optionen und bereits bei der Registrierung aufgelöste Populate-Optionen werden geprüft, ohne Populate erneut aufzurufen. Remote-fetch-Optionen und Populate-Argumente mit {attributes.*} werden übersprungen. Farb- und Verlaufswerte können benutzerdefiniert sein, sofern nicht disableCustomColors oder disableCustomGradients gesetzt ist. Geprüft werden gespeicherte Werte, nicht default, fallback oder Validierungsregeln des Editors.

Passende Erweiterungsfelder werden für jeden Block einbezogen, auf den sie zielen. Bei der Wurzel innerhalb des Blocks oder seiner Erweiterungen gelten spätere Definitionen, wie beim Rendering. Ein eigenes Blockfeld und ein Erweiterungsfeld bleiben separate Definitionen desselben Keys und gelten beide. In Repeater-Zeilen liest der Renderer aus jeder Quelle das erste Feld mit passender ID; dessen Optionen und Grenzen gelten. Doppelte Definitionen bleiben für die Konfliktdiagnose erhalten: Inkompatible Speicherformen führen zu definition_conflict, auch wenn ein späteres Duplikat beim Rendering nicht gelesen wird.

Die Funktion prüft einen Block. Durchlaufe innerBlocks, wenn du ein Dokument validierst; synchronisierte Muster und andere Referenzen werden nicht automatisch aufgelöst. Der Befehl wp bs blocks validate durchläuft die Blöcke eines oder mehrerer Beiträge und gibt ihre Blockpfade aus.

Websites mit einem benutzerdefinierten Resolver zur Renderzeit können die Befunde anpassen, ohne gespeicherte Daten zu ändern:

PHP
add_filter('blockstudio/blocks/attributes/validate', function($findings, $name, $attrs) {
  if ($name !== 'my-theme/card') {
    return $findings;
  }

  return array_values(array_filter($findings, function($finding) {
    return !($finding['path'] === 'customReference' && $finding['code'] === 'wrong_type');
  }));
}, 10, 3);

Gib immer eine Liste von Befunden zurück; die Rückgabe von [] akzeptiert den Block. Dieser Filter wird nur für verwaltete Blöcke ausgeführt, niemals für das Ergebnis null.

Gespeicherte Werte beschreiben

Verwende bs_block_schema() nach der Blockregistrierung (init oder später), um die Werte zu beschreiben, die ein Block speichert, zum Beispiel um Block-Markup in einem Tool oder einer KI-Integration zu generieren oder Eingaben in einer REST-Route zu prüfen:

PHP
$schema = bs_block_schema('theme/card');

if ($schema === null) {
  // No Blockstudio fields or matching extensions apply.
}

Das Ergebnis ist ein JSON-Schema des Objekts, das in attrs.blockstudio.attributes gespeichert wird. Es umfasst die Felder des Blocks und die Felder passender Erweiterungen sowie die Speicherschlüssel, die bei der Validierung verwendet werden: Eine Gruppe auf oberster Ebene stellt ihren untergeordneten Feldern ein Präfix voran, anonyme Gruppen und Tabs fügen keine Ebene hinzu, und ein Dateifeld ergänzt sein <id>__size-Gegenstück. Repeater sind Listen von Zeilenobjekten mit minItems und maxItems aus min und max. additionalProperties ist am Stamm der Feldspeicherung und in Repeater-Zeilen false. Felder mit Objektwerten, etwa Links und benutzerdefinierte Objekte, können eigene Metadaten enthalten. Ein Block ohne Felder hat kein properties, daher entspricht ihm nur ein leeres Objekt.

Jedes Feld wird in einer kanonischen Form beschrieben, die von bs_validate_block() akzeptiert wird:

Feld Schema
text, textarea, richtext, wysiwyg, code, date, datetime, unit, classes, html-tag, block Eine Zeichenfolge.
number, range Eine Zahl mit minimum und maximum aus min und max.
toggle Ein boolescher Wert.
select, radio, checkbox Ein Optionswert oder eine Liste von Optionswerten für checkbox und multiple mit enum.
color, gradient Eine Zeichenfolge mit enum, wenn disableCustomColors oder disableCustomGradients gesetzt ist.
token Eine Liste von Zeichenfolgen.
files Eine nicht negative Integer-Anhangs-ID oder eine Liste von IDs mit multiple.
link Ein Objekt mit url, title und opensInNewTab; url ist erforderlich.
icon Ein Objekt mit set, subSet und icon; set und icon sind erforderlich.
attributes Eine Liste von Objekten mit einem nicht leeren attribute und einem skalaren value.
repeater Eine Liste von Zeilenobjekten.
Benutzerdefinierte Feldtypen Ihr registrierter Attributtyp.

enum führt die Optionen auf, die bei der Validierung geprüft werden: statische Optionen und Populate-Optionen, die bei der Registrierung bereits aufgelöst wurden. Für entfernte fetch-Optionen und Populate-Argumente mit {attributes.*} gibt es kein enum. Ein Schlüssel mit Definitionen unterschiedlicher Speicherformen wird ausgelassen, da die Validierung alle darunter gespeicherten Werte meldet. Wenn ein Blockfeld und ein Erweiterungsfeld denselben Schlüssel verwenden, führt enum die Werte auf, die beide akzeptieren. Gemeinsam genutzte Repeater führen ihre untergeordneten Felder zusammen und wenden die strengeren Zeilenbeschränkungen beider Definitionen an. In Repeater-Zeilen gilt wie beim Rendern jeweils das erste Feld mit passender ID in jeder Quelle. Ein explizites Feld namens <id>__size hat Vorrang vor einem automatisch hinzugefügten Dateigrößen-Gegenstück.

Wenn für ein geschlossenes Feld keine Optionen verfügbar sind oder sich zwei zutreffende Optionssätze nicht überschneiden, lautet sein kanonischer Wert bei einfacher Auswahl null oder bei Mehrfachauswahl eine leere Liste. Eine leere Optionsliste macht ein Feld nicht uneingeschränkt. Optionen aus entfernten Quellen und attributabhängige Optionen bleiben offen.

label eines Felds wird zu title, sein help wird zu description, und sein default bleibt als Anmerkung erhalten. Das eigene title des Schemas ist der Blocktitel. Felder sind nie erforderlich, und bedingte Logik ist nicht Teil des Schemas.

Beschränkungen verwenden nur Schlüsselwörter, die rest_validate_value_from_schema() prüft, sodass das Schema unverändert als Eingabeschema einer REST-Route oder einer Fähigkeit funktioniert:

PHP
$values = $block['attrs']['blockstudio']['attributes'] ?? [];
$schema = bs_block_schema($block['blockName']);
if ($schema !== null) {
  $result = rest_validate_value_from_schema($values, $schema);
}

Das Schema beschreibt ein Formular pro Feld; bei der Validierung werden auch importierte Formen wie Optionsobjekte, numerische Zeichenfolgen und ID-Objekte akzeptiert. Es ersetzt bs_validate_block() nicht: Konflikte bei Definitionen sind Konfigurationsprobleme und können auch dann zu Befunden führen, wenn der widersprüchliche Schlüssel ausgelassen wird. Validierungsfilter können außerdem websitespezifische Regeln festlegen. Verwende bs_validate_block(), um gespeicherte Inhalte zu prüfen. Websites mit einem benutzerdefinierten Resolver zur Renderzeit können das Schema mit dem Filter blockstudio/blocks/attributes/schema anpassen.

PHP-Funktionen

Ohne Daten

In der einfachsten Form akzeptiert die Funktion einen einzelnen Wert: die ID des Blocks, der auf der Seite gerendert werden soll.

PHP
bs_render_block('blockstudio/cta');

Mit Daten

Um den Block mit eigenen Daten zu rendern, musst du für den ersten Parameter statt eines einzelnen Werts ein Array verwenden. Der Wert im Schlüssel data wird an die Variablen $attributes und $a in deiner Blockvorlage übergeben.

PHP
bs_render_block([
  'id' => 'blockstudio/cta',
  'data' => [
    'title' => 'My title',
    'subtitle' => 'My subtitle',
  ],
]);

Verschachtelung

Mit der Funktion bs_block und der leistungsstarken Variable $content in deinen Blockvorlagen kannst du Blöcke ineinander verschachteln.

PHP
<div>
  <h1><?php echo $a['title']; ?></h1>
  <p><?php echo $a['subtitle']; ?></p>
  <?php echo $content; ?>
</div>
PHP
echo bs_block([
  'id' => 'blockstudio/cta',
  'data' => [
    'title' => 'My title',
    'subtitle' => 'My subtitle',
  ],
  'content' => bs_block([
    'id' => 'blockstudio/button',
    'data' => [
      'text' => 'Button Text',
    ]
  ])
]);

Der Button-Block wird anstelle der Variable $content in der Blockvorlage gerendert.

Eingebettete Blöcke, die mit bs_render_block() oder bs_block() gerendert werden, geben immer frontend-aufgelöstes HTML aus, auch wenn der übergeordnete Block gerade eine Editor-Vorschau rendert. Pseudo-Komponenten der Vorlage wie <RichText /> und <InnerBlocks /> werden aufgelöst, bevor der eingebettete Block zurückgegeben wird.

Mehrere Platzhalter

Du kannst mehrere Inhaltsplatzhalter erstellen, indem du die Variable $content in ein assoziatives Array umwandelst und die passenden Schlüssel in der Funktion bs_block aufrufst.

PHP
<div>
  <?php echo $content['beforeContent']; ?>
  <h1><?php echo $a['title']; ?></h1>
  <p><?php echo $a['subtitle']; ?></p>
  <?php echo $content['afterContent']; ?>
</div>
PHP
echo bs_block([
  'id' => 'blockstudio/cta',
  'data' => [
    'title' => 'My title',
    'subtitle' => 'My subtitle',
  ],
  'content' => [
    'beforeContent' => bs_block([
      'id' => 'blockstudio/badge',
      'data' => ['text' => 'Before Content']
    ]),
    'afterContent' => bs_block([
      'id' => 'blockstudio/button',
      'data' => ['text' => 'Button Text']
    ])
  ]
]);

Block-Tags

Bette beliebige Blöcke mit der Tag-Syntax HTML ein. Es werden zwei Formate unterstützt:

HTML
<bs:acme-hero title="Welcome" />
<block name="acme/hero" title="Welcome" />

Beide Varianten rendern denselben Block. Bei der Syntax <bs:> wird ein Bindestrich zum Namespace-Trennzeichen (acme-hero wird zu acme/hero). Bindestriche werden von links nach rechts geprüft; der erste registrierte Treffer wird verwendet. So werden auch Namespaces mit Bindestrichen aufgelöst: <bs:acme-ui-button> prüft zuerst acme/ui-button, dann acme-ui/button. Bei der Syntax <block> wird der vollständige Blockname als name-Attribut angegeben.

Sowohl Blöcke von Blockstudio als auch Core-WordPress-Blöcke funktionieren. Blockstudio-Blöcke durchlaufen die vollständige Pipeline mit Vorlagen, Tailwind und Assets. Core-Blöcke werden mit den integrierten Block-Renderern über das Block-Renderingsystem von WordPress gerendert.

Funktionsweise

Block-Tags verhalten sich je nach ihrem Einsatzort unterschiedlich:

In Blockvorlagen und Beitragsinhalten werden Tags zur Laufzeit durch gerenderte HTML ersetzt. Die endgültige Markup-Ausgabe des referenzierten Blocks wird direkt in die Seite eingebettet. Im Editor gibt es dafür keinen WordPress-Block. Sie dienen ausschließlich zum Rendern.

In Seiten, Mustern und Website-Vorlagen werden Tags in native WordPress-Blöcke umgewandelt, bevor die Dateiquelle mit WordPress synchronisiert oder registriert wird. Dadurch erscheinen die Blöcke im Editor, lassen sich bearbeiten, sofern das Ziel dies unterstützt, und durchlaufen den vollständigen Blocklebenszyklus von WordPress. Die Tag-Syntax ist eine Kurzform, um Blockinhalte in Vorlagendateien festzulegen.

Dieser Unterschied ist wichtig: Block-Tags in Vorlagen erzeugen eine Ausgabe; Block-Tags in Seiten, Mustern und Website-Vorlagen erzeugen native Blöcke.

In Blockvorlagen

Block-Tags werden in Twig- und PHP-Vorlagen automatisch gerendert. Eine Einstellung ist nicht erforderlich. Dazu gehören die Syntaxen <bs:> und <block> sowie alle registrierten Tags mit Präfix und Alias-Tags. Eine Vorlage kann diese Tags direkt ausgeben, statt bs_render_block() aufzurufen. Die Ausgabe wird als HTML gerendert und direkt in die Vorlagenausgabe des Blocks eingebettet:

Twig
<div class="my-page">
  <bs:mytheme-card title="Featured" />
  <block name="core/separator" />
  <bs:core-paragraph>Rendered by WordPress</bs:core-paragraph>
  <block name="core/heading" level="2">Also WordPress</block>
  <theme-card title="Prefix shorthand" />
</div>

In Beitragsinhalten

Das Rendern auf Seitenebene (Beitragsinhalte, Widget-Bereiche) ist optional und muss aktiviert werden:

JSON
{
  "blockTags": {
    "enabled": true
  }
}

Oder über einen Filter:

PHP
add_filter('blockstudio/settings/block_tags/enabled', '__return_true');

Syntax

Tags ohne schließendes Tag:

HTML
<bs:mytheme-cta title="Get started" variant="primary" />
<block name="core/separator" />

Gepaarte Tags mit innerem Inhalt:

HTML
<bs:mytheme-section layout="wide">
  <p>Content inside the block.</p>
</bs:mytheme-section>

<block name="core/group">
  <block name="core/paragraph">Inside a group.</block>
</block>

Du kannst beide Syntaxen beliebig kombinieren und verschachteln:

HTML
<bs:mytheme-section>
  <block name="core/heading" level="2">Title</block>
  <bs:mytheme-card title="Features" />
  <block name="core/paragraph">Description text.</block>
</bs:mytheme-section>

Präfix-Kurzformen

Block-Tags können auch projektspezifische Präfix-Kurzformen verwenden. Registriere ein Präfix mit einem oder mehreren Namespaces. Blockstudio löst <prefix-slug> dann zum ersten registrierten Block in der Reihenfolge der Namespaces auf:

PHP
add_filter('blockstudio/block_tags/prefixes', function($prefixes) {
  $prefixes['theme'] = ['theme-components', 'bsui'];

  return $prefixes;
});
HTML
<theme-card title="Homepage" />
<theme-button label="Get started" />
<theme-ui-feature-matrix />

Mit dem obigen Beispiel wird <theme-card> zu theme-components/card aufgelöst, <theme-button> fällt auf bsui/button zurück, wenn theme-components/button nicht registriert ist, und <theme-ui-feature-matrix> wird zu theme-components/ui-feature-matrix aufgelöst.

Präfixe können auch kombiniert werden. Wenn ein Tag mit Präfix nicht direkt aufgelöst werden kann und der verbleibende Slug selbst ein registriertes Präfix-Tag ist, wird die Auflösung rekursiv fortgesetzt. So kann ein Markenpräfix auf einem Namespace-Präfix aufbauen:

PHP
add_filter('blockstudio/block_tags/prefixes', function($prefixes) {
  $prefixes['theme'] = ['theme-components'];
  $prefixes['ui'] = ['bsui'];

  return $prefixes;
});
HTML
<theme-ui-input />

<theme-ui-input> hat keinen theme-components/ui-input-Block und fällt daher auf das Präfix ui zurück, wodurch bsui/input aufgelöst wird. Direkte Treffer haben immer Vorrang vor verschachtelter Auflösung, und Zulassungs- und Sperrregeln gelten für den endgültig aufgelösten Block.

Du kannst Präfixe auch in blockstudio.json konfigurieren:

JSON
{
  "blockTags": {
    "prefixes": {
      "theme": ["theme-components", "bsui"]
    }
  }
}

Präfixe dürfen nur Kleinbuchstaben oder Zahlen enthalten, müssen mit einem Buchstaben beginnen und dürfen keine Bindestriche enthalten. Explizite Aliase aus blockstudio/block_tags/tag_aliases haben Vorrang vor der Präfixauflösung. Unbekannte Tags mit Präfix bleiben unverändert.

Präfix- und Alias-Tags bleiben praktische Hilfen beim Erstellen. Die kanonische, portierbare Schreibweise ist immer <bs:namespace-slug>, da sie den tatsächlichen Blocknamen festhält, ohne von Projektfiltern abzuhängen:

HTML
<bs:theme-components-card />
<bs:bsui-input />

Blockstudio Beispiele, generierte Diagnosen und programmgesteuerte Ausgaben verwenden diese kanonische Schreibweise. Projekte, die eine ältere Kurzform entfernen möchten, können die eigenständige Migration zu kanonischen Tags verwenden, die zuerst einen Probelauf ausführt: Migration zu kanonischen Tags ohne WordPress zu starten.

Kernblöcke

Jeder Block mit einem registrierten Renderer kann verwendet werden:

HTML
<bs:core-paragraph>A paragraph</bs:core-paragraph>
<bs:core-heading level="2">A heading</bs:core-heading>
<bs:core-separator />
<bs:core-image url="photo.jpg" alt="Photo" />
<bs:core-buttons>
  <bs:core-button url="/about">About</bs:core-button>
</bs:core-buttons>

Oder mit der Syntax <block>:

HTML
<block name="core/group">
  <block name="core/columns">
    <block name="core/column">
      <block name="core/paragraph">Left column</block>
    </block>
    <block name="core/column">
      <block name="core/paragraph">Right column</block>
    </block>
  </block>
</block>

Zulassungs- und Sperrlisten

Steuere, welche Blöcke über Tags gerendert werden dürfen:

JSON
{
  "blockTags": {
    "enabled": true,
    "allow": ["mytheme/*", "core/*"],
    "deny": ["mytheme/internal-*"]
  }
}

allow beschränkt die Auswahl auf passende Muster. deny schließt passende Muster aus und hat Vorrang. Beide unterstützen *-Platzhalter über fnmatch(). Dies gilt für beide Syntaxformen sowie für das Rendering auf Vorlagen- und Seitenebene.

Filter: blockstudio/block_tags/allow und blockstudio/block_tags/deny.

Durchreichen von HTML

Attribute mit dem Präfix data- werden an das Stammelement des gerenderten Blocks durchgereicht. Attribute mit dem Präfix html- werden ebenfalls durchgereicht, wobei das Präfix entfernt wird. Funktioniert mit beiden Syntaxformen. Ein durchgereichtes Attribut ersetzt den vorhandenen Wert des Stammelements, statt mit ihm zusammengeführt zu werden. Daher ersetzt html-class die Klassen des Blocks.

Ein Blockstudio-Block setzt außerdem globale Attribute, die er nicht als Felder deklariert, auf seinem Stammelement: id, style, role, title, lang, dir, hidden, tabindex und jedes aria-*-Attribut. Ein deklariertes Feld hat immer Vorrang: Ein Block mit einem Feld title erhält stattdessen den Wert aus $a['title']. Weitergereichte Styles laufen über safecss_filter_attr(); der Filter WordPress gilt für Style-Attribute in Beitragsinhalten, und sie werden an einen bereits von der Vorlage gesetzten Style angehängt.

Attributwerte sind HTML. Entitäten werden daher beim Parsen eines Tags einmal dekodiert: title="Tom &amp; Jerry" erreicht die Vorlage als Tom & Jerry und wird bei der Ausgabe erneut maskiert. In Anführungszeichen gesetzte Werte dürfen > enthalten, wie es bei Tailwind-Varianten und Animationsselektoren der Fall ist, sowohl in selbstschließenden als auch in gepaarten Tags.

Jedes andere Attribut, das ein Block nicht deklariert, einschließlich class, erreicht HTML niemals. Wenn WP_DEBUG aktiviert ist, meldet Blockstudio jedes dieser Attribute einmal pro Anfrage über _doing_it_wrong(). Deklariere dafür ein Feld oder schreibe es als data--, aria-– oder html--Attribut.

HTML
<bs:mytheme-card
  title="My Card"
  html-class="featured-card"
  html-id="main-card"
  data-analytics="card-click"
/>

<block name="core/paragraph" html-class="highlight" data-section="intro">
  Highlighted paragraph.
</block>

Benutzerdefinierte Renderer

Registriere benutzerdefinierte Block-Renderer für zusätzliche Blocktypen. Renderer erhalten ein Attributarray und eine Zeichenfolge mit dem inneren Inhalt und geben ein WordPress-Blockarray zurück:

PHP
add_filter('blockstudio/block_tags/builders', function ($builders, $parser) {
    $builders['myplugin/custom-block'] = function (array $attrs, string $inner_content) {
        $html = '<div class="my-block">' . $inner_content . '</div>';
        return [
            'blockName'    => 'myplugin/custom-block',
            'attrs'        => $attrs,
            'innerBlocks'  => [],
            'innerHTML'    => $html,
            'innerContent' => [$html],
        ];
    };
    return $builders;
}, 10, 2);

Für Containerblöcke, die den inneren Inhalt in untergeordnete Blöcke zerlegen müssen, füge innerhalb desselben Filters einen zweiten Eintrag hinzu:

PHP
$builders['myplugin/wrapper'] = function (array $attrs, string $inner_content) {
    $inner_blocks = Blockstudio\Block_Tags::parse_inner_blocks($inner_content);
    $content = ['<div class="my-wrapper">'];
    foreach ($inner_blocks as $block) {
        $content[] = null;
    }
    $content[] = '</div>';
    return [
        'blockName'    => 'myplugin/wrapper',
        'attrs'        => $attrs,
        'innerBlocks'  => $inner_blocks,
        'innerHTML'    => '<div class="my-wrapper"></div>',
        'innerContent' => $content,
    ];
};

blockstudio/block_tags/builders gilt sowohl für Block-Tags als auch für benutzerdefinierte Blöcke, die über blockstudio/parser/element_mapping ausgewählt werden. Dies ist der passende Hook, wenn ein Projektblock mit Elementzuordnung inneren Text in ein Blockstudio-Feld verschieben oder ein benutzerdefiniertes Blockarray erstellen muss.

blockstudio/block_tags/renderers und blockstudio/parser/renderers erhalten dieselbe Registry und Callback-Struktur. Sie bleiben aus Kompatibilitätsgründen und für abschließende Parser-Überschreibungen verfügbar. Die Filter laufen in dieser Reihenfolge:

  1. blockstudio/block_tags/builders
  2. blockstudio/block_tags/renderers
  3. blockstudio/parser/renderers

Ein späterer Filter kann einen Renderer ersetzen, der von einem früheren registriert wurde.

Programmatische Verwendung

Wende das Tag-Rendering auf jede Zeichenfolge aus PHP an:

PHP
$html = apply_filters('blockstudio/block_tags/render', $content);

Komponenten

Block-Tags passen gut zu Komponenten. Komponenten sind Blöcke, die nur programmatisch gerendert werden und nie im Editor erscheinen.

HTML
<bs:mytheme-card title="My Card" description="Card content." />

Parser

Block-Tags werden von einem schlanken Zeichenfolgen-Scanner verarbeitet, der DOMDocument ersetzt. Der Parser verarbeitet sowohl die Syntax <bs:> als auch <block>, gleichnamige verschachtelte Tags mit Tiefenverfolgung, Attributwerte in Anführungszeichen und rekursive Containerblöcke. Er wurde speziell für diesen Anwendungsfall entwickelt, ist in Benchmarks schneller als DOMDocument und WordPress’s WP_HTML_Tag_Processor und vermeidet bekannte Probleme von DOMDocument mit dem Entfernen von Namespace-Präfixen und der Umwandlung von Attributnamen in Kleinbuchstaben.

Für Seiten, Muster und Website-Vorlagen verarbeitet derselbe Parser auch rohe HTML-Elemente (<p>, <div>, <h1> usw.) und ordnet sie den entsprechenden WordPress-Kernblöcken zu.

Wenn eine Elementzuordnung <p> auf einen registrierten Nicht-Kernblock Blockstudio verweist, der ein content-Richtext-Attribut deklariert, wird der innere Inhalt von HTML automatisch diesem content-Attribut zugewiesen. Das gilt auch für Inline-Tags wie code und img, die auf Blockebene Elementen zugeordnet sind. Ein Absatz, dessen einziges Kindelement ein Bild ist, wird zu dem Block, dem <img> zugeordnet ist. Verschachtelte Block-Tags oder blockartige HTML-Elemente werden weiterhin wie gewohnt als innere Blöcke geparst. <block name="core/shortcode"> behält seinen Shortcode-Text als Inhalt des Blocks.