JavaScript page hooks for page submit, validations and errors

This article is suitable for developers

For complete flexibility, we allow clients and developers to add any custom code to pages that they wish. To help with this, we provide JavaScript “page hooks” as a way to integrate this custom code.

When a form is submitted, we use event.preventDefault() to stop the submit. We also run the validation (and other processes) asynchronously, using promises. After that, if everything is validated, then the page is submitted.

There are three page hooks that help standardize ‘event interception’ and to help custom scripts to follow a more formal methodology.

The page hooks are enOnValidate, enOnSubmit and enOnError.

These three functions have been placed in global scope (i.e on the window object) and when present, our page JavaScript will call them during the submission process.

None	None
enOnValidate	Called during validation – any validation fails will prevent the page submitting. A function that can return true to allow processing to continue, return false to prevent processing, or return a Promise that will only allow the processing to continue once the Promise is resolved.
enOnSubmit	Called when validation has successfully completed and the page is about to be submitted. A function that can return true to allow processing to continue, return false to prevent processing, or return a Promise that will only allow the processing to continue once the Promise is resolved.
enOnError	Called when the client side validation fails. The return value is ignored.

For enOnValidate and enOnSubmit, both callbacks work the same – they are a function that can return true to allow processing to continue, return false to prevent processing, or return a Promise that will only allow the processing to continue once the Promise is resolved.

Avoid defining the same hook multiple times, as only the most recently defined will be run.

enOnSubmit examples

Basic example to prevent submit:

CODE

window.enOnSubmit = function(){
  // client code
  ...
  return false; // return false to prevent submit
}

Example using promises to prevent submit

CODE

window.enOnSubmit = function(){
  // handle async code with promises
  return new Promise(function(resolve, reject){
    setTimeout(function(){
      resolve() // will allow submit when timeout runs in 1000ms
    }, 1000)
  })
}

enOnValidate examples

Example of custom validation

CODE

window.enOnValidate = function(){
  if(!checkCustomValidationFunction()){
    alert('validation failed');
    return false; //validation failed so return false to prevent submission
  }
  return true; // validation was ok so return true
}

Example of AJAX validation

CODE

// $.ajax returns a promise so this will halt page processing if the ajax call fails
window.enOnValidate = function(){
  return $.ajax('/url/to/call') 
}

enOnError examples

enOnError is a hook that is called when the client side validation fails. Like enOnSubmit and enOnValidate, it should be set on the window object so it is in global scope.

The return value is ignored.

Example of ‘on Error’

CODE

window.enOnError = function(){
  alert('Validation failed')
}