Zum Inhalt springen

Attribute rendern

In Template-Dateien kannst du über die Variablen $attributes oder $a und die jeweilige ID des Felds auf alle Attribute zugreifen.

PHP

PHP
<h1><?php echo $attributes['message']; ?></h1>
<h1><?php echo $a['message']; ?></h1>

Twig

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:

PHP
// 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:

PHP
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 min enthält seine initialen Zeilen.
  • Werte der obersten Ebene und blockstudio.attributes werden 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 returnFormat von label gibt 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
<?php if ($a['message']) : ?>
  <h1><?php echo $a['message']; ?></h1>
<?php endif; ?>

Twig

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
<?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

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.

Das Linkfeld gibt ein Objekt mit URL und Attributen zurück:

PHP

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

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
<?php if ($a['icon']) : ?>
  <div class="icon">
    <?php bs_render_icon($a['icon']); ?>
  </div>
<?php endif; ?>

Twig

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

PHP
<div <?php bs_render_data_attributes($a['attributes']); ?>>
  Content
</div>

Twig

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
<?php $group = bs_get_group($a, 'settings'); ?>
<h1><?php echo $group['title']; ?></h1>
<p><?php echo $group['description']; ?></p>

Twig

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:

JSON
{
  "name": "section-header",
  "attributes": [
    {
      "id": "section-header",
      "type": "group",
      "attributes": [
        { "id": "kicker", "type": "text" },
        { "id": "title", "type": "text" }
      ]
    }
  ]
}
JSON
{
  "blockstudio": {
    "attributes": [
      { "type": "custom/section-header" }
    ]
  }
}
Twig
{% set sectionHeader = fn('bs_get_group', a, 'section-header') %}
<p>{{ sectionHeader.kicker }}</p>
<h2>{{ sectionHeader.title }}</h2>

Repeater

Durchlaufe die Repeater-Elemente:

PHP

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

Twig
{% for item in a.items %}
  <div class="item">
    <h3>{{ item.title }}</h3>
    <p>{{ item.description }}</p>
  </div>
{% endfor %}

Field Patterns Cookbook