コンテンツへスキップ

属性のフィルタリング

Blockstudioには、ブロック属性をフィルタリングする2つのメソッドがあります。

属性定義

blockstudio/blocks/attributesは各フィールド定義をフィルタリングし、Blockstudioはブロックを構築して登録します。エディターのコントロール、デフォルト値、条件、選択肢、およびレンダリング時の値の検証に使う定義を調整できます。

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

上記のコードはlineNumbersのデフォルト値をtrueに設定し、languageがcssに設定されていない限りフィールドを非表示にします。

コールバックは呼び出しごとに、ネストされたグループフィールドやリピーターフィールドも含む1つのフィールド定義を受け取ります。ブロックの登録時に実行され、フロントエンドのレンダリングごとには実行されません。

フィルタリングされた選択肢の定義は、レンダリング用の属性マップにも使用されます。たとえば、select、radio、checkboxフィールドに追加した選択肢は、エディターで利用でき、Blockstudioがテンプレート用に保存値を解決するときも有効です。

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

レンダリングされる値

blockstudio/blocks/attributes/renderは、解決済みの単一フィールドの値をブロックテンプレートに渡す直前にフィルタリングします。各フィールドに対して1回実行されるため、コールバックには値、フィールドキー、ブロックデータが渡されます。

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

上記の例では、lineNumbersについて、エディターに保存された値がすべて上書きされます。コールバックは3つの引数を受け取るように登録してください(add_filterの最後の引数)。そうしないと、WordPressが値のみを渡します。

  • $value: テンプレートが$a[$key]として受け取る形式の、フィールドの解決済みの値。テンプレートに渡す値を返します。
  • $key: $aで使用されるフィールドのキー。リピーター行内では、行内のフィールドIDです。
  • $block: テンプレートが$blockまたは$bとして受け取るブロックデータ配列。id、name、postId、postType、index、indexTotal、contextとアイランドフラグを含みます。拡張機能をBlockstudioブロックではないブロックに適用した場合、$blockにはblockstudioエントリ(attributesとdisabled)のみが格納され、nameはありません。

このフィルターは、classNameやanchorなど、Blockstudioフィールドではない属性や、ファイルフィールドの<id>__sizeコンパニオンにも実行されます。そのため、値を変更する前に$keyを比較してください。戻り値で置き換わるのは$keyの値のみです。このフィルターで$aに新しいキーを追加することはできません。

フィールド設定を変更する場合は定義フィルターを、リクエストに応じてテンプレートの値を計算または上書きする場合はレンダーフィルターを使用してください。

値をレンダリングせずにbs_block_values()経由で読み取る場合、このフィルターが$blockで受け取るのはブロック名のみです。 レンダーカウンターなど、レンダリング時のみのメタデータは、このヘルパーでは作成されません。