The Blocklab plugin helps you as a developer build websites a lot faster by allowing you to easily create new building blocks for your websites. Currently it’s build to generate ACF blocks with ease, but native support is planned to be added in the future. Find everything you need to know in this Blocklab documentation.
Getting started
As the plugin has not been publicly released yet, if you’re getting started with the plugin you must have received the zip-file to the closed beta release for live testing. Getting started will be super easy: just upload the zip file through adding it as a new plugin, wait for it to install and activate it. This will add the Blocklab link under the ‘Tools’ (Gereedschappen) section of the admin menu. Please note that the Advanced Custom Fields plugin is required to use the Blocklab plugin.
Heads-up!
The plugin adds block-files to your theme. The blocks will be automatically moved when switching themes, but this does mean using a default WordPress theme can be problematic. Whenever you would update your theme, it would overwrite any changes you made, including the added blocks. If you are using a version-controlled custom theme, I would advise adding the created blocks to your repository: handle your custom blocks as part of your custom theme.
Local vs Remote
Blocklab should work both locally and in a remote environment like staging or live. Just be aware the plugin will create files upon block creation. When working locally, this works fairly easy, as you would be editing the local files. When working remote, you’ll need to download the created files, edit them and re-upload the files to see the changes. I would advise to use Filezilla for this, as it allows you to create a temporary download you can edit and easily re-upload after saving. This Blocklab documentation covers everything you can do with the blocks regardless of the environment you’re working on.
The boilerplate
When creating a block, it will create new folder inside your theme-folder/template-parts/blocks/ folder. The main template file will be content-blockname.php. You will add all the logic to a block in this render file. Depending on the settings you have used, there can also be a blockname.css stylesheet and a blockname.js script added to the folder. After you have assigned custom fields to a block, the ACF JSON-file will also be stored with the block-files, to make moving blocks a lot easier.
Other parts of the boilerplate are actually loaded in dynamically while registering the blocks. This way the block folders stay clean, while making changes to the functionality of all blocks can be done in one place. The key part of this is the construct file. Inside of your content-blockname.php template you will see a file being included. Before this include, you can still easily add classes by using $classes[] = ‘newclassname’. Inside the construct file, all styles, classes and attributes for the block are generated based on the settings you chose during block creation.
When the boilerplate changes, this Blocklab documentation will be updated.
Block settings
General Settings
Type
The type of block. Currently only ‘ACF’ is available.
Title
The title of the block.
Name
The name will automatically be a slugified version of the block title.
Version
Version of the block.
Description
The description of the block.
Advanced Settings
Enqueue Style
If checked a CSS file will be created in the Block folder, you can then edit this to apply style.
Enqueue Script
If checked a JS file will be created in the Block folder, you can then edit this to apply scripts.
Keywords
Comma seperated keywords to help find this block in the Block Editor.
Category
Select the core category that will be assigned to this block.
Icon
Select a dashicon icon or paste SVG code to use any SVG icon.
Settings Support
Mode
This property allows the user to toggle between edit and preview modes via a button.
Default mode
In Auto Mode the Preview is shown by default but changes to edit form when block is selected. In Preview Mode the Edit form appears in sidebar when block is selected. In Edit Mode Edit form is always shown.
Anchor
This property allows the user to add an anchor property that will be added as the ID of the block’s outer element.
Multiple
This property allows the block to be added multiple times.
JSX
This property allows you to use the <InnerBlocks /> component in your PHP template.
Styling Support
Align
This property enables a toolbar button to control the block’s alignment.
Default Align
Set the default value for this blocks’ Align setting.
Align Text
This property enables a toolbar button to control the block’s text alignment.
Default Text Align
Set the default value for this blocks’ Align Text setting.
Align Content
This property enables a toolbar button to control the block’s inner content alignment.
Default Content Align
Set the default value for this blocks’ Align Content setting.
Background Color
This property enables the background color picker.
Background Gradients
This property enables the background gradient picker.
Link Color
This property enables the link color picker.
Text Color
This property enables the text color picker.
Post Types
All Post Types
Check this when you want to be able to use this block in all post types, or when you want to use it in templates and template parts.
Selected Post Types
When not allowing this block for all post types, select which post types it can be used in with this setting.
Custom Fields
Custom fields created with ACF can be easily assigned to a block by selecting the corresponding conditions for the field-group placement. These custom fields will automatically be available in your block php template. If your custom fields’ name is ‘title’, you can use $title in your php template. If the name is ‘another_title’, the php variable will be $another_title.
Template Parts and Templates
As noted under post type settings, to be able to use custom ACF blocks in templates and template parts, the block needs an empty ‘post types array’. This is possible by selected to allow the block to be used for all post types.
At the time of writing this, ACF blocks do not yet support to be only allowed for template parts and templates yet. To be able to use them at all, it needs to be allowed everywhere. If you are reading this and you have seen an update from ACF about this that I didn’t mention yet, please let me know. As soon as ACF supports it, I will add this functionality.
Are you missing anything in this Blocklab documentation?
This page is a living document. This means that whenever the Blocklab plugin is updated, this documentation will be updated as well. Perhaps you are running into a challenge that is not discussed on this page? Get in touch and let me know!
