How do I add custom validation to a form?

Datatype and built-in rules validation together provide the simplest, most convenient ways to ensure the validity of form data. Sometimes however these techniques are not sufficient. So TerraForm provides two further ways to validate your form data.

Custom rules

The first of these ways is custom rules evaluation. You embed rules as boolean expressions within your form, and these are evaluated as true or false. If false the form fails validation and an error is generated.

Custom rules can easily handle relationships amongst fields, that is: where the status of one field affects the data requirements of another field. Examples are where a field is required if and only if another given field is completed, or where two fields must contain the same value (a typing check on a password field for example).

See the cf_terrarule tag reference for details on how to implement this form of validation.

Custom templates

When all else fails, you can provide an external ColdFusion template containing your validation code. This template might connect to a database or a web service to verify a credit card number or a user login name. All you need to do is return an error in the prescribed manner, or not. TerraForm will take care of presenting that error along with any other form errors to the user.

Create your custom validation template as a new .cfm file (it is commonly placed in the same folder as the form). Create your validation code something like this:

 

<cfif NOT Listlen(ErrorFieldList)>
  <!--- This example inspects ErrorFieldList to see if there are any errors yet. If so, it doesn't bother running. --->

  <cfif [some condition fails] > 
    <!--- This is our custom validation. It might be the result of a calculation, a query, web service or COM object, for example. --->

    <cfset ErrorFieldList = ListAppend(ErrorFieldList, "[some field]")>
      <!--- Add all the fields relating to this error to the ErrorFieldList so that they may be appropriately highlighted --->
 
    <cfset ErrorMessageList = ListAppend(ErrorMessageList, "[some error message]", RS)>
      <!--- add the error message to the list of error messages. Note that the list is NOT delimited with commas in order to allow you to insert commas in your messages. Instead it is delimited with the  character - chr(30). --->
 
  </cfif>		

</cfif>

Note that your custom template is actually called inside the cf_terraform tag — you are extending the functionality of TerraForm. This means that if you want to access local variables for your page you will need to use the caller. prefix. For example, if you want to read a value from a query record set on your page, it might be caller.myQuery.myColumn. If you are using Fusebox, your attributes-scoped variables will be located in caller.attributes.

Add the following attribute to your cf_terraform tag (you can use an absolute, mapped, or relative path here):

  customvalidationpath="[my validation template].cfm"

That's all you need to do! A sample is available for download in the Code Gallery.