cf_terraform tag reference
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
- 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.
- 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.
- 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
debugwithout assigning a value (i.e.
- 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:
SCOPEattribute has been set, this might be
ATTRIBUTES.UserNameor whatever) exist? If so, insert it in the field, otherwise
MyQuery.UserNameexist? If so, insert it in the field, otherwise
UserNamehave a default value? If so, insert it in the field, otherwise
- leave the field blank.
InputScopeListcan also used as a
cf_terrafieldattribute 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
inputscopelistalthough these are only likely to be useful for the
cf_terrafield InputScopeListattribute. 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
cfmoduleto call this custom tag, you will need to use
nameis a reseved
- 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
PassthroughFieldListattribute for page two.
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:
- Include the form file: the form will be displayed
- User enters data in the form and hits "Submit": the page is submitted back to itself
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).
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>
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:
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
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.
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