cf_terrafield tag reference

Description

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

Syntax (the short version)

These are the basic attributes you are most likely to need regularly. Click for a complete list. Default values appear in grey italics (see the note on default values below).

<cf_terrafield
  caption = "caption"                            #FieldName#
  datatype = "datatype"                          default
  displaycolumn = "display_column"               ValueColumn
  displaylist = "display_list"                   ValueList
  format = "format"                              text
  inlineErrors = "Yes" or "No"                   No
  max = "max"
  maxlength = "max_length"
  min = "min"
  minlength = "min_length"
  name | fieldname = "name"
  preset = "preset"
  prompt = "prompt"
  query = "queryname"
  required = "Yes" or  "No"                      No
  valuecolumn = "value_column"
  valuelist = "value_list"
>
  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.

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.

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

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.

name | fieldname

Required. The name for the form field. This becomes the HTML 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.

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.

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.

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