README

Requires WordPress >=5.8.0.

🧬 About Block Loader

Block Loader loads the Gutenberg Block configuration directly out of the block template file. It parses the file header comment figuring out hwo to register the Block.

Basically instead doing this:

acf_register_block_type( [
	'name'              => 'sample-block',
	'title'             => __('Sample Block'),
	'render_template'   => 'blocks/sample-block.php',
] );

You can do initialize the loader once:

Micropackage\BlockLoader\BlockLoader::init( [
	'dir' => 'blocks',
] );

And define the block config directly in the template (blocks/sample-block.php):

<?php
/**
 * Block Name: Sample Block
 */

...

Supported plugins:

Advanced Custom Fields
Meta Box

This micropackage is compatible with ACF Block Creator which can create the block templates for you while defining the Field group for your new block.

💾 Installation

composer require micropackage/block-loader

🕹 Usage

Before you can start creating blocks you need to initiate the block loader passing optional config array:

Micropackage\BlockLoader\BlockLoader::init( [
	'dir'        => 'blocks',
	'categories' => [],
	'wrap'       => '<div id="%3$s" class="%2$s">%1$s</div>', // ACF only
] );

Blocks are based on the template files located by default in blocks folder in your theme (you can change that).

There are two steps to create a block:

Create block template file in the blocks folder
Define custom fields for your block using ACF or Meta Box.

Block template file needs to have a comment header containing block parameters.

<?php
/**
 * Block Name: (required)
 * Description:
 * Category:
 * Icon:
 * Keywords: (comma-separated)
 * Post Types: 	(comma-separated, ACF only)
 * Mode: (ACF only)
 * Align: (ACF only)
 * Enqueue Style:
 * Enqueue Script:
 * Enqueue Assets:
 * Supports Align: (comma-separated)
 * Supports Anchor: (true|false)
 * Supports Custom Class Name: (true|false)
 * Supports Mode: (true|false, ACF only)
 * Supports Multiple: (true|false)
 * Supports Reusable: (true|false)
 */

ACF

Creating template files is enough for ACF to register blocks. After that you only need to create new fields group and set it's location to your custom block.

Meta Box

In Meta Box you need "MB Blocks" extension to work with blocks. With this plugin custom fields are defined in code. You need to use rwmb_meta_boxes filter to create metabox for your block.

Let's say you have a template called blocks/some-block.php. You need to add the fields definition like this:

add_filter( 'rwmb_meta_boxes', function( $meta_boxes ) {
	$meta_boxes[] = [
		'id'     => 'some-block',
		'type'   => 'block',
		'fields' => [
			// ...fields configuration
		],
	];

	return $meta_boxes;
} );

All block parameters will be fetched from template header comment and merged with your fields configuration.

⚙️ Configuration

All parameters are optional.

Categories definition

This is how to define the categories array.

	...
	'categories' => [
		[
			'slug'  => 'custom-cat',
			'title' => __( 'Custom Category', 'textdomain' ),
			'icon'  => 'book-alt',
		],
		...
	],
	...

Wrap template

Parameters used in internal sprintf:

block content from template file, which should be wrapped
block classes string
unique block id

Example: '<div id="%3$s" class="%2$s">%1$s</div>'

📦 About the Micropackage project

Micropackages - as the name suggests - are micro packages with a tiny bit of reusable code, helpful particularly in WordPress development.

The aim is to have multiple packages which can be put together to create something bigger by defining only the structure.

Micropackages are maintained by BracketSpace.

📖 Changelog

See the changelog file.

📃 License

GNU General Public License (GPL) v3.0. See the LICENSE file for more information.

© Credits

The Loader engine is based on the palmiak's Timber ACF WP Blocks.

micropackage / block-loader

Maintainers

Details