Attributes – Populating options
Last modified:
Instead of supplying different field types like Posts, Users or Terms,
Blockstudio allows for a more modular way of populating data right from the
block.json. This feature currently works for select, radio,checkbox,
color and gradient field types.
Data can be populated in three different ways:
- Query return results from a post, user or term query (only
select,radio,checkbox) - Fetch return results from an external source (only
select,radio,checkbox) - Function return results from a custom function
- Custom return results from a custom dataset
Query
When choosing the query mode, Posts, Users or Terms can be populated. Getting started is easy, simply add the populate attribute to your block.json and define the type that should be queried for your block.
{ "$schema": "https://app.blockstudio.dev/schema", "name": "blockstudio/native", "title": "Native Block", "category": "text", "icon": "star-filled", "description": "Native Blockstudio block.", "supports": { "align": true }, "blockstudio": { "attributes": [ { "id": "posts", "type": "select", "label": "Posts", "populate": { "type": "query", "query": "posts" // or "users" or "terms" } } ] } }Copy
Following functions are used 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" } } } ] } }Copy
Return format
By default, Blockstudio will return following data.
- posts: value: post object, label: post_title
- users: value: user object, label: display_name
- terms: value: term object, label: name
The response can be customised with the returnFormat attribute.
{ "blockstudio": { "attributes": [ { "id": "posts", "type": "select", "label": "Posts", "populate": { "type": "query", "query": "posts", "arguments": { "post_type": "posts", "numberposts": "20", }, "returnFormat": { "value": "id" // only accepts "id" "label": "post_name" // accepts any value found in the respective object } } } ] } }Copy
Fetch
The query population type allows fetching data from the server by using the
fetch option.
{ "blockstudio": { "attributes": [ { "id": "posts", "type": "select", "label": "Posts", "populate": { "type": "query", "query": "posts", "fetch": true, "arguments": { "post_type": "posts", "numberposts": "20", } } } ] } }Copy
Using the settings above, Blockstudio will automatically enable stylisedUi for
the attribute and initially fetch the first 20 posts from the get_posts query.
Upon typing in a value in the select field, the search value will be used as the
s argument in the query, returning posts for the search term.
This will also work for the users and terms query types.
When fetching users, you might have to adjust the search_columns property in
the arguments object to get appropriate results for your query. See the
get_users
documentation for more information.
Function
Instead of relying on the built-in query functions, it is possible to use a custom function to populate options. This can be useful when you want to return data not covered by the built in query types.
{ "blockstudio": { "attributes": [ { "id": "postTypes", "type": "checkbox", "label": "Post types", "populate": { "type": "function", "function": "get_post_types" } } ] } }Copy
Arguments
Similar to the query type, custom arguments can be passed to the function using
the arguments key. Internally, Blockstudio uses
call_user_func_array,
so all arguments have to be passed as an array.
{ "blockstudio": { "attributes": [ { "id": "postTypes", "type": "checkbox", "label": "Post types", "populate": { "type": "function", "function": "get_post_types", "arguments": [[], "objects"] } } ] } }Copy
Return format
Blockstudio will always look for the keys set in the returnFormat object. If
not available, it will look for the value and label key in the returned
data. If those are not available either, it'll fallback to the first value in
the returned array.
{ "blockstudio": { "attributes": [ { "id": "postTypes", "type": "checkbox", "label": "Post types", "populate": { "type": "function", "function": "get_post_types", "arguments": [[], "objects"], "returnFormat": { "value": "name", "label": "label" } } } ] } }Copy
Mixing
It is possible to combine options and the data from queries or functions.
{ "blockstudio": { "attributes": [ { "id": "users", "type": "radio", "label": "Users", "options": { { "value": "administrators", "label": "Administrators", }, { "value": "editors", "label": "Editors", } } "populate": { "type": "query", "query": "users", "position": "before" // this will add the populate options before the static options (defaults to "after") } } ] } }Copy
Mixing options and populate data is not supported when using fetch
Custom data
Instead of relying on one of the built-in ways to populate options with data, it is possible to create custom datasets that can be easily reused within fields.
Adding custom data is done using the blockstudio/blocks/populate filter.
add_filter('blockstudio/blocks/attributes/populate', function ($options) { $options['customData'] = [ [ 'value' => 'custom-1', 'label' => 'Custom 1', ], [ 'value' => 'custom-2', 'label' => 'Custom 2', ], [ 'value' => 'custom-3', 'label' => 'Custom 3', ], ]; return $options; });Copy
Then call the dataset inside the block.json file.
{ "blockstudio": { "attributes": [ { "id": "posts", "type": "select", "label": "Posts", "populate": { "type": "custom", "custom": "customData", } } ] } }Copy
External data
It is possible to fetch data from an external source using the fetch type. The
search will be appended to the searchUrl argument.
{ "name": "blockstudio/fetch", "title": "Fetch", "description": "Fetch field", "blockstudio": { "attributes": [ { "id": "select", "type": "select", "label": "Select", "multiple": true, "populate": { "type": "fetch", "arguments": { "urlSearch": "https://fabrikat.io/streamline/wp-json/wp/v2/posts?search=" }, "returnFormat": { "value": "id", "label": "title.rendered" } } } ] } }Copy