AMD

If using an AMD loader, move the ./js/mystique folder from the downloaded source into a location where your AMD loader can access the files. You may also need to configure your AMD loader to know where the Mystique package is.

Dojo example

Using the dojo AMD loader, place ./js/mystique in the same folder as your dojo packages:

./
├── dojo/
├── dijit/
└── mystique/

You will then be able to use require to load any Mystique module. Eg:

require(['mystique/Alpha'], function(Alpha){
    var validator = new Alpha;
});

Stand alone

If you are using the stand alone mystique.js simply add that script to your page:

<script type="text/javascript" src="mypath/mystique.js"></script>

You will then be able to use the mystique global variable to use any Mystique module. Eg:

var validator = new mystique.Alpha;

Validators

To use a validator, first create an instance. Any options can be passed to the constructor in an object:

require(['mystique/Length'], function(Length){
    var validator = new Length({min: 4, max: 50});
});

Then call isValid to test a value

var result = validator.isValid('123456');

The returned Result object contains the validation result:

if ( ! result.get('value')){
    //validation failed
} else {
    //validation passed
}

The returned Result object may also contain an array of validation messages:

alert(result.get('messages').join(' ')); //display any messages

Chains

Chains can be used to string validators together. Eg:

var validator = new Chain({'validators': [
        new Alpha,
        new Length({'min': 5, 'max': 10})
    ]});

Validation can be expensive and repetitive on the client, so javascript validators have a validation cache. If the cache is enabled, if the same value is validated more than once, the result will be retrieved from the cache.

Properties

useCache

Boolean. Defaults to true. Turns cache use on and off. For example, this Alpha validator has the cache turned off:

var validator = new Alpha({useCache: false});

maxCacheSize

Int. Defaults to 50. Defines the maximum cache size. Eg:

var validator = new Alpha({maxCacheSize: 10});

Client side validation may occasionally need to make a request to a server. Javascript validators support async returning of Result objects. Rather than returning a boolean value, a Result may return an object with a then() function which will be called when the async validation is complete. Eg:

var validator = new MyAsyncValidator,
    result = validator.isValid(myValue),
    value = result.get('value');

if (value.then){
    value.then(function(result){
        if (result.get('value')){
            //validator passed async
        } else {
            //validator failed async
        }
    });
} else if (value) {
    //validator passed syncronously
} else {
    //validator failed syncronously
}

Note: if you are using dojo, this works well with the dojo/promise api and dojo/Deferred.

English translations for validator messages are provided (if you would like to add more languages, that would be great!). The dojo/i18n tool is supported if using Mystique with an AMD loader.