コンテンツへスキップ

属性のレンダリング

テンプレートファイル内では、$attributes変数または$a変数と各フィールドのIDを使って、すべての属性にアクセスできます。

PHP

PHP
<h1><?php echo $attributes['message']; ?></h1>
<h1><?php echo $a['message']; ?></h1>

Twig

Twig
<h1>{{ attributes.message }}</h1>
<h1>{{ a.message }}</h1>

属性をプログラムで書き込む

エディターは保存した値をblockstudio.attributesの下にネストします。RESTAPI、WP-CLI、コンテンツの移行、MCPサーバーなど、エディター外でブロックを書き込むものは、WP_Block_Typeに登録されたBlockstudioからブロックを特定し、値をトップレベルに書き込みます。どちらの形式もレンダリングできます。

PHP
// 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配列を渡して呼び出します:

PHP
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
<?php if ($a['message']) : ?>
  <h1><?php echo $a['message']; ?></h1>
<?php endif; ?>

Twig

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
<?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

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
<?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

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
<?php if ($a['icon']) : ?>
  <div class="icon">
    <?php bs_render_icon($a['icon']); ?>
  </div>
<?php endif; ?>

Twig

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

PHP
<div <?php bs_render_data_attributes($a['attributes']); ?>>
  Content
</div>

Twig

Twig
<div {{ fn('bs_render_data_attributes', a.attributes) }}>
  Content
</div>

bs_render_data_attributes()は属性を直接出力します。bs_data_attributes()は文字列を返します。

グループ

グループフィールドでは、子属性IDの先頭にグループ名が付きます。bs_get_group()を使うと、グループフィールドをすっきりした配列に取り出せます。

PHP

PHP
<?php $group = bs_get_group($a, 'settings'); ?>
<h1><?php echo $group['title']; ?></h1>
<p><?php echo $group['description']; ?></p>

Twig

Twig
{% set group = fn('bs_get_group', a, 'settings') %}
<h1>{{ group.title }}</h1>
<p>{{ group.description }}</p>

これにより、属性キーからグループの接頭辞が取り除かれます。たとえば、$a['settings_title']は$group['title']になります。

グループが再利用可能なカスタムフィールドに由来する場合も、このヘルパーを使えます。

JSON
{
  "name": "section-header",
  "attributes": [
    {
      "id": "section-header",
      "type": "group",
      "attributes": [
        { "id": "kicker", "type": "text" },
        { "id": "title", "type": "text" }
      ]
    }
  ]
}
JSON
{
  "blockstudio": {
    "attributes": [
      { "type": "custom/section-header" }
    ]
  }
}
Twig
{% set sectionHeader = fn('bs_get_group', a, 'section-header') %}
<p>{{ sectionHeader.kicker }}</p>
<h2>{{ sectionHeader.title }}</h2>

リピーター

リピーターの項目をループ処理します。

PHP

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

Twig
{% for item in a.items %}
  <div class="item">
    <h3>{{ item.title }}</h3>
    <p>{{ item.description }}</p>
  </div>
{% endfor %}

フィールドパターンのレシピ集