Custom Server-Side Form ValidationPRO

WS Form allows you to perform your own server-side validation of submitted fields values using the wsf_submit_field_validate WordPress filter.

A basic example of how this filter can be used is shown below:

// Add filter for wsf_submit_field_validate using hook my_validation_function
add_filter( 'wsf_submit_field_validate', 'my_validation_function', 10, 6 );

// My validation function
function my_validation_function( $field_error_action_array, $field_id, $field_value, $section_repeatable_index, $post_mode, $submit_object ) {

    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;
}

The Filter

The wsf_submit_field_validate filter passes the following 6 arguments to the hook function. You can use any of these arguments to assess the validity of a field.

Argument Description
$field_error_action_array An array of actions that are passed back to form to execute. This will typically include field_invalid_feedback and/or message actions (See below).

Always ensure you return $field_error_action_array to WS Form.
$field_id The field ID being validated
$field_value The submitted value. Note that for some fields (e.g. Select, checkbox and file upload) the value may contain an array.
$section_repeatable_index If the field is contained within a repeatable section, this argument represents the row index (starts with 1).
$post_mode The post mode. Values are: submit, save and action.
$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.

Error Types

There are two main types of error you can show on a form if a field does not validate; Field Invalid Feedback and Messages.

These errors are added to the form by pushing elements to the $field_error_action_array array (See below).

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

Redirects

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

Redirects

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

Advanced Example

A more advanced example showing  more examples of how WS Form server-side validation can be used is shown below.

// Add filter for wsf_submit_field_validate using hook my_validation_function
add_filter( 'wsf_submit_field_validate', 'my_validation_function', 10, 6 );

// My validation function
function my_validation_function( $field_error_action_array, $field_id, $field_value, $section_repeatable_index, $post_mode, $submit_object ) {

    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;
}