ValidateThis

A ColdFusion Validation Framework

Supported Validation Types

ValidateThis comes bundled with a number of validation types, and you can also add your own validation types. This page describes all of the built-in validation types. Default Failure Messages Each validation type generates a default message when it fails, which generally includes the name of the property for which the failure occurred, as well as the values of the parameters defined for the rule. The default failure message for each rule type is documented below. Note that by default each failure message is prepended with the word “The ”, followed by the property description, for example “The Email Address is required.” You can change the text that is prepended to the default validation failure message using the defaultFailureMessagePrefix key of the ValidateThisConfig Struct. For example, if you set defaultFailureMessagePrefix=“”, the example message above would be generated as “Email Address is required”. Built-In Validation Types Boolean The Boolean type ensures that the contents of a property is a valid ColdFusion boolean value. Parameters: None Default Failure Message: The propertyDescription must be a valid boolean. Metadata Example:

CollectionSize The CollectionSize type ensures that the contents of a property is of a specific size. On the server this can be a list, struct or array. On the client it can be a multi-select form field. Parameters: min (optional) - the minimum size of the collection. Defaults to 1. max (optional) - the maximum size of the collection. Defaults to min. Default Failure Message: The propertyDescription size is not equal or greater than min. Or The propertyDescription size is not between min and max. Metadata Examples: This will ensure that the contents of the property is a collection with at least 3 elements. This will ensure that the contents of the property is a collection with between 1 and 3 elements.

Custom The Custom type allows you to create a validation which uses any arbitrary CFML code. You do so by specifying the name of a method in your object that will perform the validation. Parameters: methodName - the name of the method in your object that determines whether the validation passes or not remoteURL (optional) - a url that can be called via AJAX which will run code to determine whether the validation passes or not, and returns a message to the client Default Failure Message: A custom validator failed. Note that this should be overridden using either the failureMessage attribute of the rule or via the data returned from the method called, although the former will not return a meaningful message for client-side validations. Metadata Example: The method defined in your object, which would be checkDuplicateNickname in the above example, should return either a boolean or a structure with at least one key: isSuccess, which should be set to true if the validation passed and to false if the validation failed. The structure can also contain a failureMessage key, which would contain the message to display upon failure. The process that is reached via the remoteURL parameter must return a simple text string, which should which should be true if the validation passed and false if the validation failed. More information on using the Custom validation type can be found on the Using the Custom Validation Type page.

Date The Date type ensures that the contents of a property is a valid date value. Parameters: None Default Failure Message: The propertyDescription must be a valid date. Metadata Example:

DateRange The DateRange type ensures that the contents of a property is a valid date that falls between two dates. Parameters: from - the start date of the range until - the end date of the range Default Failure Message: The propertyDescription must be a date between from and until. Metadata Example: This will ensure that the property has a date between January 1, 2010 and December 31, 2010.

DoesNotContainOtherProperties The DoesNotContainOtherProperties type ensures that the contents of a property does not contain values found in other properties. This can be used, for example, to ensure that a password property doesn’t include the user’s first or last names. Parameters: propertyNames - the names of the other properties delim (optional) - the delimiter used in the list of other properties specified in the propertyNames parameter. Defaults to a comma. Default Failure Message: The propertyDescription must not contain the values of properties named: propertyNames. Metadata Example: This will ensure that the property does not contain the values of either the firstName or lastName properties.

Email The Email type ensures that the contents of a property is a valid email address. Parameters: None Default Failure Message: The propertyDescription must be a valid email address. Metadata Example: Note that the test on the client-side uses the jQuery Validation plugin’s built-in email validator and the test on the server-side uses ColdFusion’s isValid(), so the results are not always identical. It is possible to have an email address that passes on the client and not on the server.

EqualTo The EqualTo type ensures that the contents of one property is the same as the contents of another property. Parameters: comparePropertyName - the name of another property comparePropertyDesc (optional) - the description of the other property Default Failure Message: The propertyDescription must be the same as the comparePropertyDesc. Metadata Example: This will ensure that the contents of the property is the same as the contents of the anotherProperty property.

False The False type ensures that the contents of a property is a value that can be interpreted as false. This includes the values false,no and 0. Parameters: None Default Failure Message: The propertyDescription must be a false boolean. Metadata Example:

FutureDate The FutureDate type ensures that the contents of a property is a valid date that falls after a particular date. Parameters: after (optional) - defaults to the current date Default Failure Message: The propertyDescription must be a date in the future. Note that if an after parameter is specified the message will be appended with: The date entered must come after after. Metadata Examples: This will ensure that the property has a date in the future. This will ensure that the property has a date after January 1, 2010.

InList The InList type ensures that the contents of a property is one of the values specified in a list. Parameters: list - the list of values to be searched delim (optional) - the delimiter used in the list of values to be searched. Defaults to a comma. Default Failure Message: The propertyDescription was not found in the list: list. Metadata Example: This will ensure that the property has a value of either John, Paul or George.

Integer The Integer type ensures that the contents of a property is a valid integer value. Parameters: None Default Failure Message: The propertyDescription must be an integer. Metadata Example:

IsValidObject The IsValidObject type is used to validate properties which contain other objects. Parameters: objectType (optional) - the type of object contained in the property. This corresponds to what you’d normally pass into the objectType argument of the validate method when manually validating an object. context (optional) - the context to be used when validating the object contained in the property. Defaults to *, which is all or no contexts. Default Failure Message: The propertyDescription is invalid: messages generated while validating the object. Metadata Example: This will cause the object that is stored inside the property to be validated by ValidateThis as a user object and using the register context.

Max The Max type ensures that the contents of a property contains a maximum value. Parameters: max - a number Default Failure Message: The propertyDescription must be no more than max. Metadata Example: This will ensure that the property has a value of 5 or less.

MaxLength The MaxLength type ensures that the length of the contents of a property is no more than a certain number of characters. Parameters: maxLength - a number Default Failure Message: The propertyDescription must be no more than maxLength characters long. Metadata Example: This will ensure that the contents of the property is no more than 5 characters long.

Min The Min type ensures that the contents of a property contains a minimum value. Parameters: min - a number Default Failure Message: The propertyDescription must be at least min. Metadata Example: This will ensure that the property has a value of 5 or more.

MinLength The MinLength type ensures that the length of the contents of a property is at least a certain number of characters. Parameters: minLength - a number Default Failure Message: The propertyDescription must be at least minLength characters long. Metadata Example: This will ensure that the contents of the property is at least 5 characters long.

MinPatternsMatch The MinPatternsMatch type ensures that the contents of a property matches a minimum number of patterns. This can be used, for example, to ensure that a password property conforms to certain standards. Parameters: minMatches - the minimum number of patterns that the value must match pattern_x - where x is the name of a pattern and the value of the parameter is a regex to be evaluated Default Failure Message: numberOfPatternsMatched patterns were matched but minMatches were required. Metadata Example: This will ensure that the contents of the property conforms to at least 3 of the 4 regex patterns listed.

NoHTML The NoHTML type ensures that the contents of a property does not contain HTML. Parameters: None Default Failure Message: The propertyDescription cannot contain HTML tags. Metadata Example:

NotInList The NotInList type ensures that the contents of a property is not one of the values specified in a list. Parameters: list - the list of values to be searched delim (optional) - the delimiter used in the list of values to be searched. Defaults to a comma. Default Failure Message: The propertyDescription was found in the list: list. Metadata Example: This will ensure that the property does not have a value of either John, Paul or George.

Numeric The Numeric type ensures that the contents of a property is a valid numeric value. Parameters: None Default Failure Message: The propertyDescription must be a number. Metadata Example:

PastDate The PastDate type ensures that the contents of a property is a valid date that falls before a particular date. Parameters: before (optional) - defaults to the current date Default Failure Message: The propertyDescription must be a date in the past. Note that if an before parameter is specified the message will be appended with: The date entered must come before before. Metadata Examples: This will ensure that the property has a date in the past. This will ensure that the property has a date before December 31, 2010.

Range The Range type ensures that the contents of a property contains a value between two numbers. Parameters: min - a number max - a number Default Failure Message: The propertyDescription must be between min and max. Metadata Example: This will ensure that the property has a value between 5 and 10.

RangeLength The RangeLength type ensures that the length of the contents of a property is between two numbers. Parameters: minLength - a number maxLength - a number Default Failure Message: The propertyDescription must be between minLength and maxLength characters long. Metadata Example: This will ensure that the contents of the property is between 5 and 10 characters long.

Regex The Regex type ensures that the contents of a property conforms to a regular expression. Parameters: regex - a regular expression serverRegex (optional) - a regular expression Default Failure Message: The propertyDescription must match the specified pattern. Metadata Example: This will ensure that the contents of the property matches the expression. Note that you can provide a CFML-only regex using the serverRegex parameter, otherwise the same regex will be used on the client and the server.

Required The Required type ensures that the contents of a property is not empty. Parameters: None Default Failure Message: The propertyDescription is required. Metadata Example:

Time The Time type ensures that the contents of a property is a valid time value in the format 00:00. This includes values between 00:00 and 23:59. Parameters: None Default Failure Message: The propertyDescription must be a must be a valid time, between 00:00 and 23:59. Metadata Example:

True The True type ensures that the contents of a property is a value that can be interpreted as true. This includes the values true,yes and any number other than 0. Parameters: None Default Failure Message: The propertyDescription must be a true boolean. Metadata Example:

URL The URL type ensures that the contents of a property is a valid (properly formed) URL. Parameters: None Default Failure Message: The propertyDescription must be a valid URL. Metadata Example:

Server Only Validation Types Expression The Expression type ensures that a cfml expression evaluates to true. Parameters: expression - the cfml expression to evaluate on the object. Default Failure Message: [NONE] Metadata Example:

Updated: