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_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.
Messages
Messages can appear before or after the form, and have a variety of designs and options.
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:
|
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:
|
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; }