wsf_submit_field_validate

Description

The wsf_submit_field_validate filter hook is used to validate each field when a form is submitted.

Usage

add_filter( 'wsf_submit_field_validate', 'my_hook_function', 10, 6 );

Parameters

1. $field_error_action_array Array
   An array of actions that are passed back to form to execute. This will typically include field_invalid_feedback and/or message actions.
2. $field_id Integer
   The field ID being validated.
3. $field_value Mixed
   The submitted value. Note that for some fields (e.g. Select, checkbox and file upload) the value may contain an array.
4. $section_repeatable_index Integer
   If the field is contained within a repeatable section, this argument represents the row index (starts with 1).
5. $post_mode String
   The post mode. Values are: submit, save and action.
6. $submit Submit Object
   The submit object. Please note that this is a partial submit object because the submit object is still being constructed at the point this filter runs.

Return

The errors are added to the form by pushing elements to the $field_error_action_array array and returning them in your hook function.

Error Types

There are two types of error message you can show on a form if a field does not validate; Field Invalid Feedback and Messages. You can also redirect a user in the event of an error.

Field Invalid Feedback

Field invalid feedback appears underneath the field being validated.

Messages

Messages can appear before or after the form, and have a variety of designs and options.

Redirect

You can redirect the user to a different URL.

Pushing Elements to $field_error_action_array

WS Form supports the display of one or more errors on the form. Each error is stored in the $field_error_action_array array.

WS Form adds its own errors to this array, such as file upload, de-duplication or reCaptacha errors.

Your hook function adds errors to this array if your own validation fails. $field_error_action_array is then returned to WS Form when your function ends.

Example array elements you can push to the $field_error_action_array are shown below:

Field Invalid Feedback

$field_error_action_array[] = false;

$field_error_action_array[] = 'My custom invalid feedback message';

$field_error_action_array[] = array(
    'action' => 'field_invalid_feedback',
    'message' => 'My custom invalid feedback message'
);

Messages

$field_error_action_array[] = array(
    'action' => 'message'
);

$field_error_action_array[] = array(
    'action' => 'message',
    'message' => 'My custom message'
);

$field_error_action_array[] = array(
    'action' => 'message',
    'message' => 'My custom message',
    'type' => 'information'
);

Redirect

$field_error_action_array[] = array(
    'action' => 'redirect',
    'url' => '/redirect-here/' 
);

Customizing Messages

The following optional array keys can be added to $field_error_action_array message elements. If these keys are excluded, WS Form will use the values configured in Form Settings.

Example

Basic

// My validation function
function my_hook_function( $field_error_action_array, $field_id, $field_value, $section_repeatable_index, $post_mode, $submit ) {

    // Only process validation if the form is submitted and not saved
    if ( $post_mode !== 'submit' ) {
        return $field_error_action_array;
    }

    // Process each field
    switch( $field_id ) {

        // Validate field ID 123
        case 123 :

            // Put your own validation statement here
            if ( '' === $field_value ) {

                // Field did not validate, show invalid feedback text on the field
                $field_error_action_array[] = false;
            }

            break;

        // Other field ID validations here ...
    }

    // Return $field_error_action_array to WS Form
    return $field_error_action_array;
}

// Add a callback function for the wsf_submit_field_validate filter hook
add_filter( 'wsf_submit_field_validate', 'my_hook_function', 10, 6 );

Advanced

// My validation function
function my_hook_function( $field_error_action_array, $field_id, $field_value, $section_repeatable_index, $post_mode, $submit ) {

    // Only process validation if the form is submitted and not saved
    if ( $post_mode !== 'submit' ) {
        return $field_error_action_array;
    }

    // Process each field
    switch( $field_id ) {

        // Validate field ID 1
        case 1 :

            // Put your own validation statement here
            if ( '' === $field_value ) {

                // Field did not validate, show standard invalid feedback text the field
                $field_error_action_array[] = false;
            }

            break;

        // Validate field ID 2
        case 2 :

            // Put your own validation statement here
            if ( '' === $field_value ) {

                // Field did not validate, show invalid feedback with a custom message
                $field_error_action_array[] = __( 'My custom message' );
            }

            break;

        // Validate field ID 3
        case 3 :

            // Put your own validation statement here
            if ( '' === $field_value ) {

                // Field did not validate, show a custom message
                $field_error_action_array[] = array(

                    'action'     => 'message',
                    'message'    => __( 'My custom message' ),
                    'type'       => 'information',
                    'clear'      => 'on',
                    'duration'   => 500,
                    'scroll_top' => 'smooth'
                );
            }

        // Validate field ID 4
        case 4 :

            // Put your own validation statement here 
            if(
                ( '' === $field_value ) &&

                // Example showing how to limit validation to the first row in a repeatable section
                ( 1 === $section_repeatable_index )
            ) {

                // Field did not validate, lets do two things...

                // 1. Show a custom message
                $field_error_action_array[] = array(

                    'action'     => 'message',
                    'message'    => __( 'My custom message' ),
                );

                // 2. Show invalid feedback on this field
                $field_error_action_array[] = false;
            }

            break;

        // Other field ID validations here ...
    }

    // Return $field_error_action_array to WS Form
    return $field_error_action_array;
}

// Add a callback function for the wsf_submit_field_validate filter hook
add_filter( 'wsf_submit_field_validate', 'my_hook_function', 10, 6 );

Source File

More Resources

• WordPress Hooks
• WordPress add_filter function