Attributes - Populating options

Last modified: April 17 2024.

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 and checkbox field types. More will be supported in the future.

Data can be populated in three different ways:

Query return results from a post, user or term query
Function return results from a custom function
Custom return results from a custom dataset
Fetch return results from an external source

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.

block.json


            {
      "$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:

posts: get_posts
users: get_users
terms: get_terms

Arguments

Custom arguments can be passed using the arguments attribute.

block.json


            {
      "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.

block.json


            {
      "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.

block.json


            {
      "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.

block.json


            {
      "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.

block.json


            {
      "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.

block.json


            {
      "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.

block.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" // 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.

functions.php


            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.

block.json


            {
      "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.

block.json


            {
      "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