Celebrate WordCamp Asia! - 30% OFF with coupon WC30 at checkout - Terms

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.

Server-Side Validation - Field Invalid Feedback

Messages

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

Server-Side Validation - Message

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

Array Element Description
$field_error_action_array[] = false;
Show  the standard invalid feedback message on the field.

Type: Boolean false

$field_error_action_array[] = 'My custom invalid feedback message';
Show your own custom invalid feedback message on the field.

Type: String

$field_error_action_array[] = array(
    'action' => 'field_invalid_feedback',
    'message' => 'My custom invalid feedback message'
);
Show your own custom invalid feedback message on the field (Alternative method).

Type: Array

Messages

Array Element Description
$field_error_action_array[] = array(
    'action' => 'message'
);
Show an error message containing the standard invalid feedback text for that field.

Type: Array

$field_error_action_array[] = array(
    'action' => 'message',
    'message' => 'My custom message'
);
Show an error message with your own custom message.

Type: Array

$field_error_action_array[] = array(
    'action' => 'message',
    'message' => 'My custom message',
    'type' => 'information'
);
Show an error message with your own custom message with type information.

See the ‘Customizing Message’ section below for additional message configuration keys.

Type: Array

Redirect

Array Element Description
$field_error_action_array[] = array(
    'action' => 'redirect',
    'url' => '/redirect-here/' 
);
Redirect to the specified URL.

Type: Array

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.

Array Parameter Description
message The message to show.
type The type of message to show. Supported values are:

  • success
  • information
  • warning
  • danger
  • none
method Whether to show the message before or after the form. Supported values are:

  • before
  • after
clear Whether to clear other messages before the message is shown (Only applies to the first message shown). Supported values are:

  • on
  • off
scroll_top Whether to scroll to the top of the page when the message is shown. Supported values are:

  • instant
  • smooth
  • off
scroll_top_offset Scroll top offset in pixels (integer). Useful if you have a floating top navigation.
scroll_top_duration If smooth scrolling is selected, this value specifies how long in milliseconds the scroll should take.
form_hide Whether to hide the form when the message is shown. Supported values are:

  • on
  • off
duration How long the form should be shown for. Supported values are:

  • [blank] – Indefinite
  • [integer] – Time in milliseconds

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

This hook can be found in: <plugin root>/includes/core/class-ws-form-submit.php