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

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 formname instead).

Attributes

Action #.script_name#?#.query_string#

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 Action is #.path_info#?#.query_string#. This may not be appropriate for all sites. A fusebox site, for example, might use
#request.self#?fuseaction=#Caller.Attributes.FuseAction#
Remember, you would normally set this in your defaults.cfm settings file.

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.

BuildFormTags Yes

Optional. Create the form tags. If you are combining cfform and TerraForm tags, cfform will insist on building the form tags. You can use this attribute to tell TerraForm not to build them.

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).

DynamicLocale No

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.Locale, Request.TerraForm.DateMask, and 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.

EncType application/x--form-urlencoded

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 <input type="file">).

Focus No

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 FocusField if provided, or else the first field.

FocusField

Optional. The name of the field to send focus to when the form loads. Used in conjunction with the Focus attribute.

FlagLabels No

Optional (only relevant if FlagRequiredFields is 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_terralabel tag for this to succeed. (new in 2.1)

FlagRequiredFields Yes

Optional. Flag any required fields with an asterisk or other marker (new in 2.1).

HideButtonsOnSubmit Yes

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_terralabel tags are used). HighlightLabelTagStart and HighlightLabelTagEnd contain the opening and closing tags to be wrapped around the field's label if there is an error on the field. If used, the labelfor attribute (applied to the tag wrapped around the field label) is not required. See the cf_terralabel tag reference for details. (new in 2.1)

HighlightLabelTagEnd </span>

Optional (see HighlightLabelTagStart). (new in 2.1)

inlineErrors No

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 inlineErrors is true). inlineErrorsTagStart and inlineErrorsTagEnd contain 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)

inlineErrorsTagEnd </div>

Optional (see inlineErrorsTagStart). (new in 2.7)

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 document.

labelTransformRegex = "reg_expression" (.*)
labelTransformSubstring = "substring" \u\1:

These attributes are used in combination to control how each field's caption attribute is transformed into a label as rendered using cf_terraLabel. The portion of the caption matching labelTransformRegex is 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.

LanguageList

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 cf_terrafield attribute: languagefilter .

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.

qForms No

Optional. If yes, TerraForm will include the qForms libraries and set the qForms required and description properties for each field for you.

qFormsPath /lib/

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 FlagRequiredFields is 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 FlagRequiredFields is set.

ResourcePath /TerraFormResources/

Optional. The Web path to your resources folder. The resources folder should be included under the web root of each web site, and contains external files formats may need such as images and JavaScript. Without this attribute, formats such as calendar that require external resources will fail. You would generally set this in your TerraForm settings file.

Scope FORM

Optional. The primary input and output scope. Defaults to FORM. You can change the default Scope using your defaults.cfm settings file. For a Fusebox site, you would set Scope to Attributes.

SettingsPath terraform\settings.cfm

Optional. The path to your settings file (usually settings.cfm in the folder terraform). This path is also used to locate any formats that are implemented as includes rather than UDFs (such as calendar and soeditor), so the folder format_includes should be located in the same folder where settings.cfm is 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.SettingsPath and 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 Application.cfm template:

<cfset Request.TerraForm = StructNew()>
<cfset Request.TerraForm.SettingsPath="[myCustomPath]">

smartDegrade Yes

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.

XHTML No

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 xpath attribute. Note that this functionality does not as yet support fields that return multiple results satisfactorily. Evaluate it carefully before use.

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.