cf_terralabel tag reference
Used inside a TerraForm form to create the text label for an individual form field. Although text labels may be created simply by entering some text next to the field, this tag provides certain benefits and may be useful in some circumstances. Use of
cf_terralabel allows greater flexibility in placement of automatically generated required field flags, and in the ways you can highlight error fields.
Default values appear in grey italics.
<cf_terralabel for = "fieldlist" indicateAccessKey = "Yes" or "No" Yes > text_label [the field captions] </cf_terralabel>
or (specifying label as an attribute):
<cf_terralabel for = "fieldlist" indicateAccessKey = "Yes" or "No" Yes label = "text_label" [the field captions] label_[identifier] = "text_label" />
- Required. List of the names of fields this label applies to. Usually this will be just one field, although in some cases there may be several. For example, a label "Name:" could be associated with individual first name, initial, and surname fields.
- Optional. If your field uses the HTML accesskey attribute, TerraForm can automatically underline the appropriate letter of your label to indicate the access key. This behavior is on by default — simply specify an access key for your field.
label [the field captions],
- Optional. The text label to display. This defaults to the caption of the associated field (or a list of the captions if there are multiple fields). If you want no label, you must explicitly add the attribute:
Note that you may also provide alternative labels so that a single form may be reused for different languages. Write the attribute as
label_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 label in that order. For example, your field may have the attributes:
label="Your name:" label_de="Ihr Name:".
To TerraForm, almost everything on your page that is not a TerraForm tag is a complete mystery. This is by design, as it gives you more freedom to construct your form to look however you like. Unfortunately, this means that TerraForm does not have much idea about exactly where the labels for your form fields are. Use of this tag fixes the locations of the labels, so that TerraForm can work with them more intelligently.
Note that in using this tag you can dispense with
labelfor attributes. You do not need them. This...
<table> <tr> <td labelfor="name"> Your name </td> <td> <cf_terrafield name="name" caption="your name" required/> </td> </tr> </table>becomes this...
<table> <tr> <td> <cf_terralabel for="name"/> </td> <td> <cf_terrafield name="name" caption="your name" required/> </td> </tr> </table>
More flexible required field flagging
If you are making use of TerraForm's automatic required field flagging, you will have noticed that the flag appears next to the field itself. With the
cf_terralabel tag, TerraForm knows the location of your field's label, so it becomes possible to place your flag next to the label instead. To do this, give your form the following attributes (or add them to your
defaults.cfm settings file):
flagRequiredFields = "Yes" flagLabels = "Yes"
You can change the appearance of the flag using the
requiredFlag attribute in your
cf_terraform tag or by editing the value in your
defaults.cfm settings file.
More flexible error field highlighting
TerraForm allows you to highlight the labels associated with error fields by making use of the
labelfor attribute. You can apply this attribute to any tag, and TerraForm will replace it with a predefined string of attributes for each error field (see
Highlight in your
defaults.cfm settings file). This simple technique allows you to highlight the labels of error fields using the standard attributes such as
class. However, if you want to flag error fields by inserting tags, this technique does not suffice. With
cf_terralabel, more powerful and flexible highlighting automatically becomes available.
To customise your error highlighting, set values for the
HighlightLabelTagEnd in your
cf_terraform tag or edit the values in your
defaults.cfm settings file.
HighlightLabelTagStart contains any code to be placed in advance of the label (e.g. opening tags).
HighlightLabelTagEnd contains any code to be placed after the label (e.g. closing tags). To avoid unpredictable results, be sure to remove any lingering
Here is our custom rule validation sample again, only this time with cf_terralabel tags. Note that the required field flags are now next to the taxt labels, and try submitting an invalid form to see the customised highlights on the error fields (this is simply a demo, any information entered here will be discarded):
Fields marked with * are required.