Vai al contenuto

Filtrare gli attributi

Blockstudio fornisce due metodi per filtrare gli attributi dei blocchi.

Definizioni degli attributi

blockstudio/blocks/attributes filtra la definizione di ogni campo, mentre Blockstudio crea e registra un blocco. Usatelo per modificare i controlli dell’editor, i valori predefiniti, le condizioni, le opzioni e la definizione usata per convalidare i valori durante il rendering.

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);

Il codice sopra imposta il valore predefinito di lineNumbers su true e nasconde il campo, a meno che language non sia impostato su css.

La callback riceve una definizione di campo per ogni invocazione, inclusi i campi gruppo e ripetitore annidati. Viene eseguita durante la registrazione del blocco, non una volta per ogni rendering del frontend.

Le definizioni delle opzioni filtrate vengono usate anche dalla mappa degli attributi di rendering. Ad esempio, un’opzione aggiunta a un campo select, radio o checkbox è disponibile nell’editor e resta valida quando Blockstudio risolve il valore salvato per un template:

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);

Valori renderizzati

blockstudio/blocks/attributes/render filtra il valore risolto di un campo immediatamente prima che venga passato al template del blocco. Viene eseguito una volta per ogni campo, quindi una callback riceve il valore, la chiave del campo e i dati del blocco.

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);

L’esempio precedente sovrascrive qualsiasi valore salvato nell’editor per lineNumbers. Registrate la callback con tre argomenti accettati (l’ultimo argomento di add_filter); altrimenti WordPress passa solo il valore.

  • $value: il valore risolto del campo, nella forma ricevuta dal template come $a[$key]. Restituite il valore che il template deve ricevere.
  • $key: la chiave del campo, come usata in $a. All’interno di una riga di repeater è l’ID del campo nella riga.
  • $block: l’array dei dati del blocco che i template ricevono come $block o $b, con id, name, postId, postType, index, indexTotal, context e i flag dell’isola. Per le estensioni applicate a un blocco che non è un blocco Blockstudio, $block contiene solo la voce blockstudio (attributes e disabled) e non include name.

Il filtro viene eseguito anche per attributi che non sono campi Blockstudio, come className e anchor, e per il valore complementare <id>__size di un campo files; quindi confrontate $key prima di modificare un valore. Il valore restituito sostituisce solo il valore di $key; il filtro non può aggiungere nuove chiavi a $a.

Usate il filtro di definizione per modificare la configurazione dei campi e il filtro di rendering per calcolare o sovrascrivere i valori dei template per una richiesta.

Quando i valori vengono letti tramite bs_block_values() anziché renderizzati, questo filtro riceve solo il nome del blocco in $block. Questo helper non crea i contatori di rendering né altri metadati disponibili solo durante il rendering.