cf_terralabel tag reference

Description

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.

Syntax

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"
/>

Attributes

for

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.

indicateAccessKey Yes

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], label_[identifier]

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: label="" .

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:" .

Usage

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 style and 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 HighlightLabelTagStart and 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 labelfor attributes.

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

 

<cf_terraform
  name="MyForm1"
  flagLabels = "Yes"
  HighlightLabelTagStart="<img hspace=""5"" align=""absmiddle"" src=""/terraform/images/warning.GIF""><span style=""font-weight : bold; color : ##990000"">"
  HighlightLabelTagEnd="</span>"
  alwaysdisplayform=true
>

  <messagesblock>
    <div class="error">
      <messages>
    </div>
  </messagesblock>

  <table>
  
    <tr>
      <td>
        <cf_terralabel
          for="password1"
        />
      </td>
      <td>
        <cf_terrafield
          name="password1"
          format="password"
          required="true"
          caption="your new password"
          minlength="6"
          maxlength="12"
          size="12"
          accesskey="p"
          pattern="[[:alnum:]]*"
          error="Your password must be letters or numbers only (no spaces), and between 6 and 12 characters long."
        />          
      </td>
    </tr>
	
    <tr>
      <td>
        <cf_terralabel
          for="password2"
          label="Please re-type it to confirm"
        />
      </td>
      <td>
        <cf_terrafield
          name="password2"
          format="password"
          caption="your password confirmation"
          required="true"
          size="12"
          accesskey="c"
        />            
      </td>
    </tr>      
	
  </table>

  <cf_terrafield
    name="MySubmit1"
    caption="Submit form"
    format="submit"
  />
  
  <cf_terrarule
    rule="{password1} eq {password2}"
    error="Your passwords do not seem to match. Please re-enter."
    fieldlist="password1,password2"
  />  
  
</cf_terraform>

Your new password: *
Please re-type it to confirm *

Fields marked with  * are required.