Przejdź do treści

Filtrowanie atrybutów

Blockstudio udostępnia dwie metody filtrowania atrybutów bloków.

Definicje atrybutów

blockstudio/blocks/attributes filtruje definicje poszczególnych pól, a Blockstudio buduje i rejestruje blok. Użyj go, aby dostosować kontrolki edytora, wartości domyślne, warunki, opcje oraz definicję służącą do walidacji wartości podczas renderowania.

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

Powyższy kod ustawia domyślną wartość lineNumbers na true i ukrywa pole, dopóki language nie zostanie ustawione na css.

Wywołanie zwrotne otrzymuje jedną definicję pola przy każdym wywołaniu, w tym pola zagnieżdżone w grupach i polach powtarzalnych. Jest uruchamiane podczas rejestracji bloku, a nie przy każdym renderowaniu strony frontendowej.

Przefiltrowane definicje opcji są również używane przez mapę atrybutów renderowania. Na przykład opcja dodana do pola select, radio lub checkbox jest dostępna w edytorze i pozostaje prawidłowa, gdy Blockstudio pobiera zapisaną wartość dla szablonu:

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

Renderowane wartości

blockstudio/blocks/attributes/render filtruje rozwiązaną wartość jednego pola bezpośrednio przed przekazaniem jej do szablonu bloku. Jest uruchamiany raz dla każdego pola, więc wywołanie zwrotne otrzymuje wartość, klucz pola i dane bloku.

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

Powyższy przykład nadpisuje każdą wartość zapisaną w edytorze dla lineNumbers. Zarejestruj wywołanie zwrotne z trzema akceptowanymi argumentami (ostatni argument add_filter), w przeciwnym razie WordPress przekazuje tylko wartość.

  • $value: rozwiązaną wartość pola, w postaci otrzymywanej przez szablon jako $a[$key]. Zwróć wartość, którą powinien otrzymać szablon.
  • $key: klucz pola używany w $a. W wierszu repeatera jest to identyfikator pola w tym wierszu.
  • $block: tablica danych bloku otrzymywana przez szablony jako $block lub $b, wraz z id, name, postId, postType, index, indexTotal, context i flagami wyspy. W przypadku rozszerzeń rozszerzenia zastosowanych do bloku, który nie jest blokiem Blockstudio, $block zawiera tylko wpis blockstudio (attributes i disabled) i nie ma name.

Filtr działa również dla atrybutów, które nie są polami Blockstudio, takich jak className i anchor, oraz dla towarzyszącego pola <id>__size pola plików, dlatego przed zmianą wartości sprawdź $key. Wartość zwracana zastępuje wyłącznie wartość $key; filtr nie może dodawać nowych kluczy do $a.

Użyj filtra definicji do zmiany konfiguracji pól, a filtra renderowania do obliczania lub nadpisywania wartości szablonu na potrzeby żądania.

Gdy wartości są odczytywane przez odczyt pólbs_block_values() zamiast renderowane, filtr otrzymuje w $block tylko nazwę bloku. Ten pomocnik nie tworzy liczników renderowania ani innych metadanych dostępnych wyłącznie podczas renderowania.