Celebrate WordCamp Asia 2024 with 30% OFF! Use coupon WC30 - Terms

Javascript Events

WS Form fires a number of different events during the lifecycle of a form. You can use these to run your own javascript when the event fires.

All WS Form events are passed the following parameters:

  • event – Event object
  • form_object – The form object (Form configuration).
  • form_id – The form ID.
  • instance_id – The instance ID of the form on the page. This is an integer that begins with 1. To learn more about instances, click here.
  • form_el – The form element jQuery object
  • form_canvas_el – The form canvas element jQuery object

When using the WS Form WooCommerce extension, form_el will refer to the WooCommerce product form and form_canvas_el will refer to the form injected by WS Form.

Example of using the WS Form JavaScript are:

$(document).on('wsf-submit-before-ajax', function(event, form_object, form_id, instance_id, form_el, form_canvas_el) {

  // Debug
  console.log('Event type: ' + event.type + ' fired.');
  console.log('Form ID: ' + form_id);
  console.log('Instance ID: ' + instance_id);

  // Get FormData object from form element
  var form_data = new FormData(form_el[0]);
});

… where wsf-submit-before-ajax is the event type. In this example, the wsf-submit-before-ajax event fires immediately before we push the form data to our server side API.

Another example showing how to handle a lock event on the form. The form is locked when the form submit button is clicked to help prevent double clicks.

$(document).on('wsf-lock', function(event, form_object, form_id, instance_id) {

  alert('Form ID ' + form_id + ' was locked!');
});

Events

The JavaScript events fired by WS Form at a document level are chronologically listed below:

Name Description Trigger
Rendered This fires when a form has finished rendering. wsf-rendered
Tab Clicked This fires when a tab is clicked or is moved to using conditional logic. wsf-tab-clicked
Submit Before This fires prior to the form being submitted (when submit button is clicked). wsf-submit-before
Save Before This fires prior to the form being saved (when save button is clicked). wsf-save-before
Validation Before This fires prior to the form being validated. wsf-validate-before
Validation After This fires when form validation has finished. wsf-validate-after
Validation Success This fires when validation was successful. wsf-validate-success
Validation Fail This fires when validation failed. wsf-validate-fail
Submit This fires when the form data is about to be processed for submission. wsf-submit
Save This fires when the form data is about to be processed for saving. wsf-save
Lock This fires when the form is locked, just prior to the data being posted on a submit or save. wsf-lock
Submit Ajax Before This fires just before the form data is submitted to the WS Form server side API after the Submit button is clicked. wsf-submit-before-ajax
Save Ajax Before This fires just before the form data is submitted to the WS Form server side API after the Save button is clicked. wsf-save-before-ajax
Complete This fires when the form submit or save is completed. wsf-complete
Submit Complete This fires when the form submit is completed. wsf-submit-complete
Save Complete This fires when the form save is completed. wsf-save-complete
Success This fires when the form submit or save is successful. wsf-success
Submit Success This fires when the form submit is successful. wsf-submit-success
Save Success This fires when the form save is successful. wsf-save-success
Error This fires when the form submit or save encounters an error. wsf-error
Submit Error This fires when the form submit encounters an error. wsf-submit-error
Save Error This fires when the form save encounters an error. wsf-save-error
Actions Start This fires when the form actions start to run on the client side. wsf-actions-start
Actions Finish This fires when the form actions finish on the client side. wsf-actions-finish
Unlock This fires when the form is unlocked. wsf-unlock
Reset Before This fires when a form reset starts (when reset button is clicked). wsf-reset-before
Reset Complete This fires when a form reset completes. wsf-reset-complete
Clear Before This fires when a form clear starts (when clear button is clicked). wsf-clear-before
Clear Complete This fires when a form clear completes. wsf-clear-complete