コンテンツへスキップ

選択肢の設定

Posts、Users、Termsなどの異なるフィールド型を指定する代わりに、Blockstudioを使うと、block.jsonから直接データを柔軟に設定できます。この機能はselect、radio、checkbox、color、gradientのフィールド型で利用できます。

データは次の4つの方法で設定できます。

  • Query – 投稿、ユーザー、またはタームのクエリ結果を返す
  • Fetch – 外部ソースから結果を取得する
  • Function – カスタム関数の結果を返す
  • Custom – カスタムデータセットの結果を返す

クエリ

クエリモードを選択すると、Posts、Users、Termsのデータを設定できます。

JSON
{
  "$schema": "https://blockstudio.dev/schema/block",
  "name": "blockstudio/native",
  "title": "Native Block",
  "blockstudio": {
    "attributes": [
      {
        "id": "posts",
        "type": "select",
        "label": "Posts",
        "populate": {
          "type": "query",
          "query": "posts"
        }
      }
    ]
  }
}

利用可能なクエリ型は、内部で次のWordPress関数を使用します。

クエリ 関数
posts get_posts
users get_users
terms get_terms

引数

arguments属性を使ってカスタム引数を渡せます。

JSON
{
  "blockstudio": {
    "attributes": [
      {
        "id": "posts",
        "type": "select",
        "label": "Posts",
        "populate": {
          "type": "query",
          "query": "posts",
          "arguments": {
            "post_type": "jobs",
            "numberposts": "20"
          }
        }
      }
    ]
  }
}

戻り値の形式

デフォルトでは、Blockstudioは次の値を返します。

クエリ 値 ラベル
posts post object post_title
users user object display_name
terms term object name

returnFormatでレスポンスをカスタマイズできます。

JSON
{
  "blockstudio": {
    "attributes": [
      {
        "id": "posts",
        "type": "select",
        "label": "Posts",
        "populate": {
          "type": "query",
          "query": "posts",
          "arguments": {
            "post_type": "posts",
            "numberposts": "20"
          },
          "returnFormat": {
            "value": "id",
            "label": "post_name"
          }
        }
      }
    ]
  }
}

Fetchモード

fetchオプションを使って動的検索を有効にします。

JSON
{
  "blockstudio": {
    "attributes": [
      {
        "id": "posts",
        "type": "select",
        "label": "Posts",
        "populate": {
          "type": "query",
          "query": "posts",
          "fetch": true,
          "arguments": {
            "post_type": "posts",
            "numberposts": "20"
          }
        }
      }
    ]
  }
}

これによりstylisedUiが有効になり、最初に20件の投稿を取得します。選択フィールドに入力すると、s引数を使って投稿を検索します。

関数

カスタム関数を使って選択肢を設定します。

JSON
{
  "blockstudio": {
    "attributes": [
      {
        "id": "postTypes",
        "type": "checkbox",
        "label": "Post types",
        "populate": {
          "type": "function",
          "function": "get_post_types"
        }
      }
    ]
  }
}

引数

引数は配列として渡します(内部ではcall_user_func_arrayを使用)。

JSON
{
  "blockstudio": {
    "attributes": [
      {
        "id": "postTypes",
        "type": "checkbox",
        "label": "Post types",
        "populate": {
          "type": "function",
          "function": "get_post_types",
          "arguments": [[], "objects"]
        }
      }
    ]
  }
}

戻り値の形式

JSON
{
  "blockstudio": {
    "attributes": [
      {
        "id": "postTypes",
        "type": "checkbox",
        "label": "Post types",
        "populate": {
          "type": "function",
          "function": "get_post_types",
          "arguments": [[], "objects"],
          "returnFormat": {
            "value": "name",
            "label": "label"
          }
        }
      }
    ]
  }
}

選択肢の組み合わせ

静的な選択肢と設定済みのデータを組み合わせます。

JSON
{
  "blockstudio": {
    "attributes": [
      {
        "id": "users",
        "type": "radio",
        "label": "Users",
        "options": [
          {
            "value": "administrators",
            "label": "Administrators"
          },
          {
            "value": "editors",
            "label": "Editors"
          }
        ],
        "populate": {
          "type": "query",
          "query": "users",
          "position": "before"
        }
      }
    ]
  }
}

positionオプション(beforeまたはafter)で、設定済みの選択肢を静的な選択肢の前後どちらに表示するかを指定します。

警告

fetchモードでは、選択肢と設定済みデータを組み合わせることはできません。

カスタムデータ

blockstudio/blocks/attributes/populateフィルターを使って再利用可能なデータセットを作成します。フィルターは、名前をキーとするすべてのカスタムデータセットを含む配列を1つの引数として受け取ります。キーの下にデータセットを追加して、配列を返します。

