Creating_New_Validation_Types

last edited byusericonBob on 07-Jul-2010

Contents

Creating New Validation Types

ValidateThis ships with a number of built in validation types, the complete list can be found in the Validation Types Supported By ValidateThis section.

In order to add a validation type to the framework, you'll need to create two ColdFusion components (cfcs), one for the server-side validations and one for the client-side validations. We'll walk through an example of adding a simple validation type. Let's add a validation type called bigNumber, which will check that a property contains a number that is al least 1,000. Of course, we could just use the built-in min validation type for this, but that requires us to provide a parameter (min) each time we want to use the rule. Let's assume that for some reason, we need to use this rule that states that the value of the property must be at least 1,000 over and over again in our model, so perhaps it makes sense to create a new validation type for it.

Creating the Server-Side Validation

Each validation type has a corresponding Server Rule Validator (SRV) which is responsible for performing the test to determine whether a validation passes or fails. The built-in validations have their SRVs stored in the /ValidateThis/server/ folder, so a great place to start is to find an existing SRV that is similar to the one you want to create and then use that as a basis.

As mentioned above, our validation type will not require a parameter, so let's find one that is similar. The SRV for the numeric validation type is a good candidate, so we'll open up the file called ServerRuleValidator_Numeric.cfc. Because we want our new validation type to be called bigNumber, we'll save a copy of this file as ServerRuleValidator_BigNumber.cfc. Here's what our file will look like before we change anything:

<cfcomponent output="false" extends="AbstractServerRuleValidator" hint="I am responsible for performing the Numeric validation.">

	<cffunction name="validate" returntype="any" access="public" output="false" hint="I perform the validation returning info in the validation object.">
		<cfargument name="valObject" type="any" required="yes" hint="The validation object created by the business object being validated." />

		<cfif shouldTest(arguments.valObject) AND NOT IsValid("Numeric",arguments.valObject.getObjectValue())>
			<cfset fail(arguments.valObject,"The #arguments.valObject.getPropertyDesc()# must be a number.") />
		</cfif>
	</cffunction>
	
</cfcomponent>

There are a number of things to note here:

Let's go ahead and change the above code to implement out bigNumber validation type:

<cfcomponent output="false" extends="ValidateThis.server.AbstractServerRuleValidator" hint="I am responsible for performing the bigNumber validation.">

	<cffunction name="validate" returntype="any" access="public" output="false" hint="I perform the validation returning info in the validation object.">
		<cfargument name="valObject" type="any" required="yes" hint="The validation object created by the business object being validated." />

		<cfif shouldTest(arguments.valObject) AND val(arguments.valObject.getObjectValue()) LT 1000>
			<cfset fail(arguments.valObject,"The #arguments.valObject.getPropertyDesc()# must be a number greater than 999.") />
		</cfif>
	</cffunction>
	
</cfcomponent>

Let's review the changes:

We simply save this file as ServerRuleValidator_BigNumber.cfc and our server-side validation is in place.

Creating the Client-Side Validation

Each validation type has a corresponding Client Rule Scripter (CRS) which is responsible for generating the JavaScript required for the validation. The built-in validations have their CRSs stored in the /ValidateThis/client/{JSImplementation}/ folder, where {JSImplementation} is the name of the JavaScript implementation. We'll therefore look in /ValidateThis/client/jQuery/ to find a CRS on which to base our new validation type.

Creating these CRSs is quite a bit trickier than the SRVs because of the way the jQuery implementation code has been designed. It has been refactored to eliminate code duplication, but that makes it more difficult to follow. We'll look at creating a CRS to support this new bigNumber validation type, basing it on the 'ClientRuleScripter_Numeric.cfc, but bear in mind that you may have to do some more digging for different types of client-side validations. Support is always available via the ValidateThis Google Group.

As before, let's open up ClientRuleScripter_Numeric.cfc and we'll save a copy of it as ClientRuleScripter_BigNumber.cfc. Here's what our file will look like before we change anything:

<cfcomponent output="false" extends="AbstractClientRuleScripter" hint="I am responsible for generating JS code for the numeric validation.">

	<cffunction name="getRuleDef" returntype="any" access="private" output="false" hint="I return just the rule definition which is required for the generateAddRule method.">
		<cfargument name="validation" type="any" required="yes" hint="The validation struct that describes the validation." />

		<cfreturn "number: true" />
		
	</cffunction>

</cfcomponent>

As before, there are a number of things to note here:

Let's go ahead and change the above code to implement out bigNumber validation type:

<cfcomponent output="false" extends="ValidateThis.client.jQuery.AbstractClientRuleScripter" hint="I am responsible for generating JS code for the bigNumber validation.">

	<cffunction name="getRuleDef" returntype="any" access="private" output="false" hint="I return just the rule definition which is required for the generateAddRule method.">
		<cfargument name="validation" type="any" required="yes" hint="The validation struct that describes the validation." />

		<cfreturn "min: 1000" />
		
	</cffunction>

</cfcomponent>

Let's review the changes:

We simply save this file as ClientRuleScripter_BigNumber.cfc and our client-side validation is in place.

Adding the New Validation Type to the Framework

With an SRV and CRS in place, we should now be able to use our new validation type, but how will the framework know about it? The simplest way to do that is to place the files in the folders the the framework uses. So if you place your SRV in /ValidateThis/server/ and your CRS in /ValidateThis/client/jQuery/ the framework will pick them up automatically and you'll be good to go. The downside with this approach is that you've now put something in a folder that is part of the official framework, and if you were to download a new version of the framework and replace your entire installation with it you would lose your new validation type. For this reason it is possible to place your SRVs and CRSs in a folder that is outside of the framework.

You tell VT where to look for your SRVs and CRSs using two ValidateThis Config options: extraRuleValidatorComponentPaths and extraClientScriptWriterComponentPaths.

Contributing New Validation Types to the Framework

If you have created a new validation type that you think may be useful to others, please let us know. We might just add it to the set of built-in validation types that ship with the framework.

 
Download in other Formats:
markup Markup | pdf PDF | swf SWF | html HTML | word Word

comments Comments (0)