属性のフィルタリング
Blockstudioには、ブロック属性をフィルタリングする2つのメソッドがあります。
属性定義
blockstudio/blocks/attributesは各フィールド定義をフィルタリングし、Blockstudioはブロックを構築して登録します。エディターのコントロール、デフォルト値、条件、選択肢、およびレンダリング時の値の検証に使う定義を調整できます。
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がテンプレート用に保存値を解決するときも有効です。
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回実行されるため、コールバックには値、フィールドキー、ブロックデータが渡されます。
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で受け取るのはブロック名のみです。
レンダーカウンターなど、レンダリング時のみのメタデータは、このヘルパーでは作成されません。