I'm headed to OSCON 2008 in a couple days and before I head out for Portland, I wanted to issue a new version of Validanguage to release the new features I've been working on over the past couple months. Unfortunately, I haven't yet had time to update the documentation page to include all the new functionality, so in the meantime, this blog post will have to serve as a supplement to the new release.
I'll mention the two changes first which affect the APIs, as these are the most important in terms of potential impact on existing code. First off, I fixed some bugs in terms of how the Object API and the Comment API parse the validation event handlers. I don't think previous versions of the code were consistent in this and didn't always do what the documentation indicated.
The following is now the preferred way to load a custom validation as onblur only:
Comment API: <validanguage target="text" validations="customFunction" onblur="true" />
Object API:
validanguage.el.text = {
validations: [ {
name: customFunction,
onblur: true
} ]
When a function is provided without any event handlers associated with it (and this includes the shortcuts like required and maxlength) the validanguage.settings.defaultValidationHandlers setting is used to determine which event handler(s) to assign. But when an event handler is provided using the above syntax, only the provided handler(s) will be used.
Previously, it was possible to use the syntax onblur="customFunction" to define a custom validation. This has now changed and the shorthand usage of onblur="customFunction" is reserved for defining a transformation. To create a validation for onblur only, you will now need to follow either of the examples above.
Transformations
This new version of validanguage includes support for a new class of functions I have named Transformations. These are intended to be used as functions which reformat the data inside a text field, or which interact with a server backend via Ajax. Transformations are defined with the following syntax:
Comment API: <validanguage target="text" transformations="customFunction" onblur="true" />
Object API:
validanguage.el.text = {
transformations: [ {
name: customFunction,
onblur: true
} ]
Or, as indicated above, the onblur="customFunction" shorthand can also be used to define a transformation.
Like validations, transformations are executed within the scope of the form field on which they are applied. I have an example of the preset "validanguage.format" transformation (which is now provided in validanguage.js) on the validanguage test case pages. In this example, I use the validanguage.format function to reformat a US phone number to add spaces, dashes and parenthesis when the user tabs out of the field. Here is the Object API code used to load this function (note the use of .call to preserve scope):
onblur: function() { validanguage.format.call( this, '(xxx) xxx-xxxx', '-() ' ) }
See the validanguage_uncompressed.js for more details on how to use validanguage.format().
Form-Level Transformations
In addition to the field-specific transformations above, you can now use form-specific onsubmit transformations to define custom error/success handlers on a form, which provides the ability to prevent a form from submitting and instead submit it via Ajax. Because this use of transformations duplicates functionality already added via the onsubmitsuccess hook, I have removed onsubmitsuccess from validanguage. The new form-level transformations offer more functionality than the old onsubmitsuccess hook.
Form-level transformations can be defined with the following syntax:
Comment API: <validanguage target="form1" onsubmit="formHandler" />
Object API:
validanguage.el.form1 = {
onsubmit: 'formHandler'
Both of the above examples would call a function named formHandler after all validations have been performed. The formHandler function is executed within the scope of the form and is passed 2 arguments:
1st argument / submitStatus = A boolean indicating whether or not any form fields flunked validation
2nd argument / failedValidations = An array of objects containing details on any flunked validations, including their error messages
An onsubmit form transformation can suppress or allow a form to be submitted by returning a boolean value. So, if the customHandler function above were to be used to submit a form via Ajax, it would issue the Ajax call and then return false to block the form submission. To have a transformation not affect the form submission either way, simply avoid returning anything.
In the coming weeks I will be adding several demos that better illustrate how transformations work. In the meantime, hopefully the explanation above and the commented source code will suffice.
Additional changes in the 0.9.3 Release:
- Fixed konqueror support for the Comment-based API. Since konqueror does not consider comment nodes as part of the DOM, for konqueror only, an Ajax call is issued for the document source, which is then parsed to retrieve any validanguage comments.
- To support the above, a basic validanguage.ajax() function was added and is now available for use
- An onerror and onsuccess handler have been added to display error messages inline, instead of using an alert() call. Alerts can still be used but are now no longer the default. The appearance of the error messages can be styled via CSS. The default class names are .vdError and .vdNoError, but these can be changed via a global setting. The new onsuccess function will create a div to place the error message in. The div is appended after the form field, unless the element immediately after the form field is a <label> tag, in which case it is appended after the label. Thus, if you wish to use this function with radio buttons or checkboxes, define the validations on the final button/checkbox and make sure no whitespace separates the input from its label. Otherwise, the error message div will most likely not appear where you want it to.
- A new ontyping event has been added. Ontyping is similar to onkeypress but it uses a 2 second timeout, so the user will need to stop typing for 2 seconds before the function is called. This is useful for things such as Ajax calls where you want to wait for a lull in the user's typing behavior before issuing of an ajax call.
- Multiple validanguage tags are now supported per comment. By default a given validanguage tag is expected to only span a single line, but if you always remember to close your validanguage tags, you can change validanguage.settings.commentDelimiter from "\n" to "/>" to allow yourself to have a single validanguage comment span multiple lines.
- Disabled form fields are now not validated.
I guess that's about it for now. Feel free to email me or post questions below about anything that's unclear. I should have some examples up in the next 3 weeks or so which will better explain the new functionality I've added, and I'll also update the existing documentation to reflect these changes.
