https://github.com/micropackage/block-loader
Automatic WordPress Gutenberg block loader based on template files
https://github.com/micropackage/block-loader
acf bracketspace composer-library gutenberg meta-box micropackage
Last synced: about 1 year ago
JSON representation
Automatic WordPress Gutenberg block loader based on template files
- Host: GitHub
- URL: https://github.com/micropackage/block-loader
- Owner: micropackage
- License: gpl-3.0
- Created: 2020-01-27T18:51:00.000Z (over 6 years ago)
- Default Branch: develop
- Last Pushed: 2022-03-19T19:25:05.000Z (about 4 years ago)
- Last Synced: 2024-10-29T06:06:53.855Z (over 1 year ago)
- Topics: acf, bracketspace, composer-library, gutenberg, meta-box, micropackage
- Language: PHP
- Homepage:
- Size: 61.5 KB
- Stars: 24
- Watchers: 4
- Forks: 5
- Open Issues: 3
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
README
# Block Loader
[](https://bracketspace.com)
[](https://packagist.org/packages/micropackage/block-loader)
[](https://packagist.org/packages/micropackage/block-loader)
[](https://packagist.org/packages/micropackage/block-loader)
[](https://packagist.org/packages/micropackage/block-loader)
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:
```php
acf_register_block_type( [
'name' => 'sample-block',
'title' => __('Sample Block'),
'render_template' => 'blocks/sample-block.php',
] );
```
You can do initialize the loader once:
```php
Micropackage\BlockLoader\BlockLoader::init( [
'dir' => 'blocks',
] );
```
And define the block config directly in the template (`blocks/sample-block.php`):
```
'blocks',
'categories' => [],
'wrap' => '
%1$s', // 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:
1. Create block template file in the `blocks` folder
2. Define custom fields for your block using ACF or Meta Box.
Block template file needs to have a comment header containing block parameters.
```
'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.
| Parameter | Type | Description |
| -------------------------- | ----------------- | ------------------------------------------------------------ |
| **dir** | (*string*) | This is a directory within your theme where block templates are located. Relative path.
**Default:** `'blocks'` |
| **categories** | (*array*) | Array of custom block categories passed directly to [`block_categories_all`](https://developer.wordpress.org/reference/hooks/block_categories_all/) filter.
If only one category will be configured, it will be used as default category for all custom blocks.
**Default:** `[]` (empty array) |
| **wrap** | (*false\|string*) | Wrapper to each block. If set to false, the block content will be just the template file content.
Works only for ACF due to the differences in block rendering mechanisms.
**Default:** `'
%1$s'` |
| `...$block_creator_params` | - | Additional parameters passed to [ACF Block Creator](https://github.com/micropackage/acf-block-creator/) |
### Categories definition
This is how to define the categories array.
```php
...
'categories' => [
[
'slug' => 'custom-cat',
'title' => __( 'Custom Category', 'textdomain' ),
'icon' => 'book-alt',
],
...
],
...
```
### Wrap template
Parameters used in internal `sprintf`:
1. block content from template file, which should be wrapped
2. block classes string
3. unique block id
Example: `'
%1$s'`
## 📦 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](https://bracketspace.com).
## 📖 Changelog
[See the changelog file](./CHANGELOG.md).
## 📃 License
GNU General Public License (GPL) v3.0. See the [LICENSE](./LICENSE) file for more information.
## © Credits
The Loader engine is based on the [palmiak](https://github.com/palmiak)'s [Timber ACF WP Blocks](https://github.com/palmiak/timber-acf-wp-blocks).