PHP
add_filter('blockstudio/blocks/attributes/populate', function($options) {
  $options['customData'] = [
    ['value' => '1', 'label' => 'Option 1'],
    ['value' => '2', 'label' => 'Option 2'],
  ];
  return $options;
});

次に、ブロック内でキーを参照します。

JSON
{
  "blockstudio": {
    "attributes": [
      {
        "id": "posts",
        "type": "select",
        "label": "Posts",
        "populate": {
          "type": "custom",
          "custom": "customData"
        }
      }
    ]
  }
}

外部データ

外部ソースからデータを取得します。

JSON
{
  "blockstudio": {
    "attributes": [
      {
        "id": "select",
        "type": "select",
        "label": "Select",
        "multiple": true,
        "populate": {
          "type": "fetch",
          "arguments": {
            "urlSearch": "https://example.com/wp-json/wp/v2/posts?search="
          },
          "returnFormat": {
            "value": "id",
            "label": "title.rendered"
          }
        }
      }
    ]
  }
}

検索語はurlSearchに追加されます。

動的な引数

設定用の引数では、{attributes.*}構文を使って他のブロック属性を参照できます。参照先の属性が変更されると、フィールドの選択肢が自動的に再取得されます。

JSON
{
  "blockstudio": {
    "attributes": [
      {
        "id": "post_type",
        "type": "select",
        "label": "Post Type",
        "options": [
          { "label": "Pages", "value": "page" },
          { "label": "Posts", "value": "post" }
        ]
      },
      {
        "id": "selected_post",
        "type": "select",
        "label": "Select Post",
        "populate": {
          "type": "query",
          "query": "posts",
          "arguments": {
            "post_type": "{attributes.post_type.value}",
            "numberposts": 10
          }
        }
      }
    ]
  }
}

これはすべての設定タイプ(query、function、custom)で動作します。設定内の{attributes.*}を含む値は、クエリ実行前に現在の属性値を使ってクライアント側で解決されます。

参照では、エディターに保存された値が使用されます。選択肢の場合、値には{attributes.post_type.value}を、ラベルには{attributes.post_type.label}を使用してください。returnFormatが制御するのはテンプレートの値であり、ここでのエディターに保存された形式ではありません。

入れ子になった引数は、テンプレート文字列にシリアライズされずに解決されます。1つのプレースホルダーだけで構成される引数は、参照先の型(数値、真偽値、配列、オブジェクトなど)を保持します。他のテキストに埋め込まれたプレースホルダーは文字列になります。参照先がない場合は変更されず、引用符付きの値や複数行の値もそのまま送信されます。 関数コールバックでは、位置引数のリストが保持されます。エディターが検索引数WordPressを追加するのは、queryのpopulateに対してのみで、関数呼び出しには追加されません。

依存する選択肢のレンダリング

ブロックを登録する時点では依存する選択肢は読み込まれません。ブロックの各インスタンスで異なる引数を使用できるためです。レンダリング時には、選択済みの項目を空の選択肢リストと照合して破棄せず、そのまま使用します。populateコールバックがフロントエンドで再実行されることはありません。

このフィールドのreturnFormatは引き続き適用されます:

returnFormat 単一選択 複数選択
value(デフォルト) 保存された値(例: "a") 保存された値の配列(例: ["a", "b"])
label 保存されたラベル 保存されたラベルの配列
both 保存された{value, label}オプション 保存されたオプションの配列

クエリで選択肢を取得する場合、populate.returnFormat.valueが"id"でない限り、値は対応するWordPress投稿、ユーザー、またはタームオブジェクトに解決されます。ラベルは保存された選択内容から取得されます。インポートされた選択内容にラベルがない場合は、その値がラベルとして使用されます。optionsで宣言された一致する静的オプションが保存済みのオプションより優先されるため、現在のラベルが適用されます。

空の選択内容はfalse(またはフィールドに設定されたfallback)のままです。通常の静的オプションの検証には影響しません。保存された値が静的オプションのリストに存在しなくなった場合も、引き続きfalseを返します。

動的セレクトでは、選択肢の読み込みが遅延されている間も、defaultおよびfallbackの選択内容が保持されます。複数選択では、スカラー値、{value, label}オプション、またはいずれかの配列を使用します。スカラー値は、宣言済みの静的オプションと一致しない限り、その値自体がラベルとして使われます。オブジェクト形式のオプションでは指定したラベルが保持され、一致する静的オプションが優先されます。サーバー上では、これらのデフォルト値を検索するためのpopulateコールバックは実行されません。