cf_terrafield tag reference
Used inside a TerraForm form to build an individual form field.
Default values appear in grey italics (see the note on default values below).
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.
Delimiters comma (,) or if query defined then (Chr(30))
- Optional. Only relevant in some cases, such as if
DisplayListattributes are set. The delimiter for the two lists.
- Optional. If ValueList or ValueColumn are defined, verify that submitted value is a member of the list. Generally, the
Formatwill 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
formatwhere users can either select from the list or enter a new value. In this case, ideally the
formatwould have a preset that set
- 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
- 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.
- 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
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
XPathattribute, although this will usually be more useful supplied in the
cf_terraform inputscopelistattribute (new in 2.5).
/[-+0-9]/will allow any digit or a + or - symbol. To specify that you regex should ignore case, add the
isuffix. For example:
/[0-9A-F]/iwill allow a hexadecimal number where the letters are upper or lower case.
- Optional. Turn language filtering on for this field. You would generally set this as a preset for certain datatypes or formats in your
Preset("Format_TextArea", "LanguageFilter", yes);or
Preset("DataType_String", "LanguageFilter", yes);Used in conjunction with the
- 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.
- 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
cfmoduleto call this custom tag, you will need to use
- Stop TerraForm from tampering with this field's value. This obscure attribute is used by formats such as
- 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:
An alphanumeric string containing between 6 and 12 characters and no spaces or other punctuation. This might be used when choosing a username.
An colour triplet, like #3366cc. Note that when inserting this regex into your
cf_terrafieldtag, you would need to escape the hash by doubling it:
A binary number.
A hexadecimal number.
An IP address.
- 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.
- 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
valuewill override all of these, and force a value into the field. This attribute might be useful for buttons or for certain rare circumstances.
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
- 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
inputscopelistattribute or the
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:
- 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.