The element ui:textarea displays a multi-line text input box. The generated HTML code consists of a TEXTAREA element, whose name attribute is set to a special identifier which is recognized by the system when the form is submitted.

The text box must be tied to a string variable. The contents of the widget is initialized with the current contents of the variable when the page is displayed. Conversely, the contents of the widget are transferred back to the variable when the page is submitted.

Input boxes generated by ui:textarea are very similar to the boxes generated by ui:text; the only major difference is that the boxes accept multi-line texts.

Level: Generative

<!ELEMENT ui:textarea EMPTY>
<!ATTLIST ui:textarea
          variable  NMTOKEN          #REQUIRED
          index     CDATA            #IMPLIED
          rows      CDATA            #IMPLIED
          cols      CDATA            #IMPLIED
          wrap      (off|hard|soft)  "off"
          cgi       (auto|keep)      "auto"
>

The following attributes have a special meaning:

• variable:Specifies the variable of the current dialog object to which the text box is tied. Unless the index attribute is present, the variable must have string type. If there is an index attribute, the variable must be an associative list of strings.

• index: Specifies the index value of the element of the associative variable to which the text box is tied.

• rows: Specifies the number of rows the input box displays. Note that this affects only the visual layout of the box, and does not limit the number of lines the user can enter.

• cols: Specifies the number of columns the input box displays. Note that this affects only the visual layout of the box, and does not limit the number of columns the user can enter.

• wrap: Specifies the wrapping mode of the box. See HTML documentation for the meaning of the modes.

• cgi: The value "auto" means that the name of the CGI variable associated with the text box is selected automatically. This works perfectly unless you want to refer to this variable from Javascript or from some other manually written event decoder. The value "keep" causes that the name of the CGI variable is predictable: it is var_ concatenated with the name of the variable. However, it is not allowed to specify "keep" if there is also an index value. Furthermore, the variable name should only contain alphanumeric characters, because not all punctuation characters can be safely transported over the CGI protocol.

If there are any other attributes, these are added to the generated TEXTAREA HTML element. This means that especially onblur, onchange, onfocus, and onselect may be specified.

ui:textarea has no subelements (unlike the corresponding HTML element).

The ui:textarea element generates HTML code which roughly looks as follows:

<textarea name="..." rows="..." cols="..." wrap="...">
...
</textarea>