ui:text and ui:password

The element ui:text displays a one-line text input box. The element ui:password displays a password input box. The difference is that the contents of the password box are invisible (only a string of asterisks). - The generated HTML code consists of an INPUT element with TYPE=TEXT or TYPE=PASSWORD, whose name attribute is set to a special identifier which is recognized by the system when the form is submitted.

The text or password 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.

In the following example, the user can enter a file name. The variable file_name is initialized with the value "sample.txt", and because this is the intial value of the variable, this string will also be the initial value of the text widget.

<ui:dialog name="sample" page="sample_page">
  <ui:variable name="file_name" type="string">
    <ui:string-value>sample.txt</ui:string-value>
  </ui:variable>

  <ui:page name="sample_page">
    <html>
      <body>
        Please input the file name:
        <ui:text variable="file_name"/>
        <ui:button name="ok" label="OK"/>
      </body>
    </html>
  </ui:page>
</ui:dialog>

Declaration

Level: Generative

<!ELEMENT ui:text EMPTY>
<!ELEMENT ui:password EMPTY>

<!ATTLIST ui:text
          variable  NMTOKEN     #REQUIRED
          index     CDATA       #IMPLIED
          maxlength CDATA       #IMPLIED
          size      CDATA       #IMPLIED
          cgi       (auto|keep) "auto"
>
<!ATTLIST ui:password
          variable  NMTOKEN     #REQUIRED
          index     CDATA       #IMPLIED
          maxlength CDATA       #IMPLIED
          size      CDATA       #IMPLIED
          cgi       (auto|keep) "auto"
>

Additionally, ui:text and ui:password must only occur inside ui:form.

Attributes

The following attributes have a special meaning:

variable: Specifies the variable of the current dialog object to which the text/password 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/password box is tied.
maxlength: Specifies the maximum number of characters the input box can accepts.
size: Specifies the length of the input box in characters.
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 INPUT HTML element. This means that especially onblur, onchange, onfocus, and onselect may be specified.

Sub elements

Neither ui:text nor ui:password have sub elements.

Generated HTML code

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

<input type="TEXT" name="..." value="..." maxlength="..." size="...">

The ui:password element generates something like that:

<input type="PASSWORD" name="..." value="..." maxlength="..." size="...">