Zum Inhalt springen

Attribute filtern

Blockstudio stellt zwei Methoden zum Filtern von Blockattributen bereit.

Attributdefinitionen

blockstudio/blocks/attributes filtert jede Felddefinition, während Blockstudio einen Block erstellt und registriert. Damit kannst du Editor-Steuerelemente, Standardwerte, Bedingungen, Optionen und die Definition anpassen, die zur Validierung von Werten beim Rendern verwendet wird.

PHP
add_filter('blockstudio/blocks/attributes', function($attribute, $block) {
  if (
    ($block['name'] ?? '') === 'my-theme/code-block' &&
    ($attribute['id'] ?? '') === 'lineNumbers'
  ) {
    $attribute['default'] = true;
    $attribute['conditions'] = [
      [
        [
          'id' => 'language',
          'operator' => '==',
          'value' => 'css'
        ]
      ]
    ];
  }

  return $attribute;
}, 10, 2);

Der obige Code setzt den Standardwert von lineNumbers auf true und blendet das Feld aus, sofern language nicht auf css gesetzt ist.

Der Callback erhält bei jedem Aufruf eine Felddefinition, auch für verschachtelte Gruppen- und Repeater-Felder. Er wird bei der Blockregistrierung ausgeführt, nicht bei jedem Frontend-Rendering.

Gefilterte Optionsdefinitionen werden auch für die Render-Attributzuordnung verwendet. Eine Option, die etwa einem Feld vom Typ select, radio oder checkbox hinzugefügt wird, ist im Editor verfügbar und bleibt gültig, wenn Blockstudio den gespeicherten Wert für ein Template auflöst:

PHP
add_filter('blockstudio/blocks/attributes', function($attribute, $block) {
  if (
    ($block['name'] ?? '') === 'bsui/button' &&
    ($attribute['id'] ?? '') === 'variant'
  ) {
    $attribute['options'][] = [
      'label' => 'Brand',
      'value' => 'brand',
    ];
  }

  return $attribute;
}, 10, 2);

Gerenderte Werte

blockstudio/blocks/attributes/render filtert den aufgelösten Wert eines Feldes unmittelbar bevor er an die Blockvorlage übergeben wird. Der Filter läuft für jedes Feld einmal, sodass ein Callback den Wert, den Feldschlüssel und die Blockdaten erhält.

PHP
add_filter('blockstudio/blocks/attributes/render', function($value, $key, $block) {
  if (($block['name'] ?? '') === 'my-theme/code-block' && 'lineNumbers' === $key) {
    return true;
  }
  return $value;
}, 10, 3);

Das obige Beispiel überschreibt jeden im Editor gespeicherten Wert für lineNumbers. Registriere den Callback mit drei akzeptierten Argumenten (dem letzten Argument von add_filter), andernfalls übergibt WordPress nur den Wert.

  • $value: der aufgelöste Wert des Feldes in der Form, die die Vorlage als $a[$key] erhält. Gib den Wert zurück, den die Vorlage bekommen soll.
  • $key: der Schlüssel des Feldes, wie in $a verwendet. Innerhalb einer Repeater-Zeile ist dies die ID des Feldes in der Zeile.
  • $block: das Blockdaten-Array, das Vorlagen als $block oder $b erhalten, mit id, name, postId, postType, index, indexTotal, context und den Island-Flags. Bei auf einen Block angewendeten Erweiterungen, der kein Blockstudio-Block ist, enthält $block nur den Eintrag blockstudio (attributes und disabled) und hat kein name.

Der Filter läuft auch für Attribute, die keine Blockstudio-Felder sind, etwa className und anchor, sowie für das <id>__size-Pendant eines Dateifeldes. Vergleiche daher $key, bevor du einen Wert änderst. Der Rückgabewert ersetzt nur den Wert von $key; der Filter kann $a keine neuen Schlüssel hinzufügen.

Verwende den Definitionsfilter, wenn du die Feldkonfiguration änderst, und den Render-Filter, wenn du Vorlagenwerte für eine Anfrage berechnest oder überschreibst.

Wenn Werte über bs_block_values() statt gerendert gelesen werden, erhält dieser Filter nur den Blocknamen in $block. Der Helfer erstellt keine Render-Zähler oder andere Metadaten, die nur beim Rendern anfallen.