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.
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. Default values appear in grey italics.
<cf_terraform Action = "form_action" #CGI.script_name#?#.query_string# AlwaysDisplayForm = "Yes" or "No" No BuildFormTags = "Yes" or "No" Yes CustomValidationPath = "path" debug = "Yes" or "No" No DynamicLocale = "Yes" or "No" No EncType = "type" application/x-WWW-form-urlencoded flagLabels = "Yes" or "No" No flagRequiredFields = "Yes" or "No" Yes Focus = "Yes" or "No" No FocusField = "field_name" HideButtonsOnSubmit = "Yes" or "No" Yes Highlight = "highlight_attributes" style="color : red; font-weight : bold" HighlightLabelTagStart <span #Attributes.Highlight#> HighlightLabelTagEnd </span> inlineErrors = "Yes" or "No" No inlineErrorsTagStart <div style="color : red; font-weight : bold; font-size : xx-small"> inlineErrorsTagEnd </div> InputScopeList = "inputscopelist" labelTransformRegex = "reg_expression" (.*) labelTransformSubstring = "substring" \u\1: languageList = "language_list" name = "name" PassthroughFieldList = "passthroughfieldlist" qForms = "Yes" or "No" No qFormsPath = "web_path" /lib/ requiredFieldsMessage = "" <p>Fields marked with a #ESC#REQUIREDFLAG are required.</p> requiredFlag = "" <span style="color : #cc0000; font-size : 150%"> * </span> ResourcePath = "web_path" /terraformresources/ Scope = "scope" FORM SettingsPath = "path" terraform\settings.cfm smartDegrade = "Yes" or "No" Yes xhtml = "Yes" or "No" No XML = "_document_object" > ... </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. When the form is submitted, the same TerraForm form must catch the submission to validate it. Basically, the page must submit the form to itself. The default value for
#.path_info#?#.query_string#. This may not be appropriate for all sites. A fusebox site, for example, might use
Remember, you would normally set this in your
- 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. Create the form tags. If you are combining
cfformand TerraForm tags,
cfformwill insist on building the form tags. You can use this attribute to tell TerraForm not to build them.
- 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. CFMX only. Tell TerraForm to dynamically assign a locale based on the visitor's language and country. Within your form, you can use the variables
Request.TerraForm.DateHint. The first will give you the form's locale, which is the same as
GetLocale()within the form but might be different after the form's closing tag (within a form, the locale will be set dynamically, but after the form, the locale will revert to whatever it was originally). The second will give you an appropriate date mask for the current locale. The third will give you a human-readable hint for the date format required (such as "month / day / year" or "年 / 月 / 日". This can be useful to display on screen as a guide.
- Optional. The MIME type used to encode data sent by the POST method. The default value is
application/x--form-urlencoded, or if you are using an TerraForm file field, TerraForm will automatically adjust it to
multipart/form-data. You would only need to use this attribute if you were using a non-TerraForm file field (like
- Optional. Send focus to the form when the page loads. The field receiving focus is the first error field if one exists, or the field specified by
FocusFieldif provided, or else the first field.
- Optional. The name of the field to send focus to when the form loads. Used in conjunction with the
- Optional (only relevant if
FlagRequiredFieldsis true). Apply the flag to the field's label rather than to the field itself. TerraForm must be able to identify each field's label (the textual caption usually to the left of the field) in order to apply the flag. So you must use the
cf_terralabeltag for this to succeed. (new in 2.1)
- Optional. Flag any required fields with an asterisk or other marker (new in 2.1).
- Optional. Stop the visitor from pushing submit and reset buttons more than once by disabling them.
Highlight style="color : red; font-weight : bold"
- Optional. Attributes passed to highlight errors.
HighlightLabelTagStart <span #Attributes.Highlight#>
- Optional (only applicable if
cf_terralabeltags are used).
HighlightLabelTagEndcontain the opening and closing tags to be wrapped around the field's label if there is an error on the field. If used, the
labelforattribute (applied to the tag wrapped around the field label) is not required. See the
cf_terralabeltag reference for details. (new in 2.1)
- Optional (see
HighlightLabelTagStart). (new in 2.1)
- Optional. Display errors next to relevant fields rather than (or as well as) in a group at the top of the form. (new in 2.7).
inlineErrorsTagStart <div style="color : red; font-weight : bold; font-size : xx-small">
- Optional (only applicable if
inlineErrorsTagEndcontain the opening and closing tags to be wrapped around any error messages that are displayed inline (i.e. next to the relevant field). (new in 2.7)
- Optional (see
inlineErrorsTagStart). (new in 2.7)
- 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 document.
labelTransformRegex = "reg_expression" (.*)
labelTransformSubstring = "substring" \u\1:
- These attributes are used in combination to control how each field's
captionattribute is transformed into a label as rendered using
cf_terraLabel. The portion of the caption matching
labelTransformRegexis replaced with
labelTransformSubstring. The default behavior is to capitalize the first letter of the caption and to add a colon (:). More information about regular expression replacement strings.
- Optional. Comma-delimited list of prohibited words. You would normally set this once in your settings file, rather than provide it as an attribute. It is used in conjunction with the
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.
- Optional. If yes, TerraForm will include the qForms libraries and set the qForms required and description properties for each field for you.
- Required if
qForms="yes". The web path from your page to the qForms libraries.
requiredFieldsMessage <p>Fields marked with a #ESC#REQUIREDFLAG are required.</p>
- Optional. Message to display at the bottom (or elsewhere) of the form if
FlagRequiredFieldsis set, and the form contains one or more required fields.
requiredFlag <span style="color : #cc0000; font-size : 150%"> * </span>
- Optional. code to use to highlight required fields. Only applicable if
calendarthat require external resources will fail. You would generally set this in your TerraForm settings file.
- Optional. The primary input and output scope. Defaults to
FORM. You can change the default
defaults.cfmsettings file. For a Fusebox site, you would set Scope to
- Optional. The path to your settings file (usually
settings.cfmin the folder
terraform). This path is also used to locate any formats that are implemented as includes rather than UDFs (such as
soeditor), so the folder
format_includesshould be located in the same folder where
settings.cfmis located. The path may be absolute, relative, or based on a mapped path set up in the CF administrator. If the path is relative, then it will be evaluated in relation to the form template itself first, and if the settings file is not found, then in relation to the terraform.cfm custom tag.
NOTE You cannot set the default for this attribute in your settings file as the attribute is required in order to locate your settings file! TerraForm will however look for the variable
Request.TerraForm.SettingsPathand use that as the default, if it exists. (If you use this under CF5, remember to declare the structure first or it won't work — you may like to add code such as the following to your
<cfset Request.TerraForm = StructNew()> <cfset Request.TerraForm.SettingsPath="[myCustomPath]">
- Optional. Should TerraForm automatically degrade a field to a simpler format based on browser settings? This is mostly only used to test new formats or new browsers.
- Optional. By default, TerraForm will attempt to generate code. Set this flag to "yes" to tell TerraForm to tattempt to generate XHTML code. Note that Terraform's XHTML compliance is incomplete at this stage. Consider this an experimental feature and let us know if you spot any compliance failure.
- Optional. Request that TerraForm read the form field content from an file and return the valid result of the submission as an document by specifying the name of the document object (i.e. the result of
xmlParse()) with this attribute. For each field to be read from and written to the document, you must supply the
cf_terrfield xpathattribute. Note that this functionality does not as yet support fields that return multiple results satisfactorily. Evaluate it carefully before use.
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