I finished a new version of validanguage last night and have added it to the download page. As always, the documentation on the new features is running a little behind the actual release, so this blog post will describe the changes briefly until I find the time to update the docs more fully.

However, in conjunction with this release, I used the JsDoc Toolkit to dynamically generate API documentation from the inline comments in validanguage.js. This API reference can be found at: http://www.drlongghost.com/vd_docs/index.html.

Without any further ado, here’s a list of what’s changed:

Added validateForm() method — This new method can be used to manually trigger validation on a form (without actually submitting it) and get access to the validation results and a list of any fields which failed and their error messages.

Added showSubmitMessage() – This new method is intended to be used as an onsubmit transformation for a form. If the form passes validation, the new method will replace the submit button with a div containing the text “Loading” and can also be styled to include a spinner image. This is helpful for signup pages to prevent multiple submissions.

An example of this appears on the validanguage demo

Added ability to manually fail a form field — This enables you to trigger an ajax lookup against a database and, depending on the results, you can mark a field as “failed” so the form won’t be allowed to submit until you manually mark it as “okay” again. You can mark a field as failed by noting it as such inside the corresponding validanguage.el.formFieldId object. For example:

validanguage.el.username.failed = true; //mark as failed
validanguage.el.username.failed = false; //return to normal

An example of this appears on the validanguage demo.

Note that you can also mark a field as “disabled” in the object, which is slightly different:

validanguage.el.username.disabled = true; //Skip any validations for this object
validanguage.el.username.disabled = false; //return to normal

Added showFailedFields option to showError() — This modifes the default showError() function to not only include an inline error message next to any failed fields, but it also populates a DIV with a list of all the fields which failed. By default, this is turned off, but it can enabled by setting : validanguage.settings.showFailedFields = true.

The names used for the form fields in showFailedFields is determined by the new validanguage.el.field setting (described below).

An example of showFailedFields (using manual CSS to style the DIV) appears on the validanguage demo

Added field attribute to validanguage.el — This new option allows you to specify a human-readable name for a field. Thus, you can tell validanguage to refer to the field that has an ID of “email1″ as the more human-friendly “Email Address”. If validanguage.el.field is not provided, it will be inherited from the field ID. Note that the new field attribute is included in the failedValidations argument which is passed to onsubmit transformations and to the results of a call to validateForm().

You can specify the new field attribute using either the comment-based API or the Object API.

Added validanguage.settings.onload — Enables you to specify a function to run after the validanguage.populate() function has finished loading and all validations have been loaded and prepared for use.

Added addValidation() and removeValidation() — These new functions enable you to manually add or disable validations after the page has loaded and any specified validation rules have been created. In order to use addValidation(), the new validation must be present in the validanguage.el.formField.validations array, which means this will only work on validations which were loaded during the page load and later removed (which doesn’t actually remove them from this array), or on validations which are later dynamically added to this array using the Object API.

To add or remove a validation, you must refer to it by the exact name/array/function definition in which it appears in this array. You can also use the ‘*’ character in the arguments for these methods to specify *any* validation or *any* event handler. See the API page for additional details.

Bug Fix: onsubmit transformations now called in form’s scope

Bug Fix: forms submitted via Enter key are now validated

Hopefully I’ll be able to beef up the documentation on these new features soon. In the meantime, let me know if you have any questions.