suredonation_register_additional_blocks Filter Hook

Overview

The suredonation_register_additional_blocks filter allows developers to register additional SureDonation blocks from their own plugins or extensions.

You can use this filter to provide custom block source directories and the PHP namespace used by the block classes. SureDonation then discovers the block files from the provided directories and registers them alongside its core blocks.

This is useful when building custom SureDonation extensions that need to add their own blocks to the block-registration process.

When to Use This Filter

Use this filter when you need to:

• Register custom SureDonation blocks.
• Add blocks from another plugin or extension.
• Register multiple groups of custom blocks.
• Keep custom block classes in a separate namespace.
• Extend the SureDonation block editor without modifying core plugin files.

Filter Signature

apply_filters(

    'suredonation_register_additional_blocks',

    []

);

apply_filters(

    'suredonation_register_additional_blocks',

    []

);

Parameters

Each block group descriptor should contain the following keys:

For example:

[

    'dir'       => MY_PLUGIN_DIR . 'blocks/**/*.php',

    'namespace' => 'MyPlugin\\Blocks',

]

[

    'dir'       => MY_PLUGIN_DIR . 'blocks/**/*.php',

    'namespace' => 'MyPlugin\\Blocks',

]

Entries that do not contain both dir and namespace are skipped.

Return Value

Return an array containing one or more block group descriptors.

The filtered value is merged into the block registration process only when it is a non-empty array.

Basic Usage

Use add_filter() to register your callback.

add_filter(

    'suredonation_register_additional_blocks',

    'your_custom_function',

    10,

    1

);

function your_custom_function( $additional_blocks ) {

    // Add block group descriptors here.

    return $additional_blocks;

}

add_filter(

    'suredonation_register_additional_blocks',

    'your_custom_function',

    10,

    1

);

function your_custom_function( $additional_blocks ) {

    // Add block group descriptors here.

    return $additional_blocks;

}

Example: Register Custom Blocks

The following example registers custom blocks located in the inc/blocks directory of a plugin.

add_filter(

    'suredonation_register_additional_blocks',

    'mysite_register_blocks',

    10,

    1

);

function mysite_register_blocks( $additional_blocks ) {

    $additional_blocks[] = [

        'dir'       => MY_PLUGIN_DIR . 'inc/blocks/**/*.php',

        'namespace' => 'MyPlugin\\Inc\\Blocks',

    ];

    return $additional_blocks;

}

add_filter(

    'suredonation_register_additional_blocks',

    'mysite_register_blocks',

    10,

    1

);

function mysite_register_blocks( $additional_blocks ) {

    $additional_blocks[] = [

        'dir'       => MY_PLUGIN_DIR . 'inc/blocks/**/*.php',

        'namespace' => 'MyPlugin\\Inc\\Blocks',

    ];

    return $additional_blocks;

}

How the Example Works

1. The filter receives the existing list of additional block groups.
2. A new block group descriptor is added.
3. The dir value points to the PHP files containing the custom blocks.
4. The namespace value identifies the namespace used by the block classes.
5. The modified array is returned.
6. SureDonation discovers and registers the block files.

Example: Register Multiple Block Groups

You can register multiple directories containing different groups of blocks.

add_filter( 'suredonation_register_additional_blocks', 'mysite_register_multiple_blocks', 10, 1);

function mysite_register_multiple_blocks( $additional_blocks ) {

    $additional_blocks[] = [
        'dir'       => MY_PLUGIN_DIR . 'blocks/donation/**/*.php',
        'namespace' => 'MyPlugin\\Blocks\\Donation',
    ];

    $additional_blocks[] = [
        'dir'       => MY_PLUGIN_DIR . 'blocks/custom/**/*.php',
        'namespace' => 'MyPlugin\\Blocks\\Custom',

    ];

    return $additional_blocks;

}

add_filter( 'suredonation_register_additional_blocks', 'mysite_register_multiple_blocks', 10, 1);

function mysite_register_multiple_blocks( $additional_blocks ) {

    $additional_blocks[] = [
        'dir'       => MY_PLUGIN_DIR . 'blocks/donation/**/*.php',
        'namespace' => 'MyPlugin\\Blocks\\Donation',
    ];

    $additional_blocks[] = [
        'dir'       => MY_PLUGIN_DIR . 'blocks/custom/**/*.php',
        'namespace' => 'MyPlugin\\Blocks\\Custom',

    ];

    return $additional_blocks;

}

Block Registration Flow

The filter is part of the SureDonation block registration process:

1. SureDonation starts the block registration process.
2. The suredonation_register_additional_blocks filter is applied.
3. Custom block group descriptors are added to the registration list.
4. SureDonation validates the required dir and namespace values.
5. The configured directories are globbed to find PHP block files.
6. The discovered block classes are registered alongside the core SureDonation blocks.

Related Hooks

• suredonation_allowed_form_blocks: Controls the blocks that are allowed for SureDonation forms.