Documentation

Documentation

Documentation

This documentation is only concerned with the code you will actually need to know, all methods used internally are committed, but they are all documented in the source code.

Contents

  • Validate (class)
    • Presence (static function)
    • Format (static function)
    • Numericality (static function)
    • Length (static function)
    • Inclusion (static function)
    • Exclusion(static function)
    • Acceptance (static function)
    • Confirmation (static function)
    • Email (static function)
    • now (static function)
  • LiveValidation (class)
    • constructor
    • add (function)
    • massValidate (static function)

Validate (class)

The Validate class contains a number of static methods which are used to perform various types of validation. These are separated out from the LiveValidation class so they can be used in any context in your javascript, not just while validating form fields.

When you add validation to a LiveValidation object, it is one of these validation types that you refer to, so familiarise yourself with them. If you are already familiar with Ruby on Rails validation, then they will be easy to remember, as they use a similar naming convention, and similar parameters (although some parameters’ names are different due to javascript keyword conflicts).

If used separately from a LiveValidation, and validation fails, a custom error is thrown which stores the failure message, so you will need to handle this yourself if you wish to use the message. If you just want a simple true or false, and don’t need to extract the failure message, you can use the Validate. now method to perform the validation.

Presence (static function)

Validates that a value is present (ie. not null, undefined, or an empty string)

Arguments:

value – {mixed} – value to be checked
paramsObj (optional) – {Object} – object containing parameters to be used for the validation

Parameters for paramsObj:

failureMessage (optional) – {String} – message to be used upon validation failure (DEFAULT: “Can’t be empty!”)

Returns:

true if valid or throws a Validate.Error object containing the failure message

Example:

Validate.Presence( 'hello world', { failureMessage: "Supply a value!" } );

Format (static function)

Validates a value against a regular expression

Arguments:

value – {mixed} – value to be checked
paramsObj – {Object} – object containing parameters to be used for the validation

Parameters for paramsObj:

failureMessage (optional) – {String} – message to be used upon validation failure (DEFAULT: “Not valid!”)
pattern – {RegExp} – regular expression to validate against (DEFAULT: /./i)

Returns:

true if valid or throws a Validate.Error object containing the failure message

Example:

// check that 'validation' exists in the string, case insensitive...
Validate.Format( 'live validation', { pattern: /validation/i, failureMessage: "Failed!" } );

Numericality (static function)

Validates that the value is numeric and: is an integer, is a specific number, is more than a minimum number, less than a maximum number, is within a range of numbers, or a combination of these

NB – numbers expressed in scientific form (ie 2e3, being 2000) are handled correctly, as are negative numbers, and floats.

Arguments:

value – {mixed} – value to be checked
paramsObj (optional) – {Object} – object containing parameters to be used for the validation

Parameters for paramsObj:

notANumberMessage (optional) – {String} – message to be used when validation fails because value is not a number (DEFAULT: “Must be a number!”)
notAnIntegerMessage (optional) – {String} – message to be used when validation fails because value is not an integer (DEFAULT: “Must be an integer!”)
wrongNumberMessage (optional) – {String} – message to be used when validation fails when ‘is’ param is used (DEFAULT: “Must be {is}!”)
tooLowMessage (optional) – {String} – message to be used when validation fails when ‘minimum’} param is used (DEFAULT: “Must not be less than {minimum}!”)
tooHighMessage (optional) – {String} – message to be used when validation fails when ‘maximum’} param is used (DEFAULT: “Must not be more than {maximum}!”)
is (optional) – {mixed} – the value must be equal to this numeric value
minimum (optional) – {mixed} – the minimum numeric allowed
maximum (optional) – {mixed} – the maximum numeric allowed
onlyInteger (optional) – {Boolean} – if true will only allow integers to be valid (DEFAULT: false)

Returns:

true if valid or throws a Validate.Error object containing the failure message

Example:

// check that value is an integer between -5 and 2000 exists in the string, case insensitive...
Validate.Numericality( 2e3, { minimum: -5, maximum: 2000 } );

Length (static function)

Validates the length of a value is a particular length, is more than a minimum, less than a maximum, or between a range of lengths

NB – to check if it is within a range, specify both a minimum and a maximum

Arguments:

value – {mixed} – value to be checked
paramsObj – {Object} – object containing parameters to be used for the validation

Parameters for paramsObj:

wrongLengthMessage (optional) – {String} – message to be used when validation fails when ‘is’ param is used (DEFAULT: “Must be {is} characters long!”)
tooShortMessage (optional) – {String} – message to be used when validation fails when ‘minimum’} param is used (DEFAULT: “Must not be less than {minimum} characters long!”)
tooLongMessage (optional) – {String} – message to be used when validation fails when ‘maximum’} param is used (DEFAULT: “Must not be more than {maximum} characters long!”)
is (optional) – {mixed} – the value must be this length
minimum (optional) – {mixed} – the minimum length allowed
maximum (optional) – {mixed} – the maximum length allowed

Returns:

true if valid or throws a Validate.Error object containing the failure message

Example:

// check that value is between 3 and 255 characters long...
Validate.Length( 'cow', { minimum: 3, maximum: 255 } );

Inclusion (static function)

Validates that a value falls within a given set of values

Arguments:

value – {mixed} – value to be checked
paramsObj – {Object} – object containing parameters to be used for the validation

Parameters for paramsObj:

failureMessage (optional) – {String} – message to be used upon validation failure (DEFAULT: “Must be included in the list!”)
within – {Array} – an array of values that the value should fall in (DEFAULT: Empty array)
allowNull (optional) – {Boolean} – if true, and a null value is passed in, validates as true (DEFAULT: false)
partialMatch (optional) – {Boolean}- if true, will not only validate against the whole value to check, but also if it is a substring of the value (DEFAULT: false)

Returns:

true if valid or throws a Validate.Error object containing the failure message

Example:

Validate.Inclusion( 'cat', { within: [ 'cow', 277, 'catdog' ], allowNull: true, partialMatch: true } );

Exclusion (static function)

Validates that a value does not fall within a given set of values

Arguments:

value – {mixed} – value to be checked
paramsObj – {Object} – object containing parameters to be used for the validation

Parameters for paramsObj:

failureMessage (optional) – {String} – message to be used upon validation failure (DEFAULT: “Must not be included in the list!”)
within – {Array} – an array of values that the given value should not fall in (DEFAULT: Empty array)
allowNull (optional) – {Boolean} – if true, and a null value is passed in, validates as true (DEFAULT: false)
partialMatch (optional) – {Boolean} – if true, will not only validate against the whole value to check, but also if it is a substring of the value (DEFAULT: false)

Returns:

true if valid or throws a Validate.Error object containing the failure message

Example:

Validate.Exclusion( 'pig', { within: [ 'cow', 277, 'catdog' ], allowNull: true, partialMatch: true } );

Acceptance (static function)

Validates that a value equates to true (for use primarily in detemining if a checkbox has been checked)

Arguments:

value – {mixed} – value to be checked
paramsObj (optional) – {Object} – object containing parameters to be used for the validation

Parameters for paramsObj:

failureMessage (optional) – {String} – message to be used upon validation failure (DEFAULT: “Must be accepted!”)

Returns:

true if valid or throws a Validate.Error object containing the failure message

Example:

Validate.Acceptance( true, { failureMessage: "You must be true!" } );

Confirmation (static function)

Validates that a value matches that of a given form field

Arguments:

value – {mixed} – value to be checked
paramsObj – {Object} – object containing parameters to be used for the validation

Parameters for paramsObj:

failureMessage (optional) – {String} – message to be used upon validation failure (DEFAULT: “Does not match!”)
match -{mixed} – a reference to, or string id of the field that this should match

Returns:

true if valid or throws a Validate.Error object containing the failure message

Example:

Validate.Confirmation( 'open sesame', { match: 'myPasswordField', failureMessage: "Your passwords dont match!" } );

Email (static function)

Validates a value is a valid email address

This is an example of a custom validation method. This one is essentially just a Format validation, but one that is used often enough to merit its own method so that you don’t need to keep remembering the same crazy regular expression and failure message. You may want to mimic this to create your own reusable validations, such as phone numbers, postcodes etc.

Arguments:

value – {mixed} – value to be checked
paramsObj – {Object} – object containing parameters to be used for the validation

Parameters for paramsObj:

failureMessage (optional) – {String} – message to be used upon validation failure (DEFAULT: “Must be a valid email address!”)

Returns:

true if valid or throws a Validate.Error object containing the failure message

Example:

Validate.Email( 'live@validation.com', { failureMessage: "I am an overridden message!" } );

now (static function)

Validates a passed in value using the passed in validation function, and handles the validation error for you so it gives a nice true or false reply

Arguments:

validationFunction – {Function} – reference to the validation function to be used (ie Validate.Presence )
value – {mixed} – value to be checked
validationParamsObj – {Object} – object containing parameters to be used for the validation (optional depends upon the validation function)

Returns:

true if valid or false if not valid

Example:

Validate.now( Validate.Numericality, '2007', { is: 2007 } );

LiveValidation (class)

The LiveValidation class sets up a text, checkbox, or password input, or a textarea to allow its value to be validated in real-time based upon the validations you assign to it.

constructor

The constructor of the LiveValidation class to set up the form field as a LiveValidation object allows you to pass in any parameters you want to override.

Arguments:

element – {mixed} – either a dom element reference or the string id of the element to validate
optionsObj (optional) – {Object} – object containing options to override the LiveValidation defaults

Parameters for paramsObj:

validMessage (optional) – {String} – message to be used upon successful validation (DEFAULT: “Thankyou!”)
onValid (optional) – {Function} – function to execute when field passes validation (DEFAULT: function(){ this.insertMessage( this.createMessageSpan() ); this.addFieldClass(); } )
onInvalid (optional) – {Function} – function to execute when field fails validation (DEFAULT: function(){ this.insertMessage( this.createMessageSpan() ); this.addFieldClass(); })
insertAfterWhatNode (optional) – {mixed} – reference or id of node to have the message inserted after (DEFAULT: the field that is being validated)