Javascript code has API documentation comments that can be extracted with JsDoc toolkit. SVN checkout of HTML_QuickForm2 contains Phing build file for this.
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
.
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:
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; };