Creating blocks

Composing your own blocks with BS is extremely easy. The plugin will look for a blockstudio folder within your currently activated theme. Inside of it, every .php and .twig file will create a new block by making use of the file header information. Let's take a look at one of the blocks that is being used on the landing page:

<?php // cta.php /* Title: Call to Action Description: Call to action element. Category: blockstudio Icon: lightbulb Mode: preview SupportsAlign: false SupportsMode: false */

The above is equivalent of this code:

add_action( 'acf/init', 'register_cta_block' ); function register_cta_block() { if( function_exists( 'acf_register_block_type' ) ) { register_cta_block(array( 'name' => 'cta', 'title' => __('Call to Action'), 'description' => __('Call to action element.'), 'category' => 'blockstudio', 'icon' => 'lightbulb', 'mode' => 'preview', 'supports' => array( 'align' => false, 'mode' => false, ), )); } }

While both of these examples will register a block, nothing is being rendered yet. Instead of relying on callbacks or templates, markup in BS is being defined in the same file like so:

<?php // cta.php /* Title: Call to Action Description: Call to action element. Category: blockstudio Icon: lightbulb Mode: preview SupportsMode: false SupportsAlign: false */ ?> <p>Buy my product!</p>

And that's it, we made our first block! Every filename can only contain lowercase alphanumeric characters and dashes, and must begin with a letter.

If you need to access other block features, which can't be set using file headers, it is also possible to register blocks and settings via PHP using the $register variable:

<?php $register = array( 'title' => 'First Block', 'title' => __( 'First Block' ), 'category' => 'formatting', 'icon' => 'design', ); ?> <p>My Markup</p>

Alternatively, it is possible to add settings via PHP while maintaining settings set with the file header using the $settings variable:

<?php // cta.php /* Title: Call to Action Description: Call to action element. Category: blockstudio Icon: lightbulb Mode: preview SupportsMode: false SupportsAlign: false */ $settings = array( 'text-align' => 'left' ); ?> <p>Buy my product!</p>

File headers

Below is a full list of possible settings that can be set in the file header.

<?php /* Title: Testimonial Description: Content block for customer testimonials. Category: marketing Icon: smiley IconBackground: #000000 IconForeground: #ffffff Keywords: testimonial customer content (space-seperated) Mode: preview Context: side Align: full PostTypes: page post (space-seperated) Parent: acf/my-block SupportsAlign: false or left right full (space-seperated) SupportsAlignText: true|false SupportsAlignContent: true|false or matrix SupportsAnchor: true|false SupportsCustomClassName: true|false SupportsJSX: true|false SupportsMode: true|false SupportsMultiple: true|false SupportsReusable: true|false */ ?>

Gotchas

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.

Subfolders

Since BS is built on ACF or MB, every block will automatically be registered under the acf or mb namespace. In our example above, the block name would have been acf/cta.

It is also possible to create blocks using folders within the Blockstudio folder. To avoid duplicate block names and errors, every block within a subfolder will be prefixed with the folders name. For example, a file called testimonial.php inside a marketing subfolder will have acf/marketing-testimonial as it's block name.

Unlimited nested folders are supported.

Defining fields

Of course, the real usefulness of blocks come from connecting custom fields to them. This way, blocks can be infinitely reused with different settings or texts.

While defining fields via the ACF or MB interface is completely fine, BS includes a handy way to register fields in the block files like so:

<?php // cta.php /* Title: Call to Action Description: Call to action element. Category: design Icon: lightbulb Mode: preview SupportsAlign: false SupportsMode: false */ $fields = array( array( 'key' => 'cta_title_key', 'label' => 'Title', 'name' => 'cta_title', 'type' => 'text', ), array( 'key' => 'cta_text_key', 'label' => 'Text', 'name' => 'cta_text', 'type' => 'textarea', ), ); ?> <h1><?php echo get_field( 'cta_title' ) ?: 'Title'; ?></h1> <p><?php echo get_field( 'cta_text' ) ?: 'Text'; ?></p>

