cf_terrarule tag reference

Description

Used inside a TerraForm form to create a custom validation rule. A custom validation rule is a boolean expression (it can be evaluated as either true or false) that may consider the values or other attributes of one field, or several fields in combination. If the rule evaluates as false, then the rule fails validation and an error is generated.

Syntax

Default values appear in grey italics.

<cf_terrarule
  rule = "boolean_expression"
  error = "message"
  fieldlist = "fieldlist"
  applyiferrors = "Yes" or "No"                 No
/>

Attributes

rule

Required. A boolean expression. This expression is evaluated to test the form's conformance to the rule. If the expression evaluates as false, then the validation fails.

error

Required. The error message to display should validation fail.

fieldlist

Optional. The list of fields associated with this rule. This list is used to highlight the appropriate fields that should be amended by the user. TerraForm will read and use the fields found in the rule, so this attribute is usually not required.

applyiferrors false

Optional, boolean. Should the rule be applied if there are existing errors on the form?

Usage

<cf_terrarule/> tags should be placed at any point between the opening <cf_terraform> and the closing </cf_terraform> tags. If you are displaying inline errors (using the cf_terraform inlineErrors flag) then any error generated by your rule will appear at the location of the cf_terrarule tag.

Writing boolean expressions

A boolean expression is any expression that can be evaluated to true or false. Here are a few arbitrary examples:

true
	
isLeapYear(year(now()))
	
CGI.https is "on"
	
dayOfWeekAsString(dayOfWeek(now())) eq "Sunday"
	
session.age gte 18
	
getAuthUser() neq ""

Normally you will simply want to inspect the cleaned value of the field, and you can use the following shorthand notation to do this: {[fieldname]} — that is: wrap curly braces around the name of the field you want to evaluate.

However, you can insert the value of any TerraForm field attribute in your expression by addressing the data in full as follows: request.terraform.fields.[fieldname].[attribute] where [fieldname] is the name of your TerraForm field and [attribute] is the name of the attribute you want to inspect. To explore the available attributes, turn debugging on with the cf_terraform debug flag.

Note: do not use hash / pound symbols (#) inside your expression (if you do, the expression will be evaluated immediately the ColdFusion page is loaded). Also, remember to escape any quotation marks by doubling them.

If you have multiple fields of the same name on your form, then you cannot use the shorthand notation above to refer to those fields. In this case, request.terraform.fields.[fieldname] will describe an array, where each item represents a successive field. For example, request.terraform.fields.phone[3].value refers to the value of the third field in your form called "phone."

Examples

If you had a boolean field which made another field required when checked, you could write something like this:

<cf_terrarule
  rule = "{gift} imp len({giftCardMessage})"
  error = "As you have specified that this item is a gift, you must supply a gift card message."
  fieldlist = "gift,giftCardMessage"
/>

Or if the boolean field made several fields required:

<cf_terrarule
  rule = "{gift} imp (len({giftCardMessage}) and {giftWrapping})"
  error = "As you have specified that this item is a gift, you must supply a gift card message and choose wrapping paper."
  fieldlist = "gift,giftCardMessage,giftWrapping"
/>

---

If you had two dates where one must precede the other, you could write something like this:

<cf_terrarule
  rule = "dateCompare({arrivalDate},{departureDate}) eq 1"
  error = "Your arrival date seems to be after your departure date! Please check you have entered both dates correctly."
  fieldlist = "arrivaldate,departuredate"
/>

---

Here is a simple and common application of custom rule validation. Password and password confirmation (this is simply a demo, any information entered here will be discarded):

 

<table>

  <tr>
    <td labelfor="password1">
      Your new password
    </td>
    <td>
      <cf_terrafield
        name="password1"
        format="password"
        required="true"
        caption="your password"
        minlength="6"
        maxlength="12"
        size="12"
        pattern="[[:alnum:]]*"
        error="Your password must be letters or numbers only (no spaces), and between 6 and 12 characters long."
      />          
    </td>
  </tr>
  
  <tr>
    <td labelfor="password2">
      Please re-type it to confirm:
    </td>
    <td>
      <cf_terrafield
        name="password2"
        format="password"
        caption="your password confirmation"
        required="true"
        size="12"
      />            
    </td>
  </tr>     
   
</table>

<cf_terrarule
  rule="{password1} eq {password2}"
  error="Your passwords do not seem to match. Please re-enter."
  fieldlist="password1,password2"
/>

Your new password	*
Please re-type it to confirm:	*

Fields marked with  * are required.