Get Started

Attributes - Populating options

Last modified:

Instead of supplying different field types like Posts, Users and 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.

Setup

At this stage, 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",
      "apiVersion": 2,
      "name": "blockstudio/native",
      "title": "Native Block",
      "category": "text",
      "icon": "star-filled",
      "description": "Native Blockstudio block.",
      "keywords": [
        "block",
        "native"
      ],
      "version": "1.0.0",
      "textdomain": "blockstudio",
      "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.

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

Mixing

It is possible to combine options and the data from queries.

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

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 () {
      return [
        "customData" => [
          [
            "value" => "custom-1",
            "label" => "Custom 1",
          ],
          [
            "value" => "custom-2",
            "label" => "Custom 2",
          ],
          [
            "value" => "custom-3",
            "label" => "Custom 3",
            ],
          ],
        ];
      ]);
    });

        
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