wsf_submit_validate

Contents

Description

The wsf_submit_validate filter hook is used to validate a form submission.

Usage

add_filter( 'wsf_submit_validate', 'my_hook_function', 10, 3 );

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. $post_mode String
    The post mode. Values are: submit, save and action.
  3. $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

You can show a message on the form and also redirect a user in the event of an error.

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:

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

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

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

    // Perform your validation here
    $validation = false;

    // Add an error message to the form
    if( false === $validation ) {

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

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

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

Source File

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