cf_terraform tag reference

Description

Builds a regular HTML form using tags that provide a higher level of system intelligence, including flexible data validation, friendly error messages, prefilling with defaults and data from other sources.

Syntax (the short version)

Most TerraForm attributes rarely need to be used within the custom tag as you can set up your own defaults for each of them in your defaults.cfm settings file. Listed here are the basic attributes you are most likely to need regularly. Click for the complete list. Default values appear in grey italics.

<cf_terraform
  AlwaysDisplayForm = "Yes" or "No"              No 
  CustomValidationPath = "path"
  debug = "Yes" or "No"                          No
  InputScopeList = "inputscopelist"
  name = "name"
  PassthroughFieldList = "passthroughfieldlist"
>
  ...
</cf_terraform>

If you are using a shared server and cannot install TerraForm as a custom tag, see Different ways to call custom tags for alternative syntaxes (since name is a reserved cfmodule attribute, you can use formname instead).

Attributes

AlwaysDisplayForm No

Optional. Display the form whether it has passed validation or not. For example, if you had a search form, you would want it to remain visible even when displaying results. In this way it is easier for the user to refine their search.

CustomValidationPath

Optional. You can write custom validation code for your form and save it as a file. This file is included when the form has been submitted, after all the built-in validation has run. You may use an absolute path as in earlier versions (perhaps written as follows: CustomValidationPath="#GetDirectoryFromPath(GetCurrentTemplatePath())#val_myform.cfm") or you may use a relative path which is evaluated beginning at the location of the form itself (new in 2.1), or you may use a mapped path.

debug No

Optional. Output some debugging information, for use during development and debugging. Very useful for explaining how a given field has been prefilled with an unexpected value. For convenience you can simply use the flag debug without assigning a value (i.e. debug rather than debug=true).

InputScopeList

Optional. A list of secondary input "scopes". In its most common use, you would specify the name of a query or two here. If you had a field called UserName, and you specified InputScopeList = "MyQuery", then TerraForm would proceed through the following decision process:

1. Does FORM.UserName (if the SCOPE attribute has been set, this might be ATTRIBUTES.UserName or whatever) exist? If so, insert it in the field, otherwise
2. does MyQuery.UserName exist? If so, insert it in the field, otherwise
3. does UserName have a default value? If so, insert it in the field, otherwise
4. leave the field blank.

Note that InputScopeList can also used as a cf_terrafield attribute and that attribute takes priority over this attribute.

Note that you can now add a full variable name (new in 2.1) or a function name, or a CFC method name (new in 2.5) to inputscopelist although these are only likely to be useful for the cf_terrafield InputScopeList attribute. You can also now use the name of a parsed XML document.

name | formname

Required. The name for the form. This becomes the form name and is available to client-side scripting. If you are using cfmodule to call this custom tag, you will need to use formname instead of name (as name is a reseved cfmodule attribute).

PassthroughFieldList

Optional. A list of variables in the form's primary scope to pass through. If you had a multi-page form, you could list the names of the form fields on page one in the PassthroughFieldList attribute for page two.

Usage

cf_terraform are used just like form tags to enclose the content of a form. A closing tag must be used. Between the tags, place regular markup along with form field tags. Each field is specified using cf_terrafield tags or regular form tags.

The form and its fields are used both to construct the form and to provide validation for it. Here is the algorithm that your code should implement:

1. Include the form file: the form will be displayed
2. User enters data in the form and hits "Submit": the page is submitted back to itself
3. The form file is included again: this time the form is not automatically displayed but is used to validate the data entered
   • If the data is invalid then the form is redisplayed with error messages, and the fields prefilled with the invalid data
   • If the data is valid then the variable form.[formName] is set to "Valid" (where [formName] is the name of your form).
4. If form.[formName] is "Valid" then include the form handler and load the follow-up page.

See Recommended implementation for a code example.

Listing error messages and highlighting error fields

To allow output of validation errors, add a block at the desired point:

<messagesblock>
  <messages>
</messagesblock>

Between the messagesblock tags you may place any , and it will only be displayed if there are errors. The messages tag marks the point where the actual error messages will be inserted. For example, if your form is laid out with a table you might want something like this:

<messagesblock>
  <tr>
    <td colspan="2">
      <messages>
    </td>
  </tr>
</messagesblock>

To allow TerraForm to highlight error fields, use the labelfor attribute on any appropriate tag:

labelfor="list_of_field_names"

list_of_field_names may be one or more field names. TerraForm will replace this with the Highlight attributes (generally, a CSS style or class). For example:

<tr>
  <td labelfor="FirstName">
    First Name:
  </td>
  <td>
    <cf_terrafield name="FirstName"/terraform/>
  </td>
</tr>

If you are using TerraForm's ability to automatically highlight required fields, and you want to control the position of the explanatory message (something like "Fields marked with * are required"), insert the tag <requiredmessage/> at the point where you want the message to appear. If you leave the tag out, the message will appear at the bottom of your form. If you don't want the message to appear anywhere, pass the attribute requiredFieldsMessage="" to your cf_terraform tag.

If you want the flags to appear next to the field labels rather than next to the flags themselves, then you will need to use the cf_terralabel custom tag. See the tag reference.

Multiple forms

You can set up multiple forms on one page, but you should be sure each has a unique name. Also be aware that if the forms share field names, behaviour will be erratic, just like regular forms.

Refreshing without validation

Each form contains a hidden field with the same name as the form. This field records the status of the current form so that, once submitted, TerraForm knows how to handle it. After the closing </cf_terraform> tag, you may test this value. If it is "Valid", then the form has passed validation and the form handler may run.  

Occasionally, you may want to submit the form without validation being performed. For example, you may change the quantities on an order form and hit a "Recalculate" button to have the order total price updated. To turn off validation, change the value of the status field to "Refresh". You can do this using JavaScript.