Registration

Last modified: March 14 2023.

Composing your own blocks with Blockstudio is extremely easy. The plugin will look for a blockstudio folder within your currently activated theme. Inside it, all subfolders which contain a block.json file with a blockstudio key will be registered.

block.json


                {
      "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",
      "blockstudio": true
    }

        Copy

Conditional logic

Blocks can be registered conditionally using the conditions key. It supports all the global variables which are also available for attributes.

See all conditions

The following example will only register the block if the current post type is a page:

block.json


                {
      "blockstudio": {
        "conditions": [
          [
            {
              "type": "postType",
              "operator": "==",
              "value": "page"
            }
          ]
        ],
      }
    }

        Copy

Custom icon

Custom SVGs icons for blocks can be registered like so:

block.json


                {
      "blockstudio": {
        "icon": "<svg></svg>"
      }
    }

        Copy

WordPress doesn't allow for custom SVG icons inside its own block.json icon key, only Dashicons IDs are allowed here.

HTML

Blockstudio is using a React element parser to render the icon element, so it is possible to use HTML inside the icon string.

block.json


                {
      "blockstudio": {
        "icon": "<div>:-)</div>"
      }
    }

        Copy

Template

So far the custom block is not rendering any output. To fix that just create an index.php or index.twig in the same folder as your block.json file and its contents will automatically be rendered when your block is used.

index.php


                <h1>My first native block.</h1>Copy

Custom paths

By default, Blockstudio will recursively look through the blockstudio folder for blocks. You can change that behaviour in two ways.

Filter

functions.php


                // Custom path within your theme.
    add_filter('blockstudio/path', function () {
        return get_template_directory() . '/blocks';
    });

    // Custom path within a plugin.
    add_filter('blockstudio/path', function () {
        return plugins_url() . '/my-custom-plugin/blocks';
    });

        Copy

Instances

If the above options are not enough, it is possible to initiate the Blockstudio\Build class on various folders of your choice:

functions.php


                add_action('acf/init', function () {
      // Blockstudio\Build::init($args);
      Blockstudio\Build::init([
        'dir'    => get_template_directory() . 'client-blocks',
        'type'   => 'native'
      ]);
    });

        Copy

Filter metadata

Metadata can be filtered before the block is being registered using the blockstudio/block/meta filter:

functions.php


                add_filter('blockstudio/blocks/meta', function ($block) {
      if (strpos($block->name, 'marketing') === 0) {
        $block->blockstudio['icon'] = '<svg></svg>';
      }

      return $block;
    });

        Copy

The example above is being used internally to give all Blockstudio library elements the same icon.