JavascriptValidation

From GeoMedia Smart Client
Jump to: navigation, search
GMSC 2013/2014 Javascript API Overview Form Events Types Utility Functions client-side Validation Conditions Interaction with SmartClient Cookbook Cheatsheet


Client-Side Validation

Client-side validation allows the Workflow Author to catch common form completion errors BEFORE the form content is posted to the server. This eases form completion for the user. GMSC Admin provides an extensible validation interface that is implemented with validators. A validator is a Javascript function that receives the current value of a form field as parameter, examines it with a specific business logic and either returns true (validation passed) or false (validation not passed, display error message). Each validator is uniquely identified by a name and also includes a localizeable error message. GMSC 07

Validation02.png

Builtin Validators

The following validators are provided out of the box in GMSC Workflows:


Blue.png The examples are given in formsettings.xml syntax, because this is the primary and recommended way to assign validators. In the rare case that you want to assign validators at runtime, see Assigning validators at runtime section.



core validators

all core validators are available since GMSC 07

Validator example description
required required() Form field must not be empty or unchecked (checkboxes).
minlength minlength(3) form field has to contain at least n chars
maxlength maxlength(9) form field can only contain up to n chars
min min(10) number in the form field must be greater than n
max max(200) number in the form field must be less than n
range range([9,99]) number in the form field must be in the range between n and m
email email() form field must contain a valid email adress (the existence of the email-adress is not checked)
url url() form field must contain a valid url (the existence of the url is not checked)
number number() form field must contain a number, with the . as delimitor, e.g. 99.62. You can also define directly your datatype of your FormField as a number (see here).
equalTo equalTo('Password1') form field needs to have the same value than other form field (referenced by its field name - case sensitive!)

date comparison validators

All date comparison validators are available since GMSC 2013

date validator example description
gtDate gtDate('OTHER_DATE_FIELD') date greater than the date in the form field with id OTHER_DATE_FIELD
gteDate gteDate('OTHER_DATE_FIELD') date greater or equal than the date in OTHER_DATE_FIELD
eqDate eqDate('OTHER_DATE_FIELD') date equal to the one in OTHER_DATE_FIELD
lteDate lteDate('OTHER_DATE_FIELD') date less than or equal to the one in OTHER_DATE_FIELD
ltDate ltDate('OTHER_DATE_FIELD') date less than the the one in OTHER_DATE_FIELD
betweenDate betweenDate('BEGIN_DATE_FIELD', 'END_DATE_FIELD') checks if the value of the current date field lies between the current value of BEGIN_DATE_FIELD and END_DATE_FIELD. Available since GMSC 2014

number comparison validators

all number comparison validators are available since GMSC 2013

number validator example description
gtNumber gtNumber('OTHER_NUMBER_FIELD') number greater than the number in the form field with id OTHER_NUMBER_FIELD
gteNumber gteNumber('OTHER_NUMBER_FIELD') number greater or equal than the number in OTHER_NUMBER_FIELD
eqNumber eqNumber('OTHER_NUMBER_FIELD') number greater or equal than the number in OTHER_NUMBER_FIELD
lteNumber lteNumber('OTHER_NUMBER_FIELD') number less than or equal to the number in OTHER_NUMBER_FIELD
ltNumber ltNumber('OTHER_NUMBER_FIELD') number less than the number in OTHER_NUMBER_FIELD


relative date/datetime comparison validators

date/datetime comparison validators check the value of date/datetime fields against the current system date of the user's computer. They can be used to restrict the input of date values to past or future dates and are available since GMSC 2014.

number validator example description
afterNow afterNow() ensures that the datetime string in a datetime field lies in the future (i.e. is after the current datetime).
afterToday afterToday() ensures that the date string in a date field lies in the future (i.e. is after the current date).
beforeNow beforeNow() ensures that the datetime string in a datetime field lies in the past (i.e. is before the current datetime).
beforeToday beforeToday() ensures that the date string in a date field lies in the past (i.e. is before the current date).
beforeTomorrow beforeTomorrow() ensures that the date string in a date field does not lie in the future (i.e. is on or before the current day)


Assigning validators at runtime

If you want to assign validators at runtime, you can do so in a custom script. GMSC 2013 However, this should only be your last resort, we recommend to assign the validators via your formsettings.xml file. Here is a short sample:

var field = IG.form.getItemById('FIELD')
field.value.extend({afterToday: true}); //assign the afterToday validator. If a validator requires no arguments, simple use true as argument. 
field.value.extend({equalTo: 'OTHER_FIELD'}); //assign the equalTo validator. If a validator requires one argument, use the object literal notation {}
field.value.extend({betweenDate: ['FIRST_DATE_FIELD','SECOND_DATE_FIELD']}); //assign the betweenDate validator. If a validator requires multiple arguments, put them into an array literal [] within the object

Writing your own validators

You can write custom validators that implement your own validation logic. A validator is a plain javascript function that receives the current value of the form field it was assigned to. Your validator should return true if the value passes the test and false if it doesn't.

Add you custom validators directly to your customscript file by using the IG.validation.addValidator function described below. Do not wrap them into an event handler (e.g. onFormReady), since the custom validators have to be registered before form initialisation begins.

IG.validation.addValidator (validatorId, validatorFunc, errorMessage)

allows the global registration of custom validators to use them in workflow forms. GMSC 2013

Parameters

{String} validatorId the identifier of the validator which will later be used to reference it in Formsettings.xml. Must confirm to the naming rules of Javascript functions (i.e. must start with a letter, no spaces, unique name)

{Function} validatorFunc the validator function. receives the current field value as parameter and must either return true or false.

{String} errorMessage the error message for invalid inputs.


Examples

This validator throws an error if the field value is not "42"

 IG.validation.addValidator('answeris42', function (value) {
     return value === "42";
 }, 'The answer is 42');

This validator throws an error if the field input is not divisible by 4.

 IG.validation.addValidator('divisibleby4', function (value) {
     return (parseInt(value, 10) % 4 === 0);
 }, 'input must be divisible by 4');


Localisation of Error Messages

To localise your validator error message for different languages/cultures, simply edit the correspondig .js file in scripts/IGForm/cultures. GMSC 2014

In order to localise the divisbleby4 validator for the german language, you would edit validation.culture.de.js like so:

    IG.localize.validation = {
        required: 'Ist ein Pflichtfeld.',
        //...more localisation messages...
        divisibleby4: "Die Zahl muss durch 4 teilbar sein" //<-- the message you add
    };