Create Custom Gutenberg Blocks Using Voxycure WP Plugin

Last updated on : August 2, 2025

Welcome, developers!

The Voxycure Framework allows theme and plugin authors to easily create dynamic Gutenberg blocks using PHP templates and field groups powered by the framework.

This guide shows you how to register custom blocks using the voxycure_blocks filter and how to structure your template files for frontend rendering.

What is voxycure_blocks?

The voxycure_blocks filter allows you to define a list of custom blocks (with unique IDs, labels, and template file paths) that the framework will recognize, register, and render dynamically within the Gutenberg editor.

💡 These blocks are backed by dynamic fields defined in the Voxycure Framework admin panel.

How to Register Custom Blocks

Here’s an example of how a developer can register blocks from their theme or plugin using this filter:

<?php 

add_filter('voxycure_blocks', function ($blocks) {
    
    // Get the absolute path to the theme's template parts directory for blocks.
    $template_dir = get_stylesheet_directory() . '/template-parts/blocks/';

    // Define an array of custom blocks to be registered.
    $custom_blocks = [
        [
            'id'       => 'hero-banner', // A unique machine-readable identifier for the block.
            'label'    => 'Hero Banner Block', // A human-readable name for the block, shown in the editor.
            'template' => $template_dir . 'hero-banner.php', // The path to the PHP template file that renders the block's frontend output.
        ],
        [
            'id'       => 'testimonials',
            'label'    => 'Testimonials Section',
            'template' => $template_dir . 'testimonials.php',
        ],
    ];

    return array_merge($blocks, $custom_blocks);
});

Explanation of Each Parameter

id : A unique identifier for the block. (Used as slug and handle)
label : A human-readable name shown in the editor block list.
template : Absolute path to the PHP file that renders the block HTML.

You’ve Successfully Registered Your Block with Voxycure!

Nice work — your custom Gutenberg block is now connected to the Voxycure Framework using the voxycure_blocks hook.

But the real power of Voxycure comes from its field group system, which lets you visually define what kind of content your blocks will use. Here’s how you tie your block to real, editable fields:

Step 1 : Navigate to the Voxycure Admin Page

First, log in to your WordPress dashboard. On the left-hand menu, find and click on the “Voxycure” menu item.

This will take you to the main dashboard for the Voxycure Framework, where all the magic happens.

Step 2 : Create a New Field Group

In the Voxycure dashboard, click “Create New Field Group.” This opens the editor where you’ll define what fields your block will use.

Step 3 : Configure Your Field Group

This is the most important step, where you tell Voxycure Framework what your fields are for and where they should appear.

Group Name: Give your group a meaningful name (e.g., “Hero Banner”).
Group Type: This is important — from the “Group Type” dropdown, choose “Blocks.”

🧠 Tip: You’ll only see the list of blocks here if you’ve already registered them using the voxycure_blocks filter.
Also, make sure your block’s id in the filter matches the group’s ID exactly — that’s how Voxycure links your fields to the right template.

Step 4 : Add Your Custom Fields

Once your group is set, click “Add Field” to start adding content fields.
You can add anything — text, images, buttons, repeaters, sliders — whatever your block needs.

Not sure what each field type does? Check out the full field types documentation here.

Once you’re done, your block will now show up in the block editor with your custom fields, and it will render on the front end using the template file you registered.

You’re now building dynamic, field-powered Gutenberg blocks — without writing any JavaScript. 🙌

How to Build the Template File

Each block template receives an $attributes array which contains the field values defined in the framework UI (ACF-like). You can access and use these values like so:

<?php
$title       = $attributes['title'] ?? '';
$description = $attributes['description'] ?? '';
$button      = $attributes['button'] ?? [];
?>

<section class="custom-block">
    <h2><?php echo esc_html($title); ?></h2>
    <p><?php echo esc_html($description); ?></p>

    <?php if ($button['text'] && $button['url']) : ?>
        <a href="<?php echo esc_url($button['url']); ?>" class="btn">
            <?php echo esc_html($button['text']); ?>
        </a>
    <?php endif; ?>
</section>

🧠 Tip: Use helper functions like esc_html(), esc_url(), and wp_kses_post() to keep the output secure.

How the Framework Uses Your Blocks

The block appears inside the Gutenberg editor.
Its field settings are pulled dynamically from the Voxycure Framework UI.
When rendered on the frontend, the template file is loaded and $attributes are passed automatically.
You don’t need to register JS manually—Voxycure handles it.

Pro Tip: Use Dynamic Fields via Framework

All block data comes from the Group editor inside Voxycure (similar to ACF). Just match the block_id with the id you use in the voxycure_blocks array.

Conclusion

With just a few simple steps, you’ve learned how to register custom Gutenberg blocks using the voxycure_blocks filter and connect them to dynamic field groups through the Voxycure Framework. This flexible system gives developers full control over both the editing experience and front-end output—without needing to write React or JavaScript. Whether you’re building hero banners, testimonials, or complex layouts, Voxycure makes it easy to create powerful, reusable blocks backed by clean PHP templates and field management.

Create Custom Gutenberg Blocks with Voxycure Framework WordPress Plugin