cf_terrafield tag reference
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" />
- 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
captionis the value of the field's
nameattribute, 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".
- 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.
- 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.
- Optional. The interface for this field. Remember that the
datatypeand 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.
- 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).
- Optional. Specify the minimum or maximum length for the character string. For a password field, for example, you might specify:
If you want an exact length, set both
maxlengthto the same value.
- 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
Maxbefore 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
cfmoduleto call this custom tag, you will need to use
- 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.
- Optional. Ignored by many formats, but used on
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.
PromptValueis an optional attribute assigning a value to this option, defaults to "".
- Optional. Builds
DisplayListautomatically from the columns of an already executed query.
Queryis the name of the query, for example "Countries".
DisplayColumnare the names of columns, for example "CountryID" and "CountryName".
ValueColumnis required if
- Optional. Insist that this field must be filled in? This is meaningless for some fields, for example, a
booleancheckbox will always contain either "True" or "False" and will never be empty.
Valuelistis a list of possible values for this field.
DisplayListis a corresponding list of human-friendly captions for those values. So if the data was countries,
Valuelistmight be numeric country IDs, while
Displaylistwas the names of the countries. Used to provide the options for
checkboxand similar format fields. Also used for validation purposes. I could apply it to a
text formatfield, for example, and I might receive an error: "I don't recognise that country."
DisplayList defaults to
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:
- If the
cf_terrafieldtag declares a value, use that; otherwise...
- If the
presetattribute is supplied, and the prefet declares a value for the attribute, use that; otherwise...
- If the datatype preset declares a value for the attribute (usually declared in either
datatypes.cfm), then use that; otherwise...
- If the format preset declares a value for the attribute (usually declared in either
formats.cfm), then use that; otherwise...
- If a default is listed above, use that; otherwise...
- 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.
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.