This article describes some of the best practices on how to use and organize the form script in IDM 3.5 workflows.
BP #1: Data Validation
There are a number of places where you can script data validation:
- In the onchange event of the control itself
- Attaching a function to the control's build-in validate function
- Attaching a function to one of the submit actions
Which is the best place? It really depends on the validation that must be done, and whether other fields are involved in the validation.
Data validation in the onchange event
Using the onchange event can be tricky, because it is also fired when the control is loaded. This is done to allow synchronization between this field and others. Triggering the onchange event in each control, once all controls have been loaded, allows for easy synchronization between those controls that have dynamic content. So in a general way, the onchange event should only be used to do validations that only concern the field itself. Always make sure you consider the initial onchange that is fired on form load; otherwise, you might be showing an error complaining about an empty or invalid field as soon as the form has finished loading!
Data validation by extending the build-in validate function
This is the best place, in my opinion, for atomic data validation - where you do not need other fields' values to validate the current control's data. See the form.addCustomValidation() examples in this article.
Data validation by attaching a function to a submit button
This is the best place, in my opinion, for compound data validation - where you need to validate a block of field values in one pass, such as in an address (street, number, zip, town, state) or a credit card.
You can even add an extra button to your form that will allow the user to validate the data without using one of the Submit buttons.
BP #2: Organizing Your Scripts
When starting to write form scripts, it is natural to start out with form scripts written directly in the build-in or custom events.
A more modular approach is to write re-usable functions that will be stored in an internal script, and then call them from within the events. If you need to have access to the predefined form and IDVault objects inside your functions, you must pass them as parameters to your functions when calling the functions from one of the events.
Example: If you add a library called mylib.js to a war called myscripts.war to the deployment folder of Jboss, you can access it with this relative URL: ?../../myscripts/mylib.js? from within a workflow form.
Note: Starting with IDM 3.5.1, there is now a form onload event. This can be used to regroup field initialization in one place, instead of having pieces of script in the control's onload event.
BP #3: Internationalization and Localization
You can use java resourcebundles when showing errors or other information to the user. The form.showMsg(), showWarnign(), showError(), and showFatal accept a key and bundle ID. The resourcebundle must be on the Jboss's classpath, either in the UA WAR or in JBoss's lib folder.
You can also directly extract an entry from a resourcebundle with form.getRBMessage.(). Should you need to test the user's locale, it is available from form.getLocale().
Disclaimer: As with everything else at Cool Solutions, this content is definitely not supported by Novell (so don't even think of calling Support if you try something and it blows up).
It was contributed by a community member and is published "as is." It seems to have worked for at least one person, and might work for you. But please be sure to test, test, test before you do anything drastic with it.