Blockstudio is automatically going to look for a $fields variable inside your files and if available, will register those and connect them to the block. All of the settings that ACF offers when registering fields via PHP are available here.

Previews

Previews make it possible to show the block in the inserter panel on hover. This feature behaves similar to the field registration and has to be defined in an $example variable inside your block file. Below is an example (using ACF) of the heading block used on the landing page.

<?php /* Title: Heading Description: Simple heading. Category: blockstudio Icon: editor-paragraph Mode: preview SupportsAlign: false SupportsMode: false */ $fields = array( array( 'key' => 'heading_heading_key', 'label' => 'Heading', 'name' => 'heading_heading', 'type' => 'text', ), array( 'key' => 'heading_text_key', 'label' => 'Text', 'name' => 'heading_text', 'type' => 'text', ), ); $example = array( 'attributes' => array( 'mode' => 'preview', 'data' => array( 'heading_heading' => "Title", 'heading_text' => "Text" ) ) ); $heading = get_field( 'heading_heading' ); $text = get_field( 'heading_text' ); ?> <div class="<?php echo $block['blockstudio_center']; ?>"> <?php if ( $heading ): ?> <h1 class="<?php echo $block['blockstudio_text_2xl']; ?>"> <?php echo $heading; ?> </h1> <?php endif; ?> <?php if ( $text ): ?> <p class="<?php echo $block['blockstudio_text_md']; ?> bsx-text-gray-600 2xl:bsx-max-w-none inter"> <?php echo $text; ?> </p> <?php endif; ?> </div>

Metabox

Since version 1.3.0, BS supports Metabox (MB) blocks with the same known syntax. Since MB blocks are registed using the rwmb_meta_boxes filter, following snippet has to be added to the functions.php of your currently active theme:

add_filter( 'rwmb_meta_boxes', function ( $meta_boxes ) { return Blockstudio\Build::init( get_template_directory() . '/my-mb-blocks', 'my-prefix', 'mb' ); } );

All of the features above (excluding filters for custom paths and prefixes) are also available here.

All of the features above (excluding filters for custom paths and prefixes) are also available here.

Twig

Since version 1.4.0, BS also supports Twig templates. Please note that Timber is needed for templates written with Twig.

Register

Same as PHP, all block registration data is being taken from the file header.

{# Title: My Block Description: Some description Category: content #} <p>My Markup</p>

Fields and previews

Similar to PHP, custom fields and examples can be defined in their respectively named variable. Let's create the CTA example from before with Twig:

{# Title: Call to Action Description: Call to action element. Category: blockstudio Icon: lightbulb Mode: preview #} {% set fields = [ { "key" : "cta_title_key", "label": "Title", "name" : "cta_title", "type" : "text" }, { "key" : "cta_subtitle_key", "label": "Subtitle", "name" : "cta_subtitle", "type" : "text" } ] %} {# acf #} {% set example = { "attributes": { "mode" : "preview", "data": { "cta_title_key": "This is the title", "cta_subtitle_key": "This is the subtitle" } } } %} {# mb #} {% set example = { "cta_title": "This is the title", "cta_subtitle": "This is the subtitle" } %} <h1>{{ field.cta_title }} </h1> <h2>{{ field.cta_subtitle }} </h2>

Parameters

All PHP parameters are also available in your Twig templates:

{# Title: Call to Action Description: Call to action element. Category: blockstudio Icon: lightbulb #} The available aligns are {{ block.align }} {% if is_preview %} Only show this in the block editor. {% endif %} The current post id is: {{ post_id }}

Scripts and styles

Blockstudio will automatically enqueue a style.css and script.js file (if those exist) for all blocks in the same folder.

/* my-block/style.css */ .my-h1 { color: blue !important; } // my-block/script.js setTimeout(function () { document.querySelector(".my-h1").style.color = 'green'; }, 5000);

It is possible to change the name of those files using the appropriate filter .