Easily create Gutenberg Blocks with Advanced Custom Fields.

• Minimum Requirements
• Installation
• Usage
• Block definition
  • Block constructors
    • AbstractBlock
    • AbstractBladeBlock
• Controller
• Fields
• Filters
  • acf_gutenblocks/blocks
  • acf_gutenblocks/get_initializables
  • acf_gutenblocks/render_block_frontend_path
  • acf_gutenblocks/render_block_html_output
  • acf_gutenblocks/default_icon
  • acf_gutenblocks/block_settings
• FAQ
  • Can I use a different template rendering option?
  • Do I need to adhere to any structure or standard?
  • Why not load all Blocks from a given directory? It's much easier!
  • My Blade template doesn't load.
• Author Information
• Feedback
• Change log
• License

• PHP >= 7.1
• WordPress (preferrably Bedrock) >= 5.0
• Advanced Custom Fields >= 5.8.0

$ composer require itinerisltd/acf-gutenblocks

1. Activate the plugin
2. Create a directory to store your Blocks in your plugin or theme
3. Define your Block and frontend template

Blocks/
  └── Testimonial/
      ├── views/
      │   └── frontend.php # Block template file
      └── Testimonial.php # Block constructor and controller

4. Register your Block by appending the Block class name as a string to the acf_gutenblocks/blocks filter

add_filter('acf_gutenblocks/blocks', function (array $blocks): array {
    $new_blocks = [
        Testimonial::class,
    ];
    return array_merge($blocks, $new_blocks);
});

Blocks are registered using PHP classes to provide a simple "Controller" to allow separation of logic and functionality from your template. This can really help to isolate and organise code that is intended only for that Block.

To create a Block, you must extend your class from the available Block constructors and pass any valid acf_register_block() arguments to the parent constructor. Here can also define your controller methods for use within your template.

# Blocks/Testimonial/Testimonial.php
<?php

declare(strict_types=1);

namespace App\Blocks\Testimonial;

use Itineris\AcfGutenblocks\AbstractBlock;

class Testimonial extends AbstractBlock
{
    public function __construct()
    {
        parent::__construct([
            'title' => __('Testimonial', 'fabric'),
            'description' => __('Testimonial description', 'fabric'),
            'category' => 'formatting',
            // Other valid acf_register_block() settings
        ]);
    }

    public function getItems(): array
    {
        $items = [];
        foreach (get_field('list_items') as $item) {
            if ($item['enabled']) {
                $items[] = $item['list_item'];
            }
        }
        return $items;
    }
}

Extend from this class to register a vanilla PHP template.

If your project uses the Sage theme, you can take advantage of Blade templating by extending from this class (in future, Sage will be optional).

Your Block constructor class is available to your template via $controller. This allows you to create truly advanced Blocks by organising all of your functional code and logic into a place where you can take more advantage of an OOP approach.

In the Block definition example in this page, we have the getItems method which can be used in the template like so:

# Blocks/Testimonial/views/frontend.php
<?php foreach ($controller->getItems() as $item) : ?>
    <p><?php echo $item['title']; ?></p>
<?php endforeach; ?>

You can define your ACF fields in your Block by returning an array of fields in the registerFields method.

Read more here.

protected function registerFields(): array
{
    return [
        // Any valid field settings
    ];
}

protected function registerFields(): array
{
    $testimonial = new FieldsBuilder('testimonial');

    $testimonial
        ->setLocation('block', '==', 'acf/testimonial');

    $testimonial
        ->addText('quote')
        ->addText('cite')
        ->addRepeater('list_items')
            ->addText('list_item')
            ->addTrueFalse('enabled', [
                'ui' => 1,
                'default_value' => 1,
            ])
        ->endRepeater();

    return $testimonial->build();
}

The Block Loader. Use this to load and register your Block classes.

Called before looping Blocks and checking if they are valid to load.

Used to change the frontend view path.

For use with AbstractBlock. Allows manipulating the frontend view HTML after being included.

Used to change the default icon.

Change the ACF Block settings registered in the Block before initialising it.

You could make a copy of AbstractBlock, rename it and define your own renderBlockCallback method. Just make sure your Block class extends from it.

You can manage your Blocks any way you wish. This README will use our preferred approach of strict typing and the directory structure.

Using directory scanning options like glob and DirectoryIterator (or other Iterators) will have a performance impact within your application. There are many reasons for that, but the most simple ones are that they take arguments that must be read and dealt with before getting to the actual directory scanning.

Manually loading your Blocks also means that you as a developer are more aware of what you are loading and can do things like conditional logic of loading your Blocks.

Check your PHP error logs and that your installation is valid for use with Sage.

acf-gutenblocks is a Itineris Limited project created by Lee Hanbury-Pickett.

Shout out to @nicoprat with his article which kickstarted this.

Thanks to @mmirus for pointers and giving me the idea for this package.

Full list of contributors can be found here.

Please provide feedback! We want to make this library useful in as many projects as possible. Please submit an issue and point out what you do and don't like, or fork the project and make suggestions. No issue is too small.

Please see CHANGELOG for more information on what has changed recently.

acf-gutenblocks is released under the MIT License.