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
$field_error_action_array
ArrayAn array of actions that are passed back to form to execute. This will typically include field_invalid_feedback and/or message actions.$field_id
IntegerThe field ID being validated.$field_value
MixedThe submitted value. Note that for some fields (e.g. Select, checkbox and file upload) the value may contain an array.$section_repeatable_index
IntegerIf the field is contained within a repeatable section, this argument represents the row index (starts with 1).$post_mode
StringThe post mode. Values are: submit, save and action.$submit
Submit ObjectThe 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
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:
|
method | Whether to show the message before or after the form. Supported values are:
|
clear | Whether to clear other messages before the message is shown (Only applies to the first message shown). Supported values are:
|
scroll_top | Whether to scroll to the top of the page when the message is shown. Supported values are:
|
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:
|
duration | How long the form should be shown for. Supported values are:
|
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