suredonation_default_validation_messages Filter Hook

Overview

The suredonation_default_validation_messages filter allows developers to customize the default validation messages used by SureDonation’s form fields.

You can use this filter to:

• Add validation messages for custom field types.
• Override existing default messages.
• Provide translatable messages for custom validation rules.
• Make custom validation errors available in the Form Validation settings.

Admin-configured validation messages take precedence over the defaults provided through this filter.

When to Use This Filter

Use this filter when you are developing a custom SureDonation field or validation rule and need to provide a user-friendly error message.

For example, if a custom field requires a specific code format, you can register a message such as:

Please enter a valid code.

Filter Signature

apply_filters( 'suredonation_default_validation_messages', $messages );

apply_filters( 'suredonation_default_validation_messages', $messages );

Parameters

The array follows this structure:

[

'message_key' => 'Validation message',

]

[

'message_key' => 'Validation message',

]

Some built-in message keys include:

• suredonation_dropdown_invalid_option
• suredonation_input_max_length
• suredonation_email_max_length
• suredonation_input_min_value
• suredonation_input_max_value

Messages can contain %s placeholders. These values are replaced when the message is displayed.

Return Value

Return the complete validation message array.

return $messages;

The returned array should contain:

• A unique message key.
• A translated message string.

Basic Usage

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

function your_custom_function( $messages ) {

// Add or modify validation messages here.

return $messages;

}

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

function your_custom_function( $messages ) {

// Add or modify validation messages here.

return $messages;

}

Example: Add a Custom Validation Message

The following example adds a validation message for a custom field.

add_filter( 'suredonation_default_validation_messages', 'mysite_add_message', 10, 1 );

function mysite_add_message( $messages ) {

$messages['mysite_custom_invalid'] = __(

'Please enter a valid code.',

'my-plugin'

);

return $messages;

}

add_filter( 'suredonation_default_validation_messages', 'mysite_add_message', 10, 1 );

function mysite_add_message( $messages ) {

$messages['mysite_custom_invalid'] = __(

'Please enter a valid code.',

'my-plugin'

);

return $messages;

}

The custom validation code can then use the registered message key:

return __( 'Please enter a valid code.', 'my-plugin' );

return __( 'Please enter a valid code.', 'my-plugin' );

Example: Override an Existing Message

You can also replace one of SureDonation’s default messages.

add_filter( 'suredonation_default_validation_messages', 'mysite_change_email_message', 10, 1 );

function mysite_change_email_message( $messages ) {

$messages['suredonation_email_max_length'] =

'Your email address is too long. Please enter a shorter email address.';

return $messages;

}

add_filter( 'suredonation_default_validation_messages', 'mysite_change_email_message', 10, 1 );

function mysite_change_email_message( $messages ) {

$messages['suredonation_email_max_length'] =

'Your email address is too long. Please enter a shorter email address.';

return $messages;

}

Using Placeholders

Some validation messages contain %s placeholders for dynamic values.

For example:

$messages['mysite_code_length'] = 'The code must contain at least %s characters.';

$messages['mysite_code_length'] = 'The code must contain at least %s characters.';

When the validation message is displayed, SureDonation can substitute the %s placeholder with the applicable value.

Validation Message Flow

The filter is applied when SureDonation builds its default validation messages:

Default validation messages

          ↓

suredonation_default_validation_messages

          ↓

Custom messages added or modified

          ↓

Admin validation-message overrides applied

          ↓

Message displayed when validation fails

Admin Overrides

Messages added through this filter provide the default values.

If an administrator has configured a custom validation message through the SureDonation settings, the admin-stored value takes precedence.

The stored overrides use the validation_messages option key.

Therefore, changing a default message through this filter does not necessarily replace an existing administrator-defined message.

Related Hooks

• suredonation_validate_field: Filters validation errors for individual form fields and can be used to implement custom validation rules.
• suredonation_email_field_char_limits: Controls the character limits used when validating Email fields.