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
$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.$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
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.
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:
|
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
// 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