Javascript validation library

Javascript validation library – Library API and customization possibilities for client-side validation

API docs generation

Javascript code has API documentation comments that can be extracted with JsDoc toolkit. SVN checkout of HTML_QuickForm2 contains Phing build file for this.

Helper objects and functions

All Javascript code defined in HTML_QuickForm2 lives in qf "namespace". Deeper namespaces are used to group related functionality.

qf.Map is a class for Hash Map data structure. It is used internally to store validation errors and Container values.

var map = new qf.Map();
map.set('a key', 'a value');
alert(map.get('a key')); // a value
alert(map.hasKey('another key') ? 'true' : 'false'); // false
alert(map.length()); // 1

var map2 = new qf.Map({foo: 'foo value', bar: 'bar value'});
map.merge(map2);
map.remove('foo');
alert(map.getKeys().join(', ')); // a key, bar
alert(map.getValues().join(', ')); // a value, bar value
map.clear();
alert(map.isEmpty() ? 'true' : 'false'); // true

qf.form namespace contains methods for getting and setting elements' values: qf.form.getValue(), qf.form.getSubmitValue() (shorthand qf.$v()), qf.form.getContainerSubmitValue() (shorthand qf.$cv()), qf.form.setValue().

Methods for handling CSS classes on elements live in qf.classes namespace: qf.classes.add(), qf.classes.remove(), qf.classes.has().

qf.events namespace contains helper methods for crossbrowser events support: qf.events.addListener(), qf.events.removeListener(), qf.events.fixEvent(). The latter is expected to be used in event handlers in the following way

qf.Validator.submitHandler = function(event)
{
    event = qf.events.fixEvent(event);
    // ...
};

HTML_QuickForm2 does not contain a full-blown crossbrowser event library because it does not need one, the above are simple convenience methods. There are numerous well-known JS frameworks with good crossbrowser events support, use one if needed.

qf.rules and qf.elements namespaces are intended for rule implementations and element support methods, respectively. For example, Hierselect element puts its code into qf.elements.hierselect.

qf.Validator object

Client-side validation is performed by an instance of qf.Validator. Its constructor accepts DOM object of a form it needs to validate, sets up necessary event handlers on that object and adds itself as a validator property of it.

It is easiest to disable client-side validation for a form by clearing validator property from form's DOM object:

document.getElementById(formId).validator = null;

qf.Validator exposes several methods which can be overriden to change the way validation results are presented to user:

onStart()
Called before starting the validation. May be used e.g. to clear the errors from form elements.
onFieldError()
Called on setting the element error.
onFieldValid()
Called on successfully validating the element.
onFormValid()
Called on successfully validating the whole form.
onFormError()
Called on failed form validation. List of errors is available in this.errors property, which is an instance of qf.Map.

These can be overriden either for a particular instance of qf.Validator or for all its instances if qf.Validator.prototype is changed.

For example, if you want to display a list of validation errors in an alert() (as was done in HTML_QuickForm and pre-0.6.0 HTML_QuickForm2) you can do the following:

var form = document.getElementById(formId);
form.validator.onFormError = function() {
    alert('Invalid information entered:\n - ' +
          this.errors.getValues().join('\n - ') +
          '\nPlease correct these fields.');
};
// don't set errors on elements
form.validator.onFieldError = function() {};
form.validator.onFieldValid = function() {};

If you want to disable submit button to prevent duplicate form submits:

document.getElementById(formId).validator.onFormValid = function() {
    document.getElementById(submitId).disabled = true;
};