logo

Registration

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 that contain a block.json file with a blockstudio key will be registered.

block.json

block.json 
            {
      "name": "blockstudio/native",
      "title": "Native Block",
      "category": "text",
      "icon": "star-filled",
      "description": "Native Blockstudio block.",
      "blockstudio": true
    }
  
                    

                Copy

Template

So far, the custom block is not going to be registered since it is missing a template. To fix that just create an index.php 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

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
HTML icon

Custom paths

By default, Blockstudio will recursively look through the blockstudio folder inside your current theme or child theme 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('init', function () {
      Blockstudio\Build::init([
        'dir' => get_template_directory() . '/client-blocks'
      ]);
    });
  
                    

                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.