属性のレンダリング
テンプレートファイル内では、$attributes変数または$a変数と各フィールドのIDを使って、すべての属性にアクセスできます。
PHP
<h1><?php echo $attributes['message']; ?></h1>
<h1><?php echo $a['message']; ?></h1>
Twig
<h1>{{ attributes.message }}</h1>
<h1>{{ a.message }}</h1>
属性をプログラムで書き込む
エディターは保存した値をblockstudio.attributesの下にネストします。RESTAPI、WP-CLI、コンテンツの移行、MCPサーバーなど、エディター外でブロックを書き込むものは、WP_Block_Typeに登録されたBlockstudioからブロックを特定し、値をトップレベルに書き込みます。どちらの形式もレンダリングできます。
// Top level, as a programmatic writer produces it.
echo do_blocks( '<!-- wp:acme/hero {"visual_type":"media"} /-->' );
// Nested, as the editor saves it.
echo do_blocks( '<!-- wp:acme/hero {"blockstudio":{"attributes":{"visual_type":"media"}}} /-->' );
トップレベルから読み込まれるのはブロックが宣言したIDだけなので、WordPress自体のanchor、className、lock、metadata、styleなどの属性がフィールド値として取り込まれることはありません。同じIDが両方にある場合は、ネストされた値が優先されます。
属性をプログラムから読み取る
テンプレートの外で実行されるコードでは、save_post上の構造化データ、エクスポート、検索インデックス、またはrender_blockフィルターなどで、保存されたブロックの値をテンプレートと同じ形式で必要とすることがあります。bs_block_values()はブロックをレンダリングせずに値を返します。ブロックを登録した後(init以降)に、parse_blocks()から取得した完全なattrs配列を渡して呼び出します:
foreach (parse_blocks($post->post_content) as $block) {
if ($block['blockName'] === null) {
continue;
}
$a = bs_block_values($block['blockName'], $block['attrs']);
if ($a === null) {
// Not a Blockstudio block, and no extension applies.
continue;
}
echo esc_html($a['title'] ?? '');
}
結果は、フィールドIDをキーとするテンプレートの$a配列です:
- フィールドのデフォルト値が適用され、
minを持つリピーターには初期行が含まれます。 - トップレベルの値と
blockstudio.attributesがマージされ、ネストされた値が優先されます。トップレベルから読み取られるのは宣言済みのIDだけです。また、レンダリング時と同様に、WordPressはフィールドに登録された型と一致しないトップレベルの値(たとえばセレクトの文字列)を除外します。 - 一致する拡張機能のフィールドもデフォルト値とともに含まれます。コアまたはサードパーティのブロックの拡張機能では、レンダリング時と同様に
blockstudio.attributesのみが読み取られます。 - 戻り値の形式が適用されます。そのため、
returnFormatがlabelのセレクトではラベルが返され、ファイルフィールドでは添付ファイルのデータが返されます。 - 無効なフィールドと空のフィールドは、テンプレートと同様に
falseされます。
nullは、ブロックも拡張機能もBlockstudioで管理されていないことを意味します。フィールドのないBlockstudioブロックは[]を返します。
この関数はレンダリングと同じ変換を実行するため、副作用も同じです。ファイルフィールドは添付ファイルをクエリし、dataを返さないブロックフィールドは参照先のブロックをレンダリングし、blockstudio/blocks/attributes/renderフィルターは各値に対して実行されます。ブロック自体のテンプレートはレンダリングせず、innerBlocksも解決しません。これらは自分で走査してください。コードフィールドでは、呼び出しごとに異なる生成済みの%selector% IDが保持されます。
解決には現在のWordPressコンテキストが使われます。ブロックカウンターやinnerBlocksなど、レンダリング時のみのメタデータは作成されません。属性のレンダリングフィルターには、完全にレンダリングされたブロックのメタデータではなく、ブロック名が渡されます。
変換前の保存値を取得するオプションはありません。保存値を取得するにはattrs配列を直接読み取るか、bs_validate_block()を使って確認してください。
空の値
フィールドが空の場合、または選択肢が選ばれていない場合、属性値はfalseを返します。
PHP
<?php if ($a['message']) : ?>
<h1><?php echo $a['message']; ?></h1>
<?php endif; ?>
Twig
{% if a.message %}
<h1>{{ a.message }}</h1>
{% endif %}
複合型
ファイル
デフォルト(returnFormatなし、または"returnFormat": "object"の場合)では、ファイルフィールドは添付ファイルのデータを含む配列を返します。"multiple": trueの場合は、これらの配列のリストを返します。添付ファイルが削除されたファイルはfalseです。
| キー | 説明 |
|---|---|
ID |
添付ファイルのID。 |
title |
添付ファイルのタイトル。 |
alt |
代替テキスト。空の場合は添付ファイルのタイトルが使われます。 |
caption |
キャプション。 |
description |
説明。 |
href |
添付ファイルページのパーマリンク。 |
url |
ファイルのURL。サイズのドロップダウン("size": true)を使う場合は、選択したサイズのURL。 |
sizes |
登録済みのすべての画像サイズのURLと寸法。詳細は以下を参照してください。 |
PHP
<?php if ($a['image']) :
$image = $a['image'];
$sizes = $image['sizes'] ?? [];
?>
<img
src="<?php echo esc_url($sizes['large'] ?? $image['url']); ?>"
alt="<?php echo esc_attr($image['alt']); ?>"
<?php if (isset($sizes['large-width'], $sizes['large-height'])) : ?>
width="<?php echo esc_attr($sizes['large-width']); ?>"
height="<?php echo esc_attr($sizes['large-height']); ?>"
<?php endif; ?>
/>
<?php endif; ?>
Twig
{% if a.image %}
<img
src="{{ (a.image.sizes.large ?? a.image.url)|e('html_attr') }}"
alt="{{ a.image.alt|e('html_attr') }}"
{% if a.image.sizes['large-width'] is defined and a.image.sizes['large-height'] is defined %}
width="{{ a.image.sizes['large-width']|e('html_attr') }}"
height="{{ a.image.sizes['large-height']|e('html_attr') }}"
{% endif %}
/>
{% endif %}
sizesには、登録済み画像サイズごとに1つの項目とfullが含まれます。サイズ名の下にURLがあり、<size>-widthと<size>-heightの下に寸法があります。添付ファイル用に生成されていないサイズWordPressは、元のファイルとその寸法に解決されます。WordPressが画像またはプレビューを解決できない場合、sizesキーは存在しません。たとえば、プレビューが生成されていないPDFにはsizesがありませんが、プレビューのメタデータがあるPDFには画像サイズが含まれることがあります。画像サイズが登録されていない場合、またはfiles/sizesフィルターによって無効にされた場合、sizesはnullです。このフィルターでマップが短くなることもあるため、上の例のように、寸法を読み取る前にサイズが存在するか確認してください。
このオブジェクトにはwidth、height、mime、type、sizeのキーはありません。寸法はsizesから読み取るか、IDをwp_get_attachment_image()やget_post_mime_type()などの関数とともに使ってください。
戻り値の形式
returnFormatによって、フィールドの戻り値が変わります:
returnFormat |
値 |
|---|---|
"object"(デフォルト) |
上記の配列。 |
"id" |
保存された添付ファイルID、または"multiple": trueの場合はIDのリスト。 |
"url" |
文字列としてのURL、または"multiple": trueの場合はURLのリスト。画像にはreturnSizeで設定されたサイズ(デフォルトはfull)を使い、その他のファイルにはファイルのURLを使います。 |
リンク
リンクフィールドは、URLと属性を含むオブジェクトを返します。
PHP
<?php if ($a['link']) : ?>
<a
href="<?php echo $a['link']['url']; ?>"
target="<?php echo $a['link']['target']; ?>"
>
<?php echo $a['link']['title']; ?>
</a>
<?php endif; ?>
Twig
{% if a.link %}
<a href="{{ a.link.url }}" target="{{ a.link.target }}">
{{ a.link.title }}
</a>
{% endif %}
アイコン
アイコンフィールドは、set、subSet、iconのキーを持つオブジェクトを返します。bs_render_icon()およびbs_icon()ヘルパー関数を使ってSVGを出力します。
PHP
<?php if ($a['icon']) : ?>
<div class="icon">
<?php bs_render_icon($a['icon']); ?>
</div>
<?php endif; ?>
Twig
{% if a.icon %}
<div class="icon">
{{ bs_icon(a.icon) }}
</div>
{% endif %}
bs_render_icon()はSVGを直接出力します。bs_icon()は文字列として返します。
属性
attributesフィールド型は、HTML属性として出力する{attribute, value}ペアの配列を返します。出力にはbs_render_data_attributes()を使います。
PHP
<div <?php bs_render_data_attributes($a['attributes']); ?>>
Content
</div>
Twig
<div {{ fn('bs_render_data_attributes', a.attributes) }}>
Content
</div>
bs_render_data_attributes()は属性を直接出力します。bs_data_attributes()は文字列を返します。
グループ
グループフィールドでは、子属性IDの先頭にグループ名が付きます。bs_get_group()を使うと、グループフィールドをすっきりした配列に取り出せます。
PHP
<?php $group = bs_get_group($a, 'settings'); ?>
<h1><?php echo $group['title']; ?></h1>
<p><?php echo $group['description']; ?></p>
Twig
{% set group = fn('bs_get_group', a, 'settings') %}
<h1>{{ group.title }}</h1>
<p>{{ group.description }}</p>
これにより、属性キーからグループの接頭辞が取り除かれます。たとえば、$a['settings_title']は$group['title']になります。
グループが再利用可能なカスタムフィールドに由来する場合も、このヘルパーを使えます。
{
"name": "section-header",
"attributes": [
{
"id": "section-header",
"type": "group",
"attributes": [
{ "id": "kicker", "type": "text" },
{ "id": "title", "type": "text" }
]
}
]
}
{
"blockstudio": {
"attributes": [
{ "type": "custom/section-header" }
]
}
}
{% set sectionHeader = fn('bs_get_group', a, 'section-header') %}
<p>{{ sectionHeader.kicker }}</p>
<h2>{{ sectionHeader.title }}</h2>
リピーター
リピーターの項目をループ処理します。
PHP
<?php foreach ($a['items'] as $item) : ?>
<div class="item">
<h3><?php echo $item['title']; ?></h3>
<p><?php echo $item['description']; ?></p>
</div>
<?php endforeach; ?>
Twig
{% for item in a.items %}
<div class="item">
<h3>{{ item.title }}</h3>
<p>{{ item.description }}</p>
</div>
{% endfor %}