Populating Options
Instead of supplying different field types like Posts, Users or Terms, Blockstudio allows for a modular way of populating data right from the block.json. This feature works for select, radio, checkbox, color and gradient field types.
Data can be populated in four ways:
- Query – Return results from a post, user or term query
- Fetch – Return results from an external source
- Function – Return results from a custom function
- Custom – Return results from a custom dataset
Query
When choosing query mode, Posts, Users or Terms can be populated.
{
"$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"
}
}
]
}
}
Available query types use these WordPress functions internally:
Arguments
Custom arguments can be passed using the arguments attribute:
{
"blockstudio": {
"attributes": [
{
"id": "posts",
"type": "select",
"label": "Posts",
"populate": {
"type": "query",
"query": "posts",
"arguments": {
"post_type": "jobs",
"numberposts": "20"
}
}
}
]
}
}
Return Format
By default, Blockstudio returns:
| Query | Value | Label |
|---|---|---|
posts |
post object | post_title |
users |
user object | display_name |
terms |
term object | name |
Customize the response with returnFormat:
{
"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 Mode
Enable dynamic searching with the fetch option:
{
"blockstudio": {
"attributes": [
{
"id": "posts",
"type": "select",
"label": "Posts",
"populate": {
"type": "query",
"query": "posts",
"fetch": true,
"arguments": {
"post_type": "posts",
"numberposts": "20"
}
}
}
]
}
}
This enables stylisedUi and fetches the first 20 posts initially. Typing in the select field searches posts using the s argument.
Function
Use a custom function to populate options:
{
"blockstudio": {
"attributes": [
{
"id": "postTypes",
"type": "checkbox",
"label": "Post types",
"populate": {
"type": "function",
"function": "get_post_types"
}
}
]
}
}
Arguments
Pass arguments as an array (uses call_user_func_array internally):
{
"blockstudio": {
"attributes": [
{
"id": "postTypes",
"type": "checkbox",
"label": "Post types",
"populate": {
"type": "function",
"function": "get_post_types",
"arguments": [[], "objects"]
}
}
]
}
}
Return Format
{
"blockstudio": {
"attributes": [
{
"id": "postTypes",
"type": "checkbox",
"label": "Post types",
"populate": {
"type": "function",
"function": "get_post_types",
"arguments": [[], "objects"],
"returnFormat": {
"value": "name",
"label": "label"
}
}
}
]
}
}
Mixing Options
Combine static options with populated data:
{
"blockstudio": {
"attributes": [
{
"id": "users",
"type": "radio",
"label": "Users",
"options": [
{
"value": "administrators",
"label": "Administrators"
},
{
"value": "editors",
"label": "Editors"
}
],
"populate": {
"type": "query",
"query": "users",
"position": "before"
}
}
]
}
}
The position option (before or after) controls where populated options appear relative to static options.
Warning
Mixing options and populate data is not supported when using fetch mode.
Custom Data
Create reusable datasets with the blockstudio/blocks/attributes/populate filter. The filter receives a single argument, an array of all custom datasets keyed by name. Add your dataset under a key and return the array:
add_filter('blockstudio/blocks/attributes/populate', function($options) {
$options['customData'] = [
['value' => '1', 'label' => 'Option 1'],
['value' => '2', 'label' => 'Option 2'],
];
return $options;
});
Then reference the key in your block:
{
"blockstudio": {
"attributes": [
{
"id": "posts",
"type": "select",
"label": "Posts",
"populate": {
"type": "custom",
"custom": "customData"
}
}
]
}
}
External Data
Fetch data from an external source:
{
"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"
}
}
}
]
}
}
The search term is appended to urlSearch.
Dynamic Arguments
Populate arguments can reference other block attributes using {attributes.*}
syntax. When the referenced attribute changes, the field re-fetches its options
automatically.
{
"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
}
}
}
]
}
}
This works with all populate types (query, function, custom). Any value
in the populate configuration containing {attributes.*} is resolved
client-side with the current attribute value before the query runs.
References use the editor’s stored values. For a select option, use
{attributes.post_type.value} for its value or
{attributes.post_type.label} for its label; returnFormat controls the
template value, not this stored editor shape.
Nested arguments are resolved without serializing them into a template string.
An argument consisting of one placeholder keeps its referenced type, including
numbers, booleans, arrays, and objects. A placeholder embedded in other text
produces a string. Missing references are left unchanged, and quoted or
multiline values are sent intact.
Function callbacks keep their positional argument lists. The editor adds
WordPress search arguments only to query populates, not to function calls.
Rendering Dependent Selections
Dependent options are not loaded when the block is registered, because each block instance can have different arguments. Rendering uses the saved selection instead of discarding it against an empty option list. The populate callback is not executed again on the frontend.
The field’s returnFormat still applies:
returnFormat |
Single select | Multiple select |
|---|---|---|
value (default) |
The saved value, for example "a" |
An array of saved values, for example ["a", "b"] |
label |
The saved label | An array of saved labels |
both |
The saved {value, label} option |
An array of saved options |
For query-populated selections, values still resolve to the corresponding
WordPress post, user, or term object unless populate.returnFormat.value is
"id". Labels come from the saved selection. If an imported selection has no
label, its value is used as the label. A matching static option declared in
options takes precedence over the saved option, so its current label applies.
Empty selections remain false (or the field’s configured fallback). This
does not change validation of ordinary static options: a saved value that is no
longer in a static option list still returns false.
Dynamic selects also preserve default and fallback selections while their
options are deferred. Use a scalar value, a {value, label} option, or an array
of either for a multiple select. A scalar uses its value as the label unless it
matches a declared static option. An option object preserves its supplied label;
a matching static option takes precedence. No populate callback runs on the
server to look up these defaults.