The ‘Run WordPress Hook’ action runs a WordPress action or filter when a user saves or submits a form. Although simple this action is powerful and allows developers to run any PHP code when a website visitor submits a form.
Adding This Action
To add a ‘Run WordPress Hook’ action:
- When editing your form, click the ‘Actions’ icon at the top of the page. The ‘Actions’ sidebar will open on the right-hand side of the page.
- Click the ‘Add’ icon to add a new action.
- Select ‘Run WordPress Hook’ from the Action pulldown. A series of settings will appear.
As with all sidebars in WS Form, click the ‘Save’ button at the bottom to save your changes, or click ‘Cancel’ to disregard your changes.
The ‘Run WordPress Hooks’ action settings are as follows:
When Should This Action Run?
You can choose to run the WordPress hook when the form is saved, submitted, or both.
Type
Select the type of hook you would like to run:
- Filter (apply_filter)
- Action (do_action)
Hook Tag
Enter the tag name of the filter or action you want to run.
Priority
Choose whether to run the hook before or after other actions.
If you want to manipulate field values before other actions run, select ‘Before’.
If you want to use the data after other actions have run (For example, to obtain a Zendesk ticket ID), select ‘After’.
Writing Hooks
Filter
WS Form PRO will call the filter as follows:
apply_filters($tag_name, $form, $submit);
$form
– This contains the form object.$submit
– This contains the submit object.
Return Values
The return from your PHP filter function will be processed as follows:
Return Type | Processed As |
---|---|
Object: $submit |
$submit object will be replaced and passed to the next action. |
Integer: 0 – 100 | Spam level set 0 = Not spam, 100 = Spam. |
Boolean: false | Action processing halted. |
Array | See below for returning error messages or custom messages. |
Return an Error Message
To return an error message, the return from your PHP filter can be set as follows:
return array( 'error' => array( 'message' => __('My error message') ) );
Return a Custom Message
To return a custom message, the return from your PHP filter can be set as follows:
return array( 'message' => array( 'message' => __('My custom message') ) );
The available parameters for the custom message return type array are as follows:
Name | Description | Values | Default | Required |
---|---|---|---|---|
message |
Message to display. | – | – | Yes |
type |
Type of message. | success, information, warning, danger, none | success | No |
method |
Position. | before, after | before | No |
form_hide |
Hide form when shown. | true, false | true | No |
clear |
Clear other messages. | true, false | true | No |
duration |
Show duration (ms). | No | ||
scroll_top |
Scroll to top. | instant, smooth (Blank = Do not scroll) | No | |
scroll_top_offset |
Scroll offset (pixels). | 0 | No | |
scroll_top_duration |
Scroll Duration (ms). | 400 | No | |
message_hide |
Hide message after duration. | true, false | false | No |
form_show |
Show form after duration. | true, false | false | No |
The behavior of a custom message is the same as the Show Message action.
A more advanced example of returning a custom message array is shown below:
return array( 'message' => array( 'message' => __('My information message'), 'type' => 'information', 'method' => 'after', 'form_hide' => false, 'clear' => true ) );
Using Conditional Logic to Catch Submit and Save Errors
An example of how to catch a form submission error is shown below. Similar conditions exist for a form save error too. In the example below a previously hidden message field is made visible if a submit error occurs.
Action
WS Form PRO will call the action as follows:
do_action($tag_name, $form, $submit);
- $form – This contains the form data.
- $submit – This contains the submit data.
Sample Code
Retrieve Field Data
The following code is an example of how to retrieve submitted field data from a form:
// Add action to process form data add_action('wsf_action_tag', 'wsf_action_function', 10, 2); // My function for action function wsf_action_function($form, $submit) { // Get submit value (Change '123' to your field ID) $submit_value = wsf_submit_get_value($submit, 'field_123'); // Do something with $submit_value here // ... }