Validatable Blocks Filter Hook

Overview

The suredonation_validatable_blocks filter allows developers to control which SureDonation block types are included in server-side field validation.

If your extension adds a custom field block that requires validation, use this filter to add the block name to SureDonation’s list of validatable blocks.

Once added, the submitted value of the custom field can be processed by SureDonation’s field validation system.

When to Use This Filter

Use this filter when your custom SureDonation field block needs server-side validation.

For example, if you create a custom block named:

mysite/custom-field

You can add this block to the validatable block list so SureDonation validates its submitted value.

Default Validatable Blocks

SureDonation includes the following blocks in its default validation list:

• suredonation/input
• suredonation/email
• suredonation/number
• suredonation/dropdown
• suredonation/phone
• suredonation/url

Filter Signature

apply_filters(

    'suredonation_validatable_blocks',

    self::VALIDATABLE_BLOCKS

);

apply_filters(

    'suredonation_validatable_blocks',

    self::VALIDATABLE_BLOCKS

);

Parameters

Return Value

The filter must return an array of block names.

If a non-array value is returned, SureDonation falls back to its built-in default list of validatable blocks.

Basic Usage

Use add_filter() to modify the list of validatable blocks.

add_filter( 'suredonation_validatable_blocks', 'your_custom_function', 10, 1 );

function your_custom_function( $blocks ) {

    // Add or remove validatable block names here.

    return $blocks;

}

add_filter( 'suredonation_validatable_blocks', 'your_custom_function', 10, 1 );

function your_custom_function( $blocks ) {

    // Add or remove validatable block names here.

    return $blocks;

}

Example: Add a Custom Block

The following example adds mysite/custom-field to the list of blocks that SureDonation validates.

add_filter( 'suredonation_validatable_blocks', 'mysite_validate_custom_block', 10, 1 );

function mysite_validate_custom_block( $blocks ) {

    $blocks[] = 'mysite/custom-field';

    return $blocks;

}

add_filter( 'suredonation_validatable_blocks', 'mysite_validate_custom_block', 10, 1 );

function mysite_validate_custom_block( $blocks ) {

    $blocks[] = 'mysite/custom-field';

    return $blocks;

}

After adding the block, SureDonation includes mysite/custom-field in its server-side validation process when the form is submitted.

Example: Add Multiple Custom Blocks

You can add multiple custom blocks using the same filter.

add_filter( 'suredonation_validatable_blocks', 'mysite_add_custom_blocks', 10, 1 );

function mysite_add_custom_blocks( $blocks ) {

    $blocks[] = 'mysite/custom-field';

    $blocks[] = 'mysite/custom-code';

    return $blocks;

}

add_filter( 'suredonation_validatable_blocks', 'mysite_add_custom_blocks', 10, 1 );

function mysite_add_custom_blocks( $blocks ) {

    $blocks[] = 'mysite/custom-field';

    $blocks[] = 'mysite/custom-code';

    return $blocks;

}

Validation Flow

The suredonation_validatable_blocks filter is part of the SureDonation field validation flow.

The typical flow is:

1. A custom field block is created.
2. The block is added to the validatable block list using suredonation_validatable_blocks.
3. The field configuration and validation rules are stored using suredonation_field_block_config.
4. The donor submits the form.
5. SureDonation validates the submitted value.
6. Custom validation rules can be applied using suredonation_validate_field.

Related Hooks

• suredonation_field_block_config
• suredonation_validate_field
• suredonation_default_validation_messages