Docxpresso offers developers a series of specific “events” that may be used to further customize the end users Docxpresso interfaces.
This series of custom events include:
- customOnLoad
- customOnFullyLoaded
- customOnListLoaded
- customOnValidate
- customOnPreclone
- customOnClone
- customOnPreremove
- customOnRemove
- confirmOnSubmit
- customOnSubmit
- customOnUnload
We pass now to briefly explain how to use and the particular goal of each of this events.
customOnLoad ()
If we define a customOnLoad function in our custom JavaScript all the corresponding JS code will be run as soon as the page is loaded.
For example the following code:
function customOnLoad () {alert('hello user');}Will launch a JS alert with the ‘hello user’ text as soon as the page is loaded.
This method does not need to return anything and if it does it will be ignored by Docxpresso.
customOnFullyLoaded ()
It works as customOnLoad but the JavaScript code is run after all default Docxpresso JavaScript code has been already run.
customOnListLoaded (name)
The loading of lists is an asynchronous process because the list options are obtained via an AJAX call.
In order to facilitate the triggering of any event on the loading of a list one may define a customOnListLoaded function that depends on the name of the associated list and it is launched upon success of the corresponding AJAX call.
customOnValidate (val, name)
If the customOnvalidate function is defined Docxpresso will call it automatically each time a variable field is validated passing the current value (parameter val) and name (parameter name) of the variable to be validated.
The method should return a boolean value* that reflects if the corresponding variable has been successfully validated or not.
* If we pass the integer 0 instead of false we will enforce that Docxpresso does not check any other internal validation like date format or the like.
customOnPreclone (type, id)
If we define a customOnPreclone function in our custom JavaScript all the corresponding JS code will be run before the cloning of a block is carried out.
Docxpresso passes to the function the type of block to be clone, i.e. row, list or block (bookmarked content) and the id of the block to be cloned.
COMMENT: the id parameter corresponds to the data-id attribute value for the first parent element of the block that we wish to clone.
For example, in the case of this table row:
One may also generate this token programmatically by generating the md5 hash of all the variables contained in the block element, i.e. if the table row contains two variables like product and Price.
The data-id can be generated by:
data-id = md5('product,Price');The method should return a boolean value that if false will block the cloning of that element.
The type and associated id can also be recovered from the template processing interface:
customOnClone ()
If we define a customOnClone function in our custom JavaScript all the corresponding JS code will be run after the cloning of a block.
Docxpresso passes to the function the type of block to be clone, i.e. row, list or block (bookmarked content) and the id of the cloned block (see the comments about the id above).
This method does not need to return anything and if it does it will be ignored by Docxpresso.
customOnPreremove (type, id)
If we define a customOnPreremove function in our custom JavaScript all the corresponding JS code will be run before removing a block.
Docxpresso passes to the function the type of block to be clone, i.e. row, list or block (bookmarked content) and the id of the block to be removed (see the comments about the id above).
The method should return a boolean value that if false will block the removal of that element.
customOnRemove (type, id)
If we define a customOnRemove function in our custom JavaScript all the corresponding JS code will be run after removing a block.
Docxpresso passes to the function the type of block to be clone, i.e. row, list or block (bookmarked content) and the id of the block to be removed (see the comments about the id above).
This method does not need to return anything and if it does it will be ignored by Docxpresso.
confirmOnSubmit ()
If we define a confirmOnSubmit function in our custom JavaScript we can launch an explicit confirmation by the user that he wants to submit the data to the Docxpresso server.
This event would be most commonly used with the launchConfirmSend helper because the submission will only be activated after the “confirm submit” button of the integrated confirm modal is clicked, but of course this click may be triggered programmatically.
The method should return void because the confirmation should be usually activated by an user action.
customOnSubmit ()
If we define a customOnSubmit function in our custom JavaScript all the corresponding JS code will be run before submitting the data to Docxpresso.
The method should return a boolean value that if false will block the data submission.
customOnUnload ()
If we define a customOnUnload function in our custom JavaScript all the corresponding JS code will be run before unloading the page.
The method should return a boolean value that if false will block prompt the user to stay in the page and do whatever action requested (see the section on Docxpresso helpers to learn how to launch a Docxpresso warning or popup).
