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

            {
      "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, index.blade.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.

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

Twig

Twig is a flexible, fast, and secure template engine for PHP. It allows developers to write concise and readable code in templates, enhancing productivity and maintainability. Twig supports a variety of features designed to make templating both powerful and straightforward, making it ideal for projects that require robust, reusable templates.

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:

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

      
Copy

Custom icon

Custom SVGs icons for blocks can be registered like so:

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

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

      
Copy

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

            // 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:

            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:

            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.