cf_terrafield tag reference

Description

Used inside a TerraForm form to build an individual form field.

Syntax

Default values appear in grey italics (see the note on default values below).

 

<cf_terrafield
  caption = "caption"                            #FieldName#
  caption_[identifier] = "caption"
  datatype = "datatype"                          default
  delimiters = "delimiters"                      comma (,) or if query defined then RS (Chr(30))
  displaycolumn = "display_column"               #ValueColumn#
  displaylist = "display_list"                   #ValueList#
  EnforceValueList = "yes" or "no"               yes
  error = "custom_error_message"
  format = "format"                              text
  InputScopeList = "inputscopelist"
  jsMask = "javascript_regex"
  LanguageFilter = "yes" or "no"                 no
  max = "max"
  maxlength = "max_length"
  min = "min"
  minlength = "min_length"
  multiple = "Yes" or "No"                       No
  name | fieldname = "name"
  NoProcessing = "yes" or "No"                   No
  pattern = "validation_regex"
  preset = "preset"
  prompt = "prompt"
  promptvalue="value"
  query = "queryname"
  required = "Yes" or  "No"                      No
  value = "value"
  valuecolumn = "value_column"
  valuelist = "value_list"
  xpath = "xpath"
>
  default_value
</cf_terrafield>

or (specifying default as an attribute):

  <cf_terrafield
    ...
    default = "default_value"
  />

Attributes

Caption #FieldName#

Optional. A human-friendly name for the form field, for example "your date of birth". This will be used in error messages. Although the default caption is the value of the field's name attribute, it is an important and easy usability enhancement to set this attribute thoughtfully.

Advanced tip: Wrap the beginning of the caption in parentheses if you want it to appear in error messages only. For example, caption="(your )name" would result in the field label "Name:", but the field would be described as "your name" in any error messages.

Advanced tip: You may also provide alternative captions so that a single form may be reused for different languages. Write the attribute as caption_ followed by either a Java locale (e.g. en_NZ), a language code (e.g. en), a country code (e.g. NZ), or a language (e.g. English). TerraForm will choose the appropriate caption in that order. For example, your field may have the attributes: caption="your name" caption_de="(Ihr )Name" .

Datatype default

Optional. The type of data handled by this field. Data is pre-processed as it enters the form, cleaned prior to validation, validated, then post-processed after successful validation according to its datatype.

Default

Optional. Default value to insert when the form is new. If the form has been submitted and has generated errors, the default value will be ignored even if a field is blank.

Delimiters comma (,) or if query defined then (Chr(30))

Optional. Only relevant in some cases, such as if Valuelist and DisplayList attributes are set. The delimiter for the two lists.

EnforceValueList yes

Optional. If ValueList or ValueColumn are defined, verify that submitted value is a member of the list. Generally, the Format will physically stop unauthorised options being entered (think of a select box). But it would still be possible to abuse the form handler by passing other values. In a few cases you may not want to enforce the value list. For example, you may have a combo box format where users can either select from the list or enter a new value. In this case, ideally the format would have a preset that set EnforceValueList="no".

Error

Optional. Error message to display whatever the problem is with this field, to be used in place of TerraForm's built-in errors. The error needs to be written to be appropriate to any problem the field might have. This attribute is a stopgap solution and should only rarely be used - i.e. it's generally not the right solution. Remember that you can customise TerraForm's error messages using the errors.cfm settings file.

format text

Optional. The interface for this field. Remember that the datatype and the interface are independent and set separately. The default value is TEXT, although many datatypes have a preset format — a sensible format that will be used as the default.

InputScopeList

You can set the input scopes on a field-by-field basis. When building the new form, TerraForm will look for a value first in the form's Scope, next in the field's InputScopeList, then in the form's InputScopeList, and finally (if it's a new form) in the field's default.

Note that you can now add a full variable name to inputscopelist (new in 2.1). This is useful where you desire your field's name to differ from the name of the variable (i.e. your query column name or your structure key) in your input scope. Generally, it is easier to match your field name and your variable name by using such techniques as column aliases in SQL. However, sometimes this is not possible. You can also now supply a function name, or a CFC method name (new in 2.5). Finally, you can supply the name of an XML document object in combination with the XPath attribute, although this will usually be more useful supplied in the cf_terraform inputscopelist attribute (new in 2.5).

jsMask

Optional. JavaScript regular expression to use as a filter for keyboard input. This attribute is not supported by all field formats, nor by all browsers. For this reason, it should not be used as a way to validate input data. The regex should match a single key (one character). For example: /[-+0-9]/ will allow any digit or a + or - symbol. To specify that you regex should ignore case, add the i suffix. For example: /[0-9A-F]/i will allow a hexadecimal number where the letters are upper or lower case.

LanguageFilter no

Optional. Turn language filtering on for this field. You would generally set this as a preset for certain datatypes or formats in your presets.cfm settings file:

Preset("Format_TextArea", "LanguageFilter", yes);

or

Preset("DataType_String", "LanguageFilter", yes);

Used in conjunction with the cf_terraform attribute: LanguageList.

Maxlength, MinLength

Optional. Specify the minimum or maximum length for the character string. For a password field, for example, you might specify: minlength="8" maxlength="12"
If you want an exact length, set both minlength and maxlength to the same value.

Min, Max

Optional. Validation by checking the entered value fits within the specified range. The range may be an upper and lower bound, just one or the other, or one exact value, written by specifying the same value for both max and min. Ranges function in different ways for different datatypes. For numeric datatypes, the upper and lower values are the maximum and minimum numeric values that may be entered. For character string datatypes however, the bounds function as they might in an encyclopedia or phone book. The string is truncated to the length of Max before testing. So if I specified a Surname field with max="S" then the surname "Smith" would be truncated to "S", and would validate. If I specified max="Sm", Smith would still validate. But if I specified max="Sma", Smith would no longer validate, although "Smayle" would validate. Ranges may also be specified for dates and times.

Multiple No

Optional. Does this field collect multiple values? This attribute is familiar from regular HTML select fields. Generally applied automatically by formats such as checkboxes.

name | fieldname

Required. The name for the form field. This becomes the field name and is available to client-side scripting. If you are using cfmodule to call this custom tag, you will need to use fieldname instead of name.

NoProcessing No

Stop TerraForm from tampering with this field's value. This obscure attribute is used by formats such as file.

Pattern

Optional. A powerful form of validation using a regular expression. The value entered must exactly match the regular expression. Matching is case-insensitive. Here are some examples:

• [[:alnum:]]{6,12}
  An alphanumeric string containing between 6 and 12 characters and no spaces or other punctuation. This might be used when choosing a username.
• #[[:digit:]a-f]{6}
  An colour triplet, like #3366cc. Note that when inserting this regex into your cf_terrafield tag, you would need to escape the hash by doubling it: pattern="##[[:digit:]a-f]{6}".
• [01]*
  A binary number.
• [[:digit:]A-F]*
  A hexadecimal number.
• [[:digit:]]{1,3}.[[:digit:]]{1,3}.[[:digit:]]{1,3}.[[:digit:]]{1,3}
  An IP address.

Preset

Optional. Presets are sets of attributes and their default values. You can specify a preset for a field in order to set up many attributes at once. TerraForm comes with some presets ready for use. For example, set preset="country" for a country select box.

Prompt, PromptValue

Optional. Ignored by many formats, but used on select, text and textarea. A prompt as the first option, such as "Click here" or "Select your age", or as a message that disappears when the field receives focus. PromptValue is an optional attribute assigning a value to this option, defaults to "".

Query, ValueColumn, DisplayColumn

Optional. Builds Valuelist and DisplayList automatically from the columns of an already executed query. Query is the name of the query, for example "Countries". ValueColumn and DisplayColumn are the names of columns, for example "CountryID" and "CountryName". ValueColumn is required if Query is specified. DisplayColumn defaults to ValueColumn.

Required No

Optional. Insist that this field must be filled in? This is meaningless for some fields, for example, a boolean checkbox will always contain either "True" or "False" and will never be empty.

value

Optional. Warning: this attribute's purpose is frequently misinterpreted. If you are beginning with TerraForm don't use it! TerraForm assigns the value for a field dynamically, based on defaults and input scopes. Setting value will override all of these, and force a value into the field. This attribute might be useful for buttons or for certain rare circumstances.

Valuelist, DisplayList

Optional. Valuelist is a list of possible values for this field. DisplayList is a corresponding list of human-friendly captions for those values. So if the data was countries, Valuelist might be numeric country IDs, while Displaylist was the names of the countries. Used to provide the options for select, checkbox and similar format fields. Also used for validation purposes. I could apply it to a text format field, for example, and I might receive an error: "I don't recognise that country." DisplayList defaults to ValueList.

XPath

Optional. The XPath to the value of this field in a supplied document object. Only applicable if supplying the name of an document object in either the inputscopelist attribute or the cf_terraform attribute.

Usage

cf_terrafield tags should be placed between the opening and closing cf_terraform tags. Each cf_terrafield tag represents one form field. All cf_terrafield must be closed. Content enclosed by cf_terrafield tags is taken to be the field's default value. Where this is not required, you may use the -style empty-element tag notation:

<cf_terrafield name = "MyForm" ... />

A note on default values

While some of these attributes have default values, individual field datatypes and formats may have their own default values for these attributes which override the built-in defaults. For example, you might want minlength="6" maxlength="12" to be the default for all password formats. A datatype may also have a default format, and vice versa. Occasionally, the format and the datatype may both have different defaults for some attribute. In this case the datatype's default has priority.

This is how the value for each attribute of a field is computed:

1. If the cf_terrafield tag declares a value, use that; otherwise...
2. If the preset attribute is supplied, and the prefet declares a value for the attribute, use that; otherwise...
3. If the datatype preset declares a value for the attribute (usually declared in either presets.cfm or datatypes.cfm), then use that; otherwise...
4. If the format preset declares a value for the attribute (usually declared in either presets.cfm or formats.cfm), then use that; otherwise...
5. If a default is listed above, use that; otherwise...
6. The attribute has no value.

The end result of this system is that you can specify the ways you typically work with your fields in your settings files. When you need to implement a particular format or datatype, you will have very little code to write as you will only need to specify the attributes that deviate from your personal defaults.

Other attributes

Some datatypes and formats may define other "special" attributes that are not part of the standard cf_terrafield attributes listed below, but are nevertheless understood by the datatype or format. For example, the RGBTriplet datatype understands the boolean attribute websafe which tells it whether or not to only accept "Web-safe" colors.

Any attributes that are not cf_terrafield attributes or recognised special attributes will simply be passed through to the underlying field. For example, the attribute style="width : 100%" would be ignored by TerraForm and passed on to the generated tag.