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:
window.enOnSubmit = function(){
// client code
...
return false; // return false to prevent submit
}
Example using promises to prevent submit
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
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
// $.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’
window.enOnError = function(){
alert('Validation failed')
}