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( [ (
'name' => 'cta',
'title' => __('Call to Action'),
'description' => __('Call to action element.'),
'category' => 'blockstudio',
'icon' => 'lightbulb',
'mode' => 'preview',
'supports' => [ (
'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 = [
'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 = [
'text-align' => 'left'
];
?>
<p>Buy my product!</p>
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.
<?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-separated)
SupportsAlignText: true|false
SupportsAlignContent: true|false or matrix
SupportsAlignWide: true|false
SupportsAnchor: true|false
SupportsColor: true|false
SupportsColorBackground: true|false
SupportsColorDuotone: true|false
SupportsColorGradients: true|false
SupportsColorLink: true|false
SupportsColorText: true|false
SupportsCustomClassName: true|false
SupportsFullHeight: true|false
SupportsHTML: true|false
SupportsInserter: true|false
SupportsJSX: true|false
SupportsLock: true|false
SupportsMode: true|false
SupportsMultiple: true|false
SupportsReusable: true|false
SupportsSpacingBlockGap: true|false or horizontal vertical (space-separated)
SupportsSpacingMargin: true|false or top right bottom left (space-separated)
SupportsSpacingPadding: true|false or top right bottom left (space-separated)
SupportsTypographyFontSize: true|false
SupportsTypographyLineHeight: true|false
*/
?>
Blocks have to be associated with a category for them to appear in the editor.
If no category is set, blocks will automatically be assigned to the
blockstudio
category which is registered by the plugin.
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 = [
[
'key' => 'cta_title_key',
'label' => 'Title',
'name' => 'cta_title',
'type' => 'text',
],
[
'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 = [
[
'key' => 'heading_heading_key',
'label' => 'Heading',
'name' => 'heading_heading',
'type' => 'text',
],
[
'key' => 'heading_text_key',
'label' => 'Text',
'name' => 'heading_text',
'type' => 'text',
],
);
$example = [
'attributes' => [
'mode' => 'preview',
'data' => [
'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>
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 ) {
$blockstudio = Blockstudio\Build::init( get_template_directory() . '/my-mb-blocks', 'my-prefix', 'mb' );
return array_merge( $meta_boxes, $blockstudio );
} );
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 }}
Assets
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
.
Inline
Since 2.1.0, assets can also be rendered inline by appending
-inline
to the file name.
Please note that this feature currently doesn't work for blocks used in the site editor template parts. As of now, only blocks
that are present in the
post_content or rendered via the
blockstudio_render_block function.
/* my-block/style-inline.css */
.my-inline-class {
color: red;
}
<style>
.my-inline-class {
color: red;
}
</style>
Inline styles and scripts have the big advantage that they are directly
rendered as style or script tags inside the page. This can enhance loading
times, since it saves extra requests that would have to be made otherwise.
Some things to consider:
- .js files are inlined into the wp_footer()
- .css files are inlined into the wp_head()
- each file is only being inlined once
Please note that it is possible to use inline assets and non-inlined assets
side by side. For example, you could have a
style.css, style-inline.css, script.js
and script-inline.js in a folder and Blockstudio would
enqueue or inline all files appropriately.
