WML supports two kinds of user input: entering text and selecting from a list. The following sections describe how to both prompt the user and handle the response.
The <input> element lets you prompt users to enter a string of text or numbers. You can control the format. The following is a simplified synopsis of the <input> element:
variable" title="label"
specifier" maxlength="n" emptyok="boolean"/>
| Component | Description |
|---|---|
text
| |
|
name
| |
|
title
|
A brief label for the input item (applicable for |
|
format
| A character format specifier for the user entry (see Specifying text entry formats). If you omit this attribute, the UP.Browser lets the user enter characters of any type. |
|
maxlength
| The maximum number of characters the user can enter. If you omit this attribute, the UP.Browser imposes a limit of 256 characters. |
|
emptyok
|
Indicates whether or not the field is optional (default is |
<input> element and its attributes, see the WML Language Reference.
For example, the following deck defines two cards--the first card prompts the user to enter a name, and the second card displays it (see Figure 1-7).
Figure 1-7. Card with user entry field
The name attribute specifies a variable in which the phone will store the text the user enters. As shown above, to display the value in the variable at runtime, prefix the variable name with a dollar sign ($). For more information about setting and using variables, see Using variables.
The format attribute allows you to specify the type and case of characters the user can enter. You can use a combination of the following special tags:
For example, specifying format="NAAA" requires the user to enter a number followed by exactly three symbols or uppercase alphabetic characters. In contrast, specifying a single digit number before the character tag limits the number of characters that users can enter without requiring a set number. For example, specifying format="N3A" requires the user to enter a number followed by zero to three symbols or uppercase alphabetic characters.
To let users enter an unlimited number of characters of a particular type, specify an asterisk (*) before the character tag. For example, specifying format="NN*M" requires the user to enter two numbers followed by any number of symbols, numbers, or alphabetic characters.
"4AN" or "*M2N" are not allowed.
The M and m format tags set the default capitalization when you precede them with a number or asterisk. The M specifier makes the first letter the user enters uppercase by default; the m specifier makes it lowercase by default. The user can override the default capitalization in both cases.
If you do not specify the format attribute or specify a format that allows zero or more characters (for example, *A, 5a, or 2N), the user can press ACCEPT and proceed to the next card at any point. If, however, you specify a format that requires a minimum number of characters (for example, NAAN or mm*m), the UP.Browser hides the ACCEPT key label (either one you have specified or the default) until the user enters the last character required by the format specifier. In this case, the user cannot proceed to the next card until he or she has entered all the required characters.
NOTE
If the user presses the ACCEPT key while the label is hidden, the UP.Browser simply performs the default ACCEPT key behavior (invokes a prev task).
To make field entry optional rather than required, specify emptyok="TRUE" in your <input> statement. This attribute lets the user leave the field blank without removing the format requirements if he or she does enter a value.
The format attribute also allows you to insert uneditable characters in an entry field. This feature is useful for imposing a known format on user-entered data--for example, making sure phone numbers use parentheses or dates use slashes (/) instead of dashes. To add automatic characters, insert each character in the desired position within your format specifier, preceding each with a backslash (\). The UP.Browser automatically inserts the character in the field as the user enters a value.
For example, specifying format="\(NN\)-" instructs the UP.Browser to insert a left parenthesis before the user enters anything and a right parenthesis and a dash after the user enters two numbers. The following table summarizes this behavior:
For example, the following WML generates the card shown in Figure 1-8:
Figure 1-8. Using automatic characters in a text entry field
NOTE
The UP.Browser stores the entire field value, including automatic characters, in the variable specified by the name attribute. Thus, if you use automatic characters in your format specifier, you should include them in any default value you specify for the field.
The UP.Browser supports the following text entry modes: alpha, ALPHA, smart, SMART, NUM, and SYM. When you define an input field, the UP.Browser automatically reserves the OPTIONS key for toggling between entry modes. If you specify the format attribute, the user can only toggle through the entry modes allowed by the format specifier; otherwise, the user can toggle through all of the entry modes. For more information on text entry modes, see the quick reference, Using the UP.Browser.
For example, suppose you want the user to enter a code consisting of a lowercase letter and a number. To do this, you could use the following WML:
The interface for this deck is shown in Figure 1-9. Note that after the user enters the letter q, the phone automatically changes the entry mode to NUM. After the user enters the number 1 (the final required character), the UP.Browser displays the OK label above the ACCEPT key.
Figure 1-9. Format specifier and text entry modes
The <select> element causes the device to prompt the user to choose one or more items from a specified list. The following is a simplified synopsis of the <select> element:
label" name="variable" ivalue="default">
value">content</option>
value">content</option>
| Component | Description |
|---|---|
text
| |
|
title
| |
|
name
| The name of the variable in which to store the user selection(s). |
|
ivalue
|
The default item(s) selected if the |
|
<option>
|
An individual choice item where |
<select> element and its attributes, see the WML Language Reference.
For example, the following WML deck generates the display shown in Figure 1-10:
Figure 1-10. Card with selection list
Because the choice variable does not initially have a value, the UP.Phone sets the default selection to the item with the index value specified by ivalue (the second item in this case). When the user selects an option, the UP.Phone stores the value associated with that option to the choice variable.
In some cases, you may want the act of choosing a selection item to trigger a particular action. You can accomplish this in WML by associating a task with an intrinsic event (or state transition) for the selection item. Specifying the <onevent> element within an <option> statement binds the specified task (<go>, <prev>, <noop>, or <refresh>) to that selection item.
If the task you want to define is a <go> task that simply navigates to another URL, you can use a shorthand version of the <onevent> statement--in this case, you can simply specify the onpick attribute in your <option> statement (see example below).
For example, suppose you want to modify the previous example so that one of the options is to enter a sign not shown in the list. To do this, add an <option> statement that displays a card with a text entry field when the user selects it (see Figure 1-11).
<!-- All other signs get the same horoscope -->
<card id="entersign">
NOTE
The next section explains how to use the <setvar> element to pass information when performing a <go> task.
Figure 1-11.
Card with selection item bound to <GO> task
As described above, the task in this example is a simple <go> statement. In this case, using the onpick attribute is the most efficient way to define this behavior. You could, however, have specified the exact same behavior using the full <onevent> syntax shown below:
Note that you must use the <onevent> syntax if you want to do either of the following:
<go> task--for example, one that sets variable values or uses the sendreferer or accept-charset attributes, or postfield element.
<prev>, <noop>, or <refresh>.
<onevent> element, see the WML Language Reference.