Composing your own blocks with Blockstudio is extremely easy. The plugin will look for a blockstudio folder within your currently activated theme. Inside, every .php and .twig file will create a new block by making use of the file headers or register variable.
Let's imagine the following blocks are registered using Advanced Custom Fields:
The above structure would create 7 different blocks with following block names:
Unlimited nested folders are allowed.
Every filename can only contain lowercase alphanumeric characters, dashes, underscores and must begin with a letter. The acf namespace is automatically being added by ACF. Metabox would use the meta-box namespace instead.
As you can see, naming your file index.php or index.twig will automatically name the block after the parent folder. Please note that this isn't working in the root folder of your block directory.
In the example above only one block (cta) will be registered since the index.php lies in the root folder.
Blockstudio automatically gives your blocks unique names depending on their prefix, file name and how deeply they are nested. Since no files can be named the same in a file system, no two block names will ever be the same.
However, using a combination of an index file inside a folder with the same name as a file in the same directory, there is possibility of two blocks having the same name, in which case the file not inside the folder is being preferred since it will be registered first.
Both blocks have the same name. my-block.php will be registered as a block.
Blockstudio provides two different methods to add metadata to your blocks:
The above is equivalent of this ACF code:
While both of these examples will register a block, nothing is being rendered yet. Instead of relying on callbacks or templates, markup in Blockstudio is being defined in the same file like so:
Below is a full list of possible settings that can be set in the file header.
Please note that some block supports need to be activated in the theme, check the Gutenberg docs for reference.
It is possible to add additional metadata via PHP while maintaining the data set with the file header using the $settings variable.
Alternatively, it is possible to bypass the file headers completely and register blocks via the $register variable:
Since version 1.3.0, BS supports Metabox blocks with the same known syntax. Since blocks are registed using the rwmb_meta_boxes filter, following snippet has to be added to the functions.php of your currently active theme:
The snippet above would register all blocks inside the my-mb-blocks folder of your current theme.
Blockstudio works with Advanced Custom Fields and Metabox, however, not all options are available for both plugins, the list above just shows all possible settings. Refer to the documentation of ACF or MB to find out which options are supported for each plugin.
Icons: SVGs will only work if no IconBackground or IconForeground is set. If one of those settings is present in the file headers, a Dashicons identifier has to be used.