Attribute rendern
In Template-Dateien kannst du über die Variablen $attributes oder $a und die jeweilige ID des Felds auf alle Attribute zugreifen.
PHP
<h1><?php echo $attributes['message']; ?></h1>
<h1><?php echo $a['message']; ?></h1>
Twig
<h1>{{ attributes.message }}</h1>
<h1>{{ a.message }}</h1>
Attribute programmgesteuert schreiben
Der Editor verschachtelt gespeicherte Werte unter blockstudio.attributes. Alles, was einen Block außerhalb des Editors schreibt, etwa der REST API, WP-CLI, eine Inhaltsmigration oder ein MCP-Server, ermittelt anhand der Attribute, die Blockstudio auf WP_Block_Type registriert, welche Blöcke vorhanden sind, und schreibt sie auf oberster Ebene. Beide Strukturen werden gerendert:
// Top level, as a programmatic writer produces it.
echo do_blocks( '<!-- wp:acme/hero {"visual_type":"media"} /-->' );
// Nested, as the editor saves it.
echo do_blocks( '<!-- wp:acme/hero {"blockstudio":{"attributes":{"visual_type":"media"}}} /-->' );
Nur vom Block deklarierte IDs werden aus der obersten Ebene gelesen. Daher werden die eigenen Attribute von WordPress, etwa anchor, className, lock, metadata und style, nie als Feldwerte übernommen. Wenn dieselbe ID an beiden Stellen vorkommt, hat der verschachtelte Wert Vorrang.
Attribute programmatisch auslesen
Code, der außerhalb des Templates ausgeführt wird, etwa strukturierte Daten auf save_post, Exporte, Suchindizierung oder ein render_block-Filter, benötigt häufig die Werte eines gespeicherten Blocks so, wie sie im Template erscheinen. bs_block_values() gibt sie zurück, ohne den Block zu rendern. Rufe die Funktion nach der Blockregistrierung (init oder später) mit dem vollständigen Array attrs aus parse_blocks() auf:
foreach (parse_blocks($post->post_content) as $block) {
if ($block['blockName'] === null) {
continue;
}
$a = bs_block_values($block['blockName'], $block['attrs']);
if ($a === null) {
// Not a Blockstudio block, and no extension applies.
continue;
}
echo esc_html($a['title'] ?? '');
}
Das Ergebnis ist das $a-Array des Templates, nach Feld-ID geordnet:
- Feldstandardwerte werden angewendet, und ein Repeater mit
minenthält seine initialen Zeilen. - Werte der obersten Ebene und
blockstudio.attributeswerden zusammengeführt, wobei der verschachtelte Wert Vorrang hat. Es werden nur deklarierte IDs aus der obersten Ebene gelesen, und WordPress verwirft einen Wert der obersten Ebene, der nicht dem registrierten Feldtyp entspricht, zum Beispiel einen Auswahl-String, genau wie beim Rendern. - Die Felder passender Erweiterungen werden einschließlich ihrer Standardwerte einbezogen. Eine Erweiterung eines Core- oder Drittanbieter-Blocks liest nur
blockstudio.attributes, wie beim Rendern. - Rückgabeformate werden angewendet: Eine Auswahl mit
returnFormatvonlabelgibt also das Label zurück, und ein Dateifeld die Anhangsdaten. - Deaktivierte und leere Felder werden
false, wie im Template.
null bedeutet, dass weder der Block noch eine Erweiterung von Blockstudio verwaltet wird. Ein Blockstudio-Block ohne Felder gibt [] zurück.
Die Funktion führt dieselbe Transformation wie beim Rendern aus und hat daher dieselben Nebeneffekte: Dateifelder fragen die Anhänge ab, ein Blockfeld, das data nicht zurückgibt, rendert den referenzierten Block, und der Filter blockstudio/blocks/attributes/render wird für jeden Wert ausgeführt. Das Template des Blocks selbst wird nicht gerendert und innerBlocks werden nicht aufgelöst; durchlaufe sie selbst. Ein Codefeld behält eine generierte %selector%-ID, die sich zwischen Aufrufen unterscheidet.
Die Auflösung verwendet den aktuellen WordPress-Kontext. Render-spezifische Metadaten wie Blockzähler und innerBlocks werden nicht erstellt; Attribut-Render-Filter erhalten den Blocknamen, nicht die Metadaten eines vollständig gerenderten Blocks.
Es gibt keine Option, die gespeicherten Werte ohne Transformation abzurufen. Lies dafür direkt das Array attrs oder verwende bs_validate_block(), um sie zu prüfen.
Leere Werte
Attributwerte geben false zurück, wenn das Feld leer ist oder keine Option ausgewählt wurde.
PHP
<?php if ($a['message']) : ?>
<h1><?php echo $a['message']; ?></h1>
<?php endif; ?>
Twig
{% if a.message %}
<h1>{{ a.message }}</h1>
{% endif %}
Komplexe Typen
Dateien
Standardmäßig (ohne returnFormat oder mit "returnFormat": "object") gibt das Dateifeld ein Array mit den Daten des Anhangs zurück. Mit "multiple": true gibt es eine Liste dieser Arrays zurück. Eine Datei, deren Anhang nicht mehr existiert, wird false.
| Schlüssel | Beschreibung |
|---|---|
ID |
Die Anhangs-ID. |
title |
Der Anhangstitel. |
alt |
Der Alternativtext. Ist er leer, wird der Anhangstitel verwendet. |
caption |
Die Bildunterschrift. |
description |
Die Beschreibung. |
href |
Der Permalink zur Anhangsseite. |
url |
Die URL der Datei. Mit dem Dropdown für die Größe ("size": true) die URL der ausgewählten Größe. |
sizes |
Die URL und Abmessungen jeder registrierten Bildgröße, siehe unten. |
PHP
<?php if ($a['image']) :
$image = $a['image'];
$sizes = $image['sizes'] ?? [];
?>
<img
src="<?php echo esc_url($sizes['large'] ?? $image['url']); ?>"
alt="<?php echo esc_attr($image['alt']); ?>"
<?php if (isset($sizes['large-width'], $sizes['large-height'])) : ?>
width="<?php echo esc_attr($sizes['large-width']); ?>"
height="<?php echo esc_attr($sizes['large-height']); ?>"
<?php endif; ?>
/>
<?php endif; ?>
Twig
{% if a.image %}
<img
src="{{ (a.image.sizes.large ?? a.image.url)|e('html_attr') }}"
alt="{{ a.image.alt|e('html_attr') }}"
{% if a.image.sizes['large-width'] is defined and a.image.sizes['large-height'] is defined %}
width="{{ a.image.sizes['large-width']|e('html_attr') }}"
height="{{ a.image.sizes['large-height']|e('html_attr') }}"
{% endif %}
/>
{% endif %}
sizes enthält einen Eintrag pro registrierter Bildgröße sowie full: das URL unter dem Größennamen und die Abmessungen unter <size>-width und <size>-height. Für einen Anhang, für den keine Größe WordPress generiert wurde, wird die Originaldatei mit ihren Abmessungen zurückgegeben. Kann WordPress weder ein Bild noch eine Vorschau auflösen, fehlt der Schlüssel sizes. Beispielsweise hat ein PDF ohne generierte Vorschau kein sizes, aber ein PDF mit Vorschau-Metadaten kann Bildgrößen haben. sizes ist null, wenn keine Bildgrößen registriert sind oder wenn der Filter files/sizes Filter sie deaktiviert. Dieser Filter kann die Zuordnung außerdem verkürzen. Prüfe daher, ob eine Größe vorhanden ist, bevor du ihre Abmessungen ausliest, wie in den Beispielen oben.
Das Objekt hat keine Schlüssel für width, height, mime, type oder size. Lies die Abmessungen aus sizes aus oder verwende ID mit Funktionen wie wp_get_attachment_image() und get_post_mime_type().
Rückgabeformate
returnFormat ändert, was das Feld zurückgibt:
returnFormat |
Wert |
|---|---|
"object" (Standard) |
Das oben beschriebene Array. |
"id" |
Die gespeicherte Anhangs-ID oder eine Liste von IDs mit "multiple": true. |
"url" |
Die URL als String oder eine Liste von URLs mit "multiple": true. Bilder verwenden die mit returnSize festgelegte Größe (Standard: full), andere Dateien ihren Datei-URL. |
Link
Das Linkfeld gibt ein Objekt mit URL und Attributen zurück:
PHP
<?php if ($a['link']) : ?>
<a
href="<?php echo $a['link']['url']; ?>"
target="<?php echo $a['link']['target']; ?>"
>
<?php echo $a['link']['title']; ?>
</a>
<?php endif; ?>
Twig
{% if a.link %}
<a href="{{ a.link.url }}" target="{{ a.link.target }}">
{{ a.link.title }}
</a>
{% endif %}
Icon
Das Iconfeld gibt ein Objekt mit den Schlüsseln set, subSet und icon zurück. Verwende die Hilfsfunktionen bs_render_icon() und bs_icon(), um das SVG auszugeben:
PHP
<?php if ($a['icon']) : ?>
<div class="icon">
<?php bs_render_icon($a['icon']); ?>
</div>
<?php endif; ?>
Twig
{% if a.icon %}
<div class="icon">
{{ bs_icon(a.icon) }}
</div>
{% endif %}
bs_render_icon() gibt das SVG direkt aus. bs_icon() gibt es als String zurück.
Attribute
Der Feldtyp „Attribute“ gibt ein Array aus {attribute, value}-Paaren zurück, die als HTML-Attribute gerendert werden. Verwende bs_render_data_attributes(), um sie auszugeben:
PHP
<div <?php bs_render_data_attributes($a['attributes']); ?>>
Content
</div>
Twig
<div {{ fn('bs_render_data_attributes', a.attributes) }}>
Content
</div>
bs_render_data_attributes() gibt die Attribute direkt aus. bs_data_attributes() gibt den String zurück.
Gruppe
Gruppenfelder stellen den IDs ihrer untergeordneten Attribute den Gruppennamen voran. Verwende bs_get_group(), um Gruppenfelder in ein übersichtliches Array zu extrahieren:
PHP
<?php $group = bs_get_group($a, 'settings'); ?>
<h1><?php echo $group['title']; ?></h1>
<p><?php echo $group['description']; ?></p>
Twig
{% set group = fn('bs_get_group', a, 'settings') %}
<h1>{{ group.title }}</h1>
<p>{{ group.description }}</p>
Dadurch wird das Gruppenpräfix aus den Attributschlüsseln entfernt. Zum Beispiel wird $a['settings_title'] zu $group['title'].
Die Hilfsfunktion funktioniert auch, wenn die Gruppe aus einem wiederverwendeten benutzerdefinierten Feld stammt:
{
"name": "section-header",
"attributes": [
{
"id": "section-header",
"type": "group",
"attributes": [
{ "id": "kicker", "type": "text" },
{ "id": "title", "type": "text" }
]
}
]
}
{
"blockstudio": {
"attributes": [
{ "type": "custom/section-header" }
]
}
}
{% set sectionHeader = fn('bs_get_group', a, 'section-header') %}
<p>{{ sectionHeader.kicker }}</p>
<h2>{{ sectionHeader.title }}</h2>
Repeater
Durchlaufe die Repeater-Elemente:
PHP
<?php foreach ($a['items'] as $item) : ?>
<div class="item">
<h3><?php echo $item['title']; ?></h3>
<p><?php echo $item['description']; ?></p>
</div>
<?php endforeach; ?>
Twig
{% for item in a.items %}
<div class="item">
<h3>{{ item.title }}</h3>
<p>{{ item.description }}</p>
</div>
{% endfor %}