Validator types

Presence

Presence will fail if there is no value entered in the field.

Enter the field then click somewhere else:
```
<input class=":required" type="text">
        
```
Format

Format will fail if the value does not match the regular expression.

Should be repetition of the phrase "vanadium" in any case:
```
<input class=":format;/^(vanadium)+$/i" type="text">
        
```
Ajax - using server-side to do the job!

Sometimes the logic needed to perform the validation is accessible on the server-side. An example of such case could be checking whether given username is already taken. The validation example below is doing just it. When the value in field changes it sends the value via Ajax request and receives response in special json structure. You can find the description of the structure in documentation

Provide desired nickname:
```
<input id="pass" class=":ajax;/username_checker/check.json" type="text">
        
```
Additionally if the resource in subject (e.g. username) is free indeed, server could lock it for a specific period of time, so when the user finally submit the form it will be guaranteed that the resource wasn't taken by other session. To do that server needs to include cookie in response and check it on the request.
Numbers
- Integer
  Integer simply checks if provided value is ... well integer. E.g. 1000, 99, 3
  
  Should be integer:
```
<input class=":integer" type="text">
        
```
- Float
  Float simply checks if provided value is ... well float. E.g. 123.123, 0.3, 2e10, -3.4E-30
  
  Should be float:
```
<input class=":float" type="text">
        
```
Specific length
- Length
  This example will check that the value is the exact length of which you supply.
  
  Should be 4 characters in length:
```
<input class=":length;4" type="text">
        
```
- Longer than or equal to a minimum length
  This example will check that the value is more than or equal to a minimum length that you supply.
  
  Should be 4 or more characters in length:
```
<input class=":min_length;4" type="text">
        
```
- Shorter than or equal to a maximum length
  This example will check that the value is less than or equal to a maximum length that you supply.
  
  Should be 4 or less characters in length:
```
<input class=":max_length;4" type="text">
        
```
- Within a range of lengths
  This example will check that the value is a number that falls within a range that you supply. This is done supplying both a minimum and maximum.
  
  Should be between 4 and 8 characters in length:
```
<input class=":min_length;4 :max_length;8" type="text">
        
```
Acceptance
Acceptance lets you validate that a checkbox has been checked.

I accept that Vanadium is the validation of my dreams:
```
<input class=":accept" type="checkbox">
        
```
Confirmation
This is used to check that the value of the confirmation field matches that of another field. The most common use for this is for passwords, as demonstrated below, but will work just as well on other field types.

Enter a password:

Confirm password:
```
<input id="pass" class=":required" type="password">
        <input class=":same_as;pass" type="password">
        
```
Email address
This is used to check that the provided value is valid email address.

Should be an email address:
```
<input id="pass" class=":email" type="text">
        
```
Validating entire forms on submittal

Vanadium not only weaves in its magic to the individual html elements but also takes into account the entire forms. When form is submitted, Vanadium hooks into the onsubmit event. It performs the validation on all form's elements, preventing submission of the form in case there is any invalid element in it.

Example of form validation
Email (required):

Acceptance (required):

Presence (required):

<form method="get" action="submit_example_form.html">
        <fieldset>
        <legend>Example of form validation</legend>
        <p><label for="email">Email (required):</label><input style="width: 200px" type="text" class=":email :required"/></p>
        <p><label for="accept">Acceptance (required):</label><input type="checkbox" class="checkbox :accept"/></p>
        <p><label for="desc">Presence (required):</label><textarea style="width: 200px" cols="10" rows="2" class="shallow :required"></textarea></p>
        <p><input type="submit" value="Test me!" class="submit"/></p>
        </fieldset>
        </form>

Making use of server-side validation logic.

Vanadium works in three phases. The first, initialization, phase is run when the HTML document is loaded. That phase reads Vanadium's declaration and instruments the document with javascript for you. Then there are two other phases, validation and decoration which are run every time element/form changes. Validation phase executes validation checks according to declatartion and produces special datastructure describing the result of these checks. Decoration phase uses the result of validation phase and applies proper CSS class changes and other DOM manipulations. This aproach has a reason. Basically, the division of validation into to separate activities allows to obtain the validation result not only by executing validation on client-side but also use server-side generated results to use it in exactly same fasion on client-side decoration. Thus Vanadium is said to be server-side aware. The awarnes means Vanadium make use of server-side logic to drive client-side decoration. There are two ways of integrating Vanadium with server.
- classic request - response
  When our form is classiclaly submitted to the server (e.g. there is no Ajax involved in form submittal). That case requires, in case of server-side validation faillure, server to return the same page, with JSON holding the result of the validation applied to Vanadium.decorate(JSON_RESULT) function.

For example:

<form method="get" action="submit_example_form.html">
        <fieldset>
        <legend>Example of form validation</legend>
        <p><label for="email">Email (required):</label><input style="width: 200px" type="text" class=":email :required"/></p>
        <p><label for="accept">Acceptance (required):</label><input type="checkbox" class="checkbox :accept"/></p>
        <p><label for="desc">Presence (required):</label><textarea style="width: 200px" cols="10" rows="2" class="shallow :required"></textarea></p>
        <p><input type="submit" value="Test me!" class="submit"/></p>
        </fieldset>
        </form>
          <script type="text/javascript">
        var server_side_validation_result =
        {
        validation_failed:
        {
        email:
        [{
        success: false,
        message: "This is not vaid email."
        }]
        }
        };
        Vanadium.decorate(server_side_validation_result);
        </script>

*   ### Ajax form submittal
            We can submitt our form by using asynchronous javascript request. One of the easeis way of doing that is to use grat [jQuery Form plugin](http://plugins.jquery.com/project/form).
            In that case the server response is just JSON holding the server-side validation result.
            In Ajax *success* method we call Vanadium.decorate(JSON_RESULT) function analogously to classic form submit.

For example:

server response:

{
        validation_failed:
        {
        email:
        [{
        success: false,
        message: "This is not vaid email."
        }]
        }
        }

Ajaxyfied form:

<form method="get" action="submit_example_form.html">
        <fieldset>
        <legend>Example of form validation</legend>
        <p><label for="email">Email (required):</label><input style="width: 200px" type="text" class=":email :required"/></p>
        <p><label for="accept">Acceptance (required):</label><input type="checkbox" class="checkbox :accept"/></p>
        <p><label for="desc">Presence (required):</label><textarea style="width: 200px" cols="10" rows="2" class="shallow :required"></textarea></p>
        <p><input type="submit" value="Test me!" class="submit"/></p>
        </fieldset>
        </form>
        <script type="text/javascript">
        $(function() {
        $('form').ajaxForm(
        {
        dataType: 'json',
        success: function(data) {
        if (data.validation_failed) {
        Vanadium.decorate(data.validation_failed);
        }
        return false;
        }
        }
        )
        })
        </script>

That was just few examples of Vanadium build-in validators. There is much more. And there is easy way for including your own. Please have look at documentation for full reference.

Grouping validation elements

Validated elements can be grouped in containers which could be CSS styled reflecting status of the validation group. Further more containers can be grouped as well, allowing us to have hierarchical regions of success or failure.

Advising users about the correct input

Every html element being validated has corresponding advice element associated. If you do not specify any advice element for validated one, advice element will be automatically created as with CSS class vanadium-advice. Additionally advice can have vanadium-invalid or vanadium-valid CSS class depending on whether the advice regards to the element failed or passed. If you provide advice by creating a html element containing desired message in case of validation failure, you should ensure the advice is initially hidden by setting its display attribute to none. E.g.:

<div id="adv" style="display:none"> the element is required and should be valid email address </div>
        <input id="email :required;;adv" type="text"/>

When the element is validated and the validation fails, the advice display attribute is set to block value. If you provide advice by creating a html element containing no child elements. Such elements will be automatically added when validation fails. The corresponding messages are defined in validation types.

Declarative Validation
Vanadium is declarative client-side validation toolkit. These declaration can be done in two different ways:
- Using json structure
  This method requires that elements under validation have to have their IDs defined. Granted that, one can declare validation of the form from [example] by including following code:
```
  var VanadiumRules = {
        email: ['required', 'email'],
        accept: ['accept'],
        desc: ['required']
        }
        
```
- Using inline markup
  This method simply uses special markup in html elements' class attributes. The markup is very straightforward. It is consists up to three tokens, prepended with special prefix distinguishing the markup from regular CSS names and separate by special separator. The prefix and the separator are customizable and can be any string. The default prefix is : (colon) and the separator is ; (semicolon). The first token, which is mandatory, is validator type name. The second one is the parameter for the validator. E.g. number of characters when length validator is used. The third token is the ID of the html element serving as an advice into which the message informing about validation failure is inserted. Said that, a html for an element being required valid email address with advice of ID adv would look like:
```
<div id="adv" style="display:none"> the element is required and should be valid email address </div>
        <input id="email :required;;adv :email;;adv" type="text"/>
        
```
  As you can see the double semicolon is used denoting simply no parameter for validator type is provided.
Deferring validation

The default behaviour for validated elements is the immediate validation of an element when its value has changed. As almost everything in Vanadium that can be configured as well.
- Immediate validation (default one). Immediate is too big word in this context. In fact Vanadium deliberately waits 100 ms not to get too CPU hungry still giving user flashy experience.
```
<input class=":required" type="text">
        
```
- Delayed validation. If you want to delay the Vanadium reaction on user changes you can do it by providing wait option. Vanadium will patiently wait given number of milliseconds.
```
<input class=":required :wait;500" type="text">
        
```
- When losing focus. If you consider work on particular input to be finished when user leaves the field only_on_blur is the thing you want.
```
<input class=":required :only_on_blur" type="text">
        
```
- When submitting the form. If you wish Vanadium to process your inputs only when containing form is about to be submitted only_on_submit is the thing you want.
```
<input class=":required :only_on_submit" type="text">
        
```

Download

You can download the Vanadium in uncompressed form with comments from vanadium.js (38kB)

There is also minimized version of it vanadium-min.js (20kB)

Installation

The installation is dead simple. Just include vanadium.js in header of your HTML after the dependency (jQuery)

        <head>
            ...
            ...
            <script src="/js/vanadium.js" type="text/javascript"></script>
            ...
            ...
        </head>

Coffee is good. Coffee must be drunk.
If you enjoy Vanadium please buy me a cup of
. Thank you!
You can also ask any questions related to Vanadium by contacting with me on info@VanadiumJS.com

I would be very grateful for any comments.
My personal blog is lambder.com

Validator types

Presence

Format

Ajax - using server-side to do the job!

Numbers

Integer

Float

Specific length

Length

Longer than or equal to a minimum length

Shorter than or equal to a maximum length

Within a range of lengths

Acceptance

Confirmation

Email address

Validating entire forms on submittal

Making use of server-side validation logic.

classic request - response

Grouping validation elements

Advising users about the correct input

Declarative Validation

Using json structure

Using inline markup

Deferring validation

Download

Installation

Coffee is good. Coffee must be drunk.