Display Datasource Error Messages
By default, if a problem occurs when downloading data from a remote datasource or updating a database with input data from the form, no error message will be displayed at runtime. This
Two default user-configurable error messages are available which will be used where you don't specify a specific message. One is specified at the form level and is used for data download and update actions initiated within Events and the other is used by the Submit Button. The default form-level message is also used for all data downloaded when the form loads.
Alternatively, you can specify your own error messages using custom JavaScript and assign them to individual data download, data update or submit actions.
In either case, you will need to enable the display of data error messages before the error messages will be displayed. This is done by selecting the Display Error Messages property within the form properties. If this property is not selected, the error messages will not be displayed.
The text of the default form-level error message can also be edited under the form properties, using the Default Error Message property. Edit this property to enter your chosen text for these default error messages.
The text for the Submit Button's default error message is specified under the properties for the button itself, using its Error Message Text property under the properties' Advanced tab.
If an error occurs at runtime and data error messages are enabled, your error message will be displayed in a pop-up message box, which the user will need to acknowledge in order to dismiss it and return to the form. If you have Client logging enabled, the error message pop-up will also display the HTTP error code(s) and message(s) returned to the form as a result of the error(s).
When you select the Display Error Messages property for the first time within a form, Form Studio will add a style called Datasource_Error_HeaderStyle to the Styles gallery. This style is used to format the header of the error message pop-up and can be modified in the same way as any other style, if you want to change the appearance of the error message.
Developers with JavaScript experience can extend the default error handling described above using JavaScript to customise the error messages displayed and, if required, to extend the behaviour of the form when encountering errors.
A default error handler function is provided which will be called when errors occur during data download and updates and is responsible for specifying and displaying an error message in these situations. An error handler is a section of code which deals with, or handles, error conditions should they arise.
The default error handler function is called onDatasourceError and is a JavaScript function which works with calls to the intrinsic functions loadDatasource and updateDatasource and will automatically be called if the original call results in an HTTP error, providing the display of data error messages has been enabled in the form's properties (see above). This function is automatically generated by Form Studio and added to the form's custom JavaScript file the first time you enable the display of data error messages within a form. The name of this function will also be entered in the form properties' Default Error Handler property, specifying it as the default error handler function.
If you don't specify an error handler function in calls to loadDatasource or updateDatasource, the default error handler, onDatasourceError, will be used.
You can edit this function if you want to extend the default behaviour, e.g. to provide more sophisticated error messaging based on the HTTP response(s) received or to perform specific actions in the event of an error occurring. You can also use the default function as a guide to create your own error handling functions, which you can use instead of the default function if you prefer and/or to provide individual error handling for calls to loadDatasource and updateDatasource.
You can edit onDatasourceError and add your own error handling functions by editing the custom JavaScript file in the usual way - see below for more details. If you want to provide your own default error handler function, you will need to edit the Default Error Handler property under the form properties and replace onDatasourceError with the name of your custom function.
- Changes you make to the default error message in the form properties' Default Error Message property, will automatically update the onDatasourceError function.
If you look at the onDatasourceError function in the Script file, you will see that the function takes a parameter responses. If an HTTP error response is received from a call to loadDatasource or updateDatasource, the response is stored in an array and then the script waits for two seconds in case further HTTP responses are received, e.g. where you have a number of calls to loadDatasource and or updateDatasource close together. If another response comes in, that response is added to the array and the timer reset for another two seconds and so on. When no response has been received for two seconds, the error handler function will be called passing in the responses object. You can extract the responses contained in this object, e.g. as shown in the comments at the beginning of the function, allowing you to display appropriate messages based on the actual response codes received.
You can change the error message displayed by the function by editing the line: ndlParams.errorMessageText = ... and substituting the default error message with a message of your choice.
You can also add a Reload Form button to the error message displayed, allowing the user to reload the form and start again. To do this find the line: ndlParams.showReloadButton = false; and change false to true. Clicking this button at runtime is equivalent to refreshing the page or pressing F5 within the browser.
Note that you shouldn't change the final if statement. If you change the name of the form, this statement will automatically be updated here with the new name.
If you want to create a new error handler function, to use with a specific instance of loadDatasource or updateDatasource, you can do so from the Event Builder or by manually editing the custom JavaScript.
The Event Builder pop-up allows you to assign actions to Elements, e.g. to download a Datasource when a button is clicked. If you assign a LoadDatasource or UpdateDatasource action to an Element, the pop-up will allow you to specify the error handler function to be used for this action.
If you already have an error handler function which is suitable for this action, you can select it from the list in the Error Handler Function field within the Event Builder. If you want to use the default error handler function, onDatasourceError, for an action, you can either select this function in the Error Handler Function field or leave the field blank.
If you want to create a new error handler function for this action, click on the New button to the right of the Error Handler Function field. The custom JavaScript file will load and a new error handler function will be added to the bottom of the file. This function will be a copy of the default function with its own unique name: onError_<action>_<datasource>_<n>, where <n> is a sequential series of numbers added to the end of the name to distinguish this function from other functions which would otherwise have the same name. You can then edit the function as required. The name of the function will automatically be added to the Error Handler Function field for you. Note that this function will contain the default error message as specified in the form properties' Default Error Message property, but subsequent changes to this property won't be reflected in the function and you will need to make any changes to the error message for this function in the custom JavaScript.
- When you click on the New button, if the Display Error Messages property in the form properties is not currently selected, it will be selected automatically and, if the default onDatasourceError function hasn't previously been generated, the function will be generated and added to the custom JavaScript file before opening the script file.
If, in the Event Builder pop-up, you convert a LoadDatasource or UpdateDatasource action to custom JavaScript, a function will be added for the loadDatasource or updateDatasource action, as appropriate, and the error handler function you specified in the Event Handler Function option will automatically be assigned to the action within the JavaScript.
Alternatively, if you want to call loadDatasource and/or updateDatasource within your own custom JavaScript function and you want to create an error handler function to use with the datasource action, you can copy an existing error handler function, give it a unique name, edit it as required and assign it to the loadDatasource or updateDatasource function using the function's ndlParams.errorHandler property - see loadDatasource or updateDatasource for a description of how to use these functions in a custom script. Note that if you create your own error handler function, the error message won't be affected by changes you make to the Default Error Message property in the form properties and must be edited directly in the custom JavaScript file.
How ever you create the error handler function, you must retain the default lines of code in order for the function to work. You can edit the error message and the value of the ndlParams.showReloadButton and you can add additional code lines to the function but you must leave the remaining code lines as they are.
The Submit Button and submitForm intrinsic function include similar error handling to that available for loadDatasource and updateDatasource calls.
The Submit Button includes a built-in error handler which will display a configurable error message in the event of a Datasource error. This error handling cannot be edited but you can specify the error message in the Error Message Text property on the Advanced tab within the Submit button's properties. More advanced developers can provide customised error messaging by manually creating a JavaScript error handler function and then specifying this function in the Error Function property under the Advanced tab of the Submit button's properties. This function will be used in place of the built-in error handling and the error message specified in the Error Message Text property. The format of the function must be the same as that used by the submitForm function(see below). If you specify a Failure Page in the Submit Button's properties, this page will still be displayed.
If you are customising your form using JavaScript, you can use the submitForm intrinsic function to submit the form from within your JavaScript. For example, you could write your own JavaScript function which performs some custom data validation before the form is submitted and then, if there are no issues, calls submitForm to submit the form. You could then assign this function to a standard Button's Clicked Event instead of using a Submit Button Element.
submitForm allows you to specify an error handler function which can be used to display an error message and perform other actions, if required, should any Datasource errors occur when submitting the form. An error handler is a section of code which deals with, or handles, error conditions should they arise.
A default error handler function is provided called onSubmitFormError. This JavaScript function is automatically generated by Form Studio and added to the form's custom JavaScript file (see below). The function will be called automatically if an error occurs when submitting the form using submitForm, providing the display of data error messages has been enabled in the form's properties (see above). If you don't specify an error handler function in calls to submitForm, the default error handler, onSubmitFormError, will be used.
You can edit this function if you want to extend the default behaviour, e.g. to provide more targeted error messaging or to perform specific actions in the event of an error occurring. You can also use the default function as a guide to create your own error handling function, which you can use instead of the default function if you prefer.
You can edit onSubmitFormError and add your own error handling functions by editing the custom JavaScript file in the usual way. If you want to provide your own default error handler function, you will need to write the function and then assign it to the submitForm call - see below for more details.
If you look at the onSubmitFormError function in the Script file, you will see that the function takes a parameter responses. If an HTTP error response is received from a call to submitForm, the response is stored in an array and then the script waits for two seconds in case further HTTP responses are received. If another response comes in, that response is added to the array and the timer reset for another two seconds and so on. When no response has been received for two seconds, the error handler function will be called passing in the responses object. You can extract the responses contained in this object, e.g. as shown in the comments at the beginning of the function, allowing you to display appropriate messages based on the actual response codes received.
You can change the error message displayed by the function by editing the line: ndlParams.errorMessageText = ... and substituting the default error message with a message of your choice.
You can also add a Reload Form button to the error message displayed, allowing the user to reload the form and start again. To do this find the line: ndlParams.showReloadButton = false; and change 'false' to 'true'. Clicking this button at runtime is equivalent to refreshing the page or pressing F5 within the browser.
Note that you shouldn't change the final if statement. If you change the name of the form, this statement will automatically be updated here with the new name.
If you want to create a new error handler function, to use with submitForm, you can do so from the Event Builder or by manually editing the custom JavaScript.
The Event Builder pop-up allows you to assign actions to Elements, such as downloading a Datasource, saving and restoring a form or submiting the form when a button is clicked or a text box is changed. If you assign a Submit form action to an Element, the pop-up will allow you to specify the error handler function to be used for this action.
If you already have an error handler function which is suitable for this action, you can select it from the list in the Error Handler Function field within the Event Builder. If you want to use the default error handler function, onSubmitFormError, for an action, you can either select this function in the Error Handler Function field or leave the field blank.
If you want to create a new error handler function for this action, click on the New button to the right of the Error Handler Function field. The custom JavaScript file will load and a new error handler function will be added to the bottom of the file. This function will be a copy of the default function called: onErrorSubmitForm_<n>, where <n> is a sequential series of numbers added to the end of the name to distinguish this function from other onErrorSubmit functions. You can then edit the function as required. The name of the function will automatically be added to the Error Handler Function field for you.
- When you click on the New button, if the Display Error Messages property in the form properties is not currently selected, it will be selected automatically and, if the default onSubmitError function hasn't previously been generated, the function will be generated and added to the custom JavaScript file before opening the script file.
If, in the Event Builder pop-up, you convert a Submit form action to custom JavaScript, a function will be added for the submit form action and the error handler function you specified in the Event Handler Function option will automatically be assigned to the action within the JavaScript.
Alternatively, if you want to call submitForm within your own custom JavaScript function and you want to create an error handler function to use with the datasource action, you can copy an existing error handler function, give it a unique name, edit it as required and assign it to the submitForm function using the function's ndlParams.errorHandler property - see submitForm for a description of how to use this function in a custom script.
For both the Submit button and the submitForm function, the error handler function works in the same way as it does with the loadDatasource and updateDatasource functions (see above) and the Datasource_Error_HeaderStyle style can be used to format the error message.
- Both the Submit button and submitForm function will only display Datasource error messages or use a specified error handling function if data error messages are enabled. Error messages are enabled by selecting the Display Error Messages property in the form properties. If error messages are disabled, and the submission fails, no message will be displayed and the submission will fail silently.
See also: