Contents

Validation Types Supported By ValidateThis

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:

<rule type="boolean" />


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:

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:

<rule type="collectionSize">
	<param name="min" value="3" />
</rule>

This will ensure that the contents of the property is a collection with at least 3 elements.

<rule type="collectionSize">
	<param name="min" value="1" />
	<param name="max" value="3" />
</rule>

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:

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:

<rule type="custom">
	<param name="methodName" value="checkDuplicateNickname" />
	<param name="remoteURL" value="checkDuplicateNickname.cfm" />
</rule>

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:

<rule type="date" />


DateRange

The DateRange type ensures that the contents of a property is a valid date that falls between two dates.

Parameters:

Default Failure Message: The propertyDescription must be a date between from and until.

Metadata Example:

<rule type="date">
	<param name="from" value="2010-01-01" />
	<param name="until" value="2010-12-31" />
</rule>

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:

Default Failure Message: The propertyDescription must not contain the values of properties named: propertyNames.

Metadata Example:

<rule type="doesNotContainOtherProperties">
	<param name="propertyNames" value="firstName,lastName" />
</rule>

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:

<rule type="email" />

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:

Default Failure Message: The propertyDescription must be the same as the comparePropertyDesc.

Metadata Example:

<rule type="equalTo">
	<param name="comparePropertyName" value="anotherProperty" />
</rule>

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:

<rule type="false" />


FutureDate

The FutureDate type ensures that the contents of a property is a valid date that falls after a particular date.

Parameters:

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:

<rule type="futureDate" />

This will ensure that the property has a date in the future.

<rule type="futureDate">
	<param name="after" value="2010-01-01" />
</rule>

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:

Default Failure Message: The propertyDescription was not found in the list: list.

Metadata Example:

<rule type="inList">
	<param name="list" value="John,Paul,George" />
</rule>

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:

<rule type="integer" />


IsValidObject

The IsValidObject type is used to validate properties which contain other objects.

Parameters:

Default Failure Message: The propertyDescription is invalid: messages generated while validating the object.

Metadata Example:

<rule type="isValidObject">
	<param name="objectType" value="user" />
	<param name="context" value="register" />
</rule>

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:

Default Failure Message: The propertyDescription must be no more than max.

Metadata Example:

<rule type="max">
	<param name="max" value="5" />
</rule>

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:

Default Failure Message: The propertyDescription must be no more than maxLength characters long.

Metadata Example:

<rule type="maxLength">
	<param name="maxLength" value="5" />
</rule>

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:

Default Failure Message: The propertyDescription must be at least min.

Metadata Example:

<rule type="min">
	<param name="min" value="5" />
</rule>

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:

Default Failure Message: The propertyDescription must be at least minLength characters long.

Metadata Example:

<rule type="minLength">
	<param name="minLength" value="5" />
</rule>

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:

Default Failure Message: numberOfPatternsMatched patterns were matched but minMatches were required.

Metadata Example:

<rule type="MinPatternsMatch">
	<param name="minMatches" value="3" />
	<param name="pattern_lowerCaseLetter" value="[a-z]" />
	<param name="pattern_upperCaseLetter" value="[A-Z]" />
	<param name="pattern_digit" value="[\d]" />
	<param name="pattern_punct" value="[[:punct:]]" />
</rule>

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:

<rule type="noHTML" />


NotInList

The NotInList type ensures that the contents of a property is not one of the values specified in a list.

Parameters:

Default Failure Message: The propertyDescription was found in the list: list.

Metadata Example:

<rule type="notInList">
	<param name="list" value="John,Paul,George" />
</rule>

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:

<rule type="numeric" />


PastDate

The PastDate type ensures that the contents of a property is a valid date that falls before a particular date.

Parameters:

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:

<rule type="pastDate" />

This will ensure that the property has a date in the past.

<rule type="pastDate">
	<param name="before" value="2010-12-31" />
</rule>

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:

Default Failure Message: The propertyDescription must be between min and max.

Metadata Example:

<rule type="range">
	<param name="min" value="5" />
	<param name="max" value="10" />
</rule>

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:

Default Failure Message: The propertyDescription must be between minLength and maxLength characters long.

Metadata Example:

<rule type="rangeLength">
	<param name="minLength" value="5" />
	<param name="maxLength" value="10" />
</rule>

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:

Default Failure Message: The propertyDescription must match the specified pattern.

Metadata Example:

<rule type="regex">
	<param name="regex" value="^(Dr|Prof|Mr|Mrs|Ms|Miss)(\.)?$" />
</rule>

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:

<rule type="required" />


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:

<rule type="time" />


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:

<rule type="true" />


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:

<rule type="url" />



Server Only Validation Types

Expression

The Expression type ensures that a cfml expression evaluates to true.

Parameters:

Default Failure Message: [NONE]

Metadata Example:

<rule type="expression" failureMessage="Foo is not equal to Bar">
	<param name="expression" value="getFoo() eq getBar()" />
</rule>