WP Manifestindependent plugin directory
manifest / editor / gt-acf-blocks

GT ACF Blocks

GT ACF Blocks simplifies the process of creating custom Gutenberg blocks for WordPress by leveraging the power of Advanced Custom Fields. This plugin allows developers to quickly build rich, customizable blocks with clean, organized code and without having to write complex JavaScript.

by Gaurav Tiwari · github.com/wpgaurav/gt-acf-blocks · website

★ 0stars
0forks

Install

No release zip yet. The repository archive installs, but the folder name will carry the branch suffix and updates will not flow:

wp plugin install https://github.com/wpgaurav/gt-acf-blocks/archive/refs/heads/main.zip
Readme github.com/wpgaurav/gt-acf-blocks ↗

A WordPress plugin that provides a framework for easily creating custom Gutenberg blocks using Advanced Custom Fields (ACF).

Description

GT ACF Blocks simplifies the process of creating custom Gutenberg blocks for WordPress by leveraging the power of Advanced Custom Fields. This plugin allows developers to quickly build rich, customizable blocks with clean, organized code and without having to write complex JavaScript.

Features

  • Simple framework for registering custom Gutenberg blocks
  • Seamless integration with Advanced Custom Fields
  • Block templates with automatic field rendering
  • Block categories for organization
  • Block preview support
  • CSS and JS enqueuing for individual blocks
  • Developer-friendly API

Requirements

  • WordPress 5.8+
  • PHP 7.4+
  • Advanced Custom Fields PRO 5.8+

Installation

  1. Upload the gt-acf-blocks folder to the /wp-content/plugins/ directory
  2. Activate the plugin through the 'Plugins' menu in WordPress
  3. Ensure Advanced Custom Fields PRO is installed and activated

Usage

Creating a New Block

  1. Create a new folder for your block in the blocks directory
  2. Add your block's PHP, CSS, and JS files
  3. Register your block using the plugin's API

Basic Block Structure

blocks/
└── example-block/
    ├── block.json       # Block configuration
    ├── block.php        # Block template
    ├── block.css        # Block styles (optional)
    ├── block.js         # Block scripts (optional)
    └── fields.php       # ACF field definitions

Registering a Block

Add your block registration to your theme's functions.php or a custom plugin:

add_action('acf/init', 'register_my_blocks');

function register_my_blocks() {
    if (function_exists('gt_acf_blocks_register_block')) {
        gt_acf_blocks_register_block([
            'name'        => 'example-block',
            'title'       => 'Example Block',
            'description' => 'An example custom block',
            'category'    => 'formatting',
            'keywords'    => ['example', 'demo'],
        ]);
    }
}

Adding a New Block

Follow these steps to create and register a new custom block:

  1. Create the block directory structure:

    cd /path/to/your/wordpress/wp-content/plugins/gt-acf-blocks/blocks
mkdir my-custom-block

  2. Create the necessary files:

    • block.json - Block configuration
    • block.php - Block template
    • fields.php - ACF field definitions
    • block.css (optional) - Block styles
    • block.js (optional) - Block scripts

  3. Configure your block.json:

    {
  "name": "my-custom-block",
  "title": "My Custom Block",
  "description": "A description of what my block does",
  "category": "formatting",
  "icon": "star-filled",
  "keywords": ["custom", "example"],
  "acf": {
    "mode": "preview",
    "renderTemplate": "block.php"
  },
  "supports": {
    "align": true,
    "mode": false,
    "jsx": false
  }
}

  4. Define your ACF fields in fields.php:

    <?php
if (function_exists('acf_add_local_field_group')) {
    acf_add_local_field_group([
        'key' => 'group_my_custom_block',
        'title' => 'My Custom Block',
        'fields' => [
            [
                'key' => 'field_my_custom_field',
                'label' => 'Custom Field',
                'name' => 'custom_field',
                'type' => 'text',
            ],
        ],
        'location' => [
            [
                [
                    'param' => 'block',
                    'operator' => '==',
                    'value' => 'acf/my-custom-block',
                ],
            ],
        ],
    ]);
}

  5. Create your block template in block.php:

    <?php
/**
 * Block Template
 */

// Get field values
$custom_field = get_field('custom_field');
?>

<div id="<?php echo esc_attr($block['id']); ?>" class="my-custom-block">
    <?php if ($custom_field): ?>
        <div class="custom-content">
            <?php echo esc_html($custom_field); ?>
        </div>
    <?php endif; ?>
</div>

  6. Register your block in your theme's functions.php or a custom plugin:

    add_action('acf/init', 'register_my_blocks');

function register_my_blocks() {
    if (function_exists('gt_acf_blocks_register_block')) {
        gt_acf_blocks_register_block([
            'name' => 'my-custom-block',
        ]);
    }
}

  7. Add CSS (optional) in block.css:

    .my-custom-block {
    padding: 20px;
    background-color: #f8f8f8;
}

.my-custom-block .custom-content {
    font-size: 18px;
    color: #333;
}

  8. Add JavaScript (optional) in block.js:

    (function($) {
    $(document).ready(function() {
        $('.my-custom-block').on('click', function() {
            // Your custom JavaScript here
        });
    });
})(jQuery);

  9. Test your block by adding it to a page or post in the WordPress editor.

Configuration

Each block can be configured through its block.json file with the following options:

  • name: Internal block name (required)
  • title: Display title in the editor (required)
  • description: Block description
  • category: Block category
  • icon: Dashicon or SVG to represent the block
  • keywords: Search terms to help users discover the block
  • supports: Block support options
  • example: Preview example configuration

Development

Field Definitions

Define your ACF fields in the block's fields.php file:

<?php
if (function_exists('acf_add_local_field_group')) {
    acf_add_local_field_group([
        'key' => 'group_example_block',
        'title' => 'Example Block',
        'fields' => [
            [
                'key' => 'field_example_title',
                'label' => 'Title',
                'name' => 'title',
                'type' => 'text',
            ],
            // Add more fields as needed
        ],
        'location' => [
            [
                [
                    'param' => 'block',
                    'operator' => '==',
                    'value' => 'acf/example-block',
                ],
            ],
        ],
    ]);
}

Block Template

Create your block's front-end display in the block.php file:

<?php
/**
 * Block Template
 * 
 * @param array $block The block settings and attributes
 * @param string $content The block content
 * @param bool $is_preview Whether this is a preview in the editor
 */

// Get field values
$title = get_field('title');
?>

<div id="<?php echo esc_attr($block['id']); ?>" class="example-block">
    <?php if ($title): ?>
        <h2><?php echo esc_html($title); ?></h2>
    <?php endif; ?>
</div>

Support

For support, feature requests, or bug reports, please submit an issue via the GitHub repository or send me a message.

Each block you build with GT ACF Blocks lives in its own folder with a block.json, a PHP template and its ACF fields, so you get custom Gutenberg blocks without writing complex JavaScript. The framework is free and open source under GPL v2 or later.

If GT ACF Blocks let you build a custom Gutenberg block while staying in PHP and ACF, you can buy me a coffee.

Buy me a coffee

Leaving a star helps too, and if a block won't register, an issue with your WordPress, PHP and ACF PRO versions plus its block.json and fields.php makes the problem much easier to track down.

License

This plugin is licensed under the GPL v2 or later.

Built with ♥ by Gaurav Tiwari