# LiveValidation

## Validation as you type!

## Examples...

Here you will see LiveValidation in action, and the code that makes it all happen, to serve as examples of its capabilities and as tutorials to get you started.

IMPORTANT - As you probably already know, relying on client-side validation alone is a very bad idea. Always perform appropriate server-side validation as well. The purpose of this library, and javascript validation in general, is not to replace server-side validation, but make the act of filling in a form less daunting for a user, and to save them time.

#### Contents

- Homepage example
- Presence
- Format
- Numericality
- Length
- Inclusion
- Exclusion
- Acceptance
- Confirmation
- Email
- Composite validations (combining validations)
- Validating entire forms
- Styling it up

### Homepage example Top

First up, just in case you were wondering, the homepage example consists of 2 validations - Presence to make sure it is filled in, and Format to check that the value entered contains ‘hello’ in any case. Here is how it works...

Say “hello”:

First the field is set up to be a LiveValidation object, by passing in its id as the first argument. In this example the validMessage has also been overridden by including an options object, and the wait option is set to 500 milliseconds, to make it only validate 500ms after the user stops typing:

    var sayHello = new LiveValidation( "sayHello", { validMessage: "Hey there!", wait: 500 } );

Then the Presence validation is added to it, and this example also provides an overridden failureMessage:

    sayHello.add( Validate.Presence,
                  { failureMessage: "Don't just ignore me, I wanna be your friend!" } );

Finally the Format validation is added, with the regular expression pattern to validate against, again with an overridden failureMessage for this example:

    sayHello.add( Validate.Format,
                  { pattern: /^hello$/i, failureMessage: "How come you've not said 'hello' yet?" } );

### Presence Top

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

Enter the field then click somewhere else:

    var f1 = new LiveValidation('f1');
    f1.add( Validate.Presence );

### Format Top

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

Should contain the phrase “live” in any case:

    var f2 = new LiveValidation('f2');
    f2.add( Validate.Format, { pattern: /live/i } );

### Numericality Top

This kind of validation is concerned with numbers. It can handle scientific numbers (ie. 2e3, being 2000), floats (numbers with a decimal place), and negative numbers properly as you would expect it to throughout, both in values and parameters.

#### Basic

This example will check if the value provided is a number, or can be converted into a number successfully (ie from a string - the value of a text input is a string). This is performed on every type of Numericality validation automatically, but can be used in its simplest form like this, if you only want to make sure the value entered is a number.

Should be a number:

    var f3 = new LiveValidation('f3');
    f3.add( Validate.Numericality );

#### Only allow integers

This example will check that the number supplied is, or equates to, an integer (ie. no decimal places).

Should be an integer:

    var f4 = new LiveValidation('f4');
    f4.add( Validate.Numericality, { onlyInteger: true } );

#### Specific number

This example will check that the value is the same as, or equates to, a specific number that you supply.

Should be 2000 (or scientific representation of it, 2e3):

    var f5 = new LiveValidation('f5');
    f5.add( Validate.Numericality, { is: 2000 } );

#### Higher than or equal to a minimum number

This example will check that the value is more than or equal to a minimum number that you supply.

Should be 2000 or higher (or scientific representation of it, 2e3):

    var f6 = new LiveValidation('f6');
    f6.add( Validate.Numericality, { minimum: 2000 } );

#### Lower than or equal to a maximum number

This example will check that the value is less than or equal to a maximum number that you supply.

Should be 2000 or lower (or scientific representation of it, 2e3):

    var f7 = new LiveValidation('f7');
    f7.add( Validate.Numericality, { maximum: 2000 } );

#### Within a range of numbers

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 2000 and 2003:

    var f8 = new LiveValidation('f8');
    f8.add( Validate.Numericality, { minimum: 2000, maximum: 2003 } );

#### Combination

Most of the above parameters can be combined, the only execption being that you cannot combine ‘is’ with ‘minimum’ or ‘maximum’, if this is done ‘is’ will take precedence. This example will check that the value is a number that falls within a range that you supply, and that it is an integer. This is done supplying both a ‘minimum’ and ‘maximum’, and true for ‘onlyInteger’.

Should be between 2000 and 2003, and also be an integer:

    var f9 = new LiveValidation('f9');
    f9.add( Validate.Numericality, { minimum: 2000, maximum: 2003, onlyInteger: true } );

### Length Top

Length is concerned with the number of characters in a value. You can do various validations on it, like check it is a specific length, less than or equal to a maximum length, greater than or equal to a minimum length, or falls within a range of lengths.

#### Specific length

This example will check that the value is the exact length of which you supply.

Should be 4 characters in length:

    var f10 = new LiveValidation('f10');
    f10.add( Validate.Length, { is: 4 } );

#### 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:

    var f11 = new LiveValidation('f11');
    f11.add( Validate.Length, { minimum: 4 } );

#### 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:

    var f12 = new LiveValidation('f12');
    f12.add( Validate.Length, { maximum: 4 } );

#### 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:

    var f13 = new LiveValidation('f13');
    f13.add( Validate.Length, { minimum: 4, maximum: 8 } );

### Inclusion Top

Inclusion lets you validate against a list of allowed values. You can do an exact match or a partial match.

#### Exact match

This example will check that the value is the same as any in your allowed values.

Should be “cow”, “pigeon”, or “giraffe”:

    var f14 = new LiveValidation('f14');
    f14.add( Validate.Inclusion, { within: [ 'cow' , 'pigeon', 'giraffe' ] } );

#### Partial match

This example will check that any part of the value matches something in the allowed list. Allow this by setting the ‘partialMatch’ to be true.

Should contain “cow”, “pigeon”, or “giraffe” somewhere in your entry:

    var f15 = new LiveValidation('f15');
    f15.add( Validate.Inclusion, { within: [ 'cow' , 'pigeon', 'giraffe' ], partialMatch: true } );

### Exclusion Top

Exclusion lets you validate against a list of values that are not allowed. You can do an exact match or a partial match.

#### Exact match

This example will check that the value is not the same as any in your allowed values.

Should not be “cow”, “pigeon”, or “giraffe”:

    var f16 = new LiveValidation('f16');
    f16.add( Validate.Exclusion, { within: [ 'cow' , 'pigeon', 'giraffe' ] } );

#### Partial match

This example will check that no part of the value matches something in the disallowed list. Allow this by setting the ‘partialMatch’ to be true.

Should not contain “cow”, “pigeon”, or “giraffe” anywhere in your entry:

    var f17 = new LiveValidation('f17');
    f17.add( Validate.Exclusion, { within: [ 'cow' , 'pigeon', 'giraffe' ], partialMatch: true } );

### Acceptance Top

Acceptance lets you validate that a checkbox has been checked.

I accept that LiveValidation is the validation of my dreams:

    var f18 = new LiveValidation('f18');
    f18.add( Validate.Acceptance );

### Confirmation Top

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:

    var f19 = new LiveValidation('f19');
    f19.add( Validate.Confirmation, { match: 'myPasswordField' } );

### Email Top

The email validation is not a real kind of validation in the sense that it actually uses the Validate.Format function to do its validation. It is essentially a validation that is done often enough to merit its own function so you don’t have to remember the long regular expression and custom failureMessage each time you want to validate an email.

It also serves as an example for the more adventurous of you, who want to make your own library of custom validations that you will use often. These will most likely include things like postcodes, telephone numbers, dates etc. which vary far too widely to include here, but it was felt that email addresses are generic enough to warrant inclusion, so here you go.

Should be an email address:

    var f20 = new LiveValidation('f20');
    f20.add( Validate.Email );

### Composite validations (combining validations) Top

Most of the time, you will want to combine multiple types of validation on a single field. As your user is given real-time feedback, it would also be good to be able to specify an order in which they fail, so that the most appropriate message is displayed to avoid any confusion.

LiveValidation makes this easy. You simply keep adding validations to the same LiveValidation object, and they will fail in the order they are added.

The most usual combination you will use is Validate.Presence with one or more other validations, as only Validate.Presence, Validate.Confirmation and Validate.Acceptance will fail and display their message on an empty field. This is because it is common to have fields which are optional, but if the user decides to provide information, then it must be less than a certain length etc. Therefore if you want to ensure a field is filled in, you must add a Validate.Presence, then if you require any more validation types add them too.

You have already seen an example of a composite validation in the homepage example. The following example checks that the field is not empty, then checks that it is an email address, and then makes sure it is between 10 and 20 characters long.

Enter an email address (10 - 20 characters long):

    var f21 = new LiveValidation('f21');
    f21.add( Validate.Presence );
    f21.add( Validate.Email );
    f21.add( Validate.Length, { minimum: 10, maximum: 20 } );

### Validating entire forms on submittal

When a LiveValidation object is instantiated, if it finds it is a child of a form, it will automatically attach itself to the submit event of the form, so when it is submitted, validation on all the LiveValidation objects inside it will be performed automatically. If any of the validations fail it will stop the form submitting (this of course only works when javascript is on in the users bowser, so be sure to do some validation on the server too!).

You can also specify the onlyOnSubmit option to be true when you create the LiveValidation object to make it only validate when the form is submitted. This is demonstrated in the following example.

Note also that the email field has no validation that it is present, therefore if this is not filled in the form will still be valid, as it will be treated as an optional field.

In this example the outcome is overidden if it is valid as this page has nowhere to submit to - instead of submitting, it will alert that it is valid, in real life it will just carry on submitting if valid.

Example of form validation

Email (optional):

Acceptance (required):

Presence (required):

    var field1 = new LiveValidation( 'field1', {onlyOnSubmit: true } );
    field1.add( Validate.Email );
    var field2 = new LiveValidation( 'field2', {onlyOnSubmit: true } );
    field2.add( Validate.Acceptance );
    var field3 = new LiveValidation( 'field3', {onlyOnSubmit: true } );
    field3.add( Validate.Presence );

### Styling it up Top

LiveValidation objects use a few CSS classes to allow you to style up the messages and the form fields based upon whether they are valid or not.

- LV_validation_message - the class that is added to all validation messages
- LV_valid - the class that is added to a valid message
- LV_invalid - the class that is added to an invalid message
- LV_valid_field - the class that is added to a valid field
- LV_invalid_filed - the class that is added to an invalid field

To start you off, these are the styles that this site uses for them:

    .LV_validation_message{
        font-weight:bold;
        margin:0 0 0 5px;
    }

    .LV_valid {
        color:#00CC00;
    }

    .LV_invalid {
        color:#CC0000;
    }

    .LV_valid_field,
    input.LV_valid_field:hover,
    input.LV_valid_field:active,
    textarea.LV_valid_field:hover,
    textarea.LV_valid_field:active {
        border: 1px solid #00CC00;
    }

    .LV_invalid_field,
    input.LV_invalid_field:hover,
    input.LV_invalid_field:active,
    textarea.LV_invalid_field:hover,
    textarea.LV_invalid_field:active {
        border: 1px solid #CC0000;
    }

© 2007-2008 Alec Hill | MIT license