label (item)

Defines a static text message or an image to display on the form.

If both an image and a text message are defined for the label, the image takes precedence in viewers able to display images.

Available options

active, bgcolor, border, borderinfo, fontcolor, fontinfo, format, gradient, help, image, imagemode, itemlocation, itemnext, itemprevious, justify, linespacing, printbgcolor, printfontcolor, printvisible, size, value, visible, xformsenabled, xformsreadonly, xformsrequired, xformsvalid, xforms:output

Example

The following label example shows a value from the XForms data layer combined with a textual label indicating the meaning of the value. The raw data value is formatted using locale-specific currency rules (e.g. $856.07). The data value is determined by a formula provided by the XForms calculate, which is immediately responsive to any user changes to the principal, interest rate, or duration of the loan for which this monthly payment is being calculated. Also, due to the XForms relevant model item property, the label item is invisible until the user enters positive Principal and Duration values.

   <xforms:instance xmlns="" id="loan">
      <LoanRecord>
         ...
         <MonthlyPayment>856.07</MonthlyPayment>
      </LoanRecord>
   </xforms:instance>
   ...
   <xforms:bind nodeset="MonthlyPayment" 
                calculate="if(instance('rate') > 0, 
                              ../Principal * instance('rate') 
                              div 
                              (1.0 - power(1.0 + instance('rate'), -../Duration)),
                              ../Principal div ../Duration)"
                relevant="../Principal > 0 and ../Duration > 0"/>
   ...
   <label sid="MonthlyPaymentItem">
      <xforms:output ref="MonthlyPayment">
         <xforms:label>Monthly Payment: </xforms:label>
      </xforms:output>
      <format>
         <datatype>currency</datatype>
      </format>
      <itemlocation>
         <under>InterestRateItem</under>
         <expandr2r>InterestRateItem</expandr2r>
      </itemlocation>
   </label>

This is an example of a multiple-line text label:

   <label sid="RHYME LABEL">
      <value>
         Little Miss Muffet sat on her tuffet,
         Eating her curds and whey.
         When along came a spider, who sat down beside her,
         and frightened Miss Muffet away!
      </value>
      <fontinfo>
         <fontname>Times</fontname>
         <size>16</size>
         <effect>italic</effect>
      </fontinfo>
      <justify>right</justify>
   </label>

Usage details

  1. The text displayed by a label is defined by: the xforms:output option, if given; otherwise the value option.
  2. To define an image for a label, either use the mediatype="image/*" attribute setting on the xforms:output option or use the XFDL image option.
  3. To create a multiple line text message, add line breaks to the message text.
  4. When setting the size option of a label, the height and width of the label will be based on the average character size for the font in use (set with the fontinfo option).
  5. If you set the width for a label, but not the height, then the label will automatically grow to accommodate the text within the given width. In other words, the text will wrap to fit within the width specified, and the height will increase to accommodate the text.
  6. If a label's image option points to a data item that does not exist or contains no data, then the label will display its value option instead.
  7. If a label contains both a value option and an xforms:output option, then the xforms:output overrides the value.
  8. If a label contains an xforms:output with an xforms:label, the value of the xforms:label is concatenated with the value of the xforms:output (always label first). This allows you to create a decoration for the text that is displayed. For example, you might want your label to read "Total: 200", where the "Total:" is provided by an xforms:label and the "200" is provided by the xforms:output. Note that the xforms:label can only contain text and is not affected by the format option.
  9. If a label is decorated by an xforms:label, and the justify option it set to right justify, then the value of the label item is right justified but the additional text from the xforms:label remains left justified. This allows you to create space between the xforms:label and the value, as shown: 
       Total:    200
  10. If a label contains a suppresslabel option, it prevents the xforms:label from being displayed.
  11. If a label's image option points to a data item that dynamically changes its mimedata (but not its item sid), then the label will update the image it displays. For information on how to update an image by enclosing a new one, see the data option description.
  12. Set the image display behavior with the imagemode option.
  13. The label's background color defaults to being transparent - and thus the label will allow whatever item it is over to show through. For example, it is possible to place a label over another label holding an image. The image will show through the top label.
  14. Label contents (if text) can be formatted using format flags (see section format).
  15. The suppresslabel option suppresses the label, so that it is not displayed.
Parent topic: Items