Handling user input

HDML supports two kinds of interactive cards: entry cards and choice cards. The following sections describe how to use these cards to prompt the user for input and how to handle the input.

---

Handling text input with entry cards

Entry cards prompt users for a string of text or numbers. They allow you to determine the format of the string the user enters and to place default text in the entry field.

The following is a simplified synopsis for entry card (<ENTRY>) statements:

<ENTRY NAME=cardname FORMAT=fmt DEFAULT=def KEY=var
    EMPTYOK=boolean>
    actions
    display_content
</ENTRY>

Element	Meaning
NAME=card_name	Specifies a name that allows you to navigate to the card from other cards.
FORMAT=fmt	A format specifier for the data the user enters. If you omit this option, the phone allows free-form entry (any number of characters of any type). For information on using format specifiers, see Specifying the format of entered characters.
DEFAULT=def	A default value that appears in the entry field. The user can edit this value.
EMPTYOK=boolean	If you set EMPTYOK to TRUE, the phone accepts empty input, even if you have specified a format with the FORMAT option. The default is FALSE.
KEY=varname	The name of a variable the phone uses to return the data entered by the user.
actions	The actions to execute when the user presses softkeys.
display_text	The prompt the card displays.

For example, the following deck defines an entry card in which the user enters a name and a display card which displays the entered name. This deck creates the interface depicted in Figure 1-6.

<HDML VERSION=3.0>
    <ENTRY KEY=username>
        <ACTION TYPE=ACCEPT TASK=GO DEST=#disp>
        Enter your name:
    </ENTRY>
    <DISPLAY NAME=disp>
        Hi $username!
    </DISPLAY>
</HDML>

FIGURE  1-6.     Entry card display

Note that the KEY option specifies a variable name to which the phone stores the text that the user enters. To instruct the phone to substitute a variable's value in your HDML at runtime, you precede the variable name with a dollar sign ($). For example, the display card in the deck above echoes the entered text with the following display text:

Hi $username!

There are many other ways you can use variable values, besides echoing them back to the user in display cards. Using variables to create a dynamic interface describes in detail how to set and use variables.

Specifying the format of entered characters

The FORMAT option allows you to specify the type and case of characters the user can enter. You can use a combination of the following special characters:

• A: allows any uppercase alphabetic character (no numbers)

• a: allows any lowercase alphabetic character (no numbers)

• N: allows any numeric character (no symbols)

• X: allows any numeric, symbolic, or uppercase alphabetic character

• x: allows any numeric, symbolic, or lowercase alphabetic character

• M or m: allows any alphabetic character (of any case), and any numeric or symbolic character

For example, the format specifier NAAX specifies that the user must enter a digit, followed by two uppercase alphabetic characters, followed by an uppercase alphanumeric character.

To allow zero to unlimited characters of a specified type, you specify an asterisk (*) followed by the type. For example the specifier NN*M allows the user to enter two digits followed by any number of alphanumeric characters.

To allow the user to enter up to a specific number of characters of a type, you specify the number followed by the type. For example, N5M allows the user to enter a digit followed by up to five alphanumeric characters.¹

Note that you can use an asterisk or a number only in combination with the last character of a format specifier string. For example, a specifier such as the following does not work:

4AN

To allow the user to enter four uppercase alphabetic characters followed by a numeric character, you must use the following specifier:

AAAAN

The M and m format specifiers set the default capitalization when you precede them with a number or an asterisk. The M specifier makes the first letter the user enters uppercase by default; the m specifier makes it lowercase by default. With either specifier, the user can override the default capitalization. For example, if you use the specifier *M, the first character the user enters defaults to uppercase; the user can change it to lowercase.

How format specifiers affect the text entry interface

The UP.Phone supports the following text entry modes: alpha, ALPHA, SMART, NUM, and SYM. If you don't use a format specifier, the user can use the SOFT1 key to toggle through all of these modes. If you use a format specifier, the UP.Phone only allows the user to toggle through the modes allowed by the format specifier. For more information on text entry modes, see the UP.Browser User Handbook.

When you use format specifiers in an entry card, the UP.Phone also changes the label and the action of the ACCEPT key. If 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. 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).

For example, suppose you want to allow the user to enter a code consisting of a lower case letter and a number. To do this, you could use the following HDML:

<HDML VERSION=3.0>
    <ENTRY KEY=code FORMAT=aN>
        <ACTION TYPE=ACCEPT LABEL=Disp TASK=GO DEST=#disp>
        Enter the code:
    </ENTRY>
    <DISPLAY NAME=disp>
        The code is $code.
    </DISPLAY>
</HDML>

The interface for this HDML is shown in Figure 1-7. Note that after the user enters the letter a, the phone automatically changes the entry mode to NUM. After the user enters the number 1 (the final required character), the phone display the OK label above the ACCEPT key.

FIGURE  1-7.     Entry card display

Allowing the user to enter nothing

If you don't use a format specifier, or you use a specifier that allows zero or more characters (such as, *A, 5a, or 2N), the phone allows the user to press ACCEPT and proceed to the next card at any point. However, if you use a format specifier that requires a minimum number of characters (such as NAAN or mm*m) the user can't proceed to the next card until he or she has entered all the characters required by the specifier. To override this behavior and allow the user to proceed without entering anything, specify the entry card option, EMPTYOK=TRUE.

Adding automatic characters to the entry field

The FORMAT option also allows you to place automatic characters, which the user cannot edit, into the entry field. To specify an automatic character, you insert the character between the other format specifier characters, preceding it with a backslash (\). When the user enters data, the phone automatically inserts the characters at the specified positions. This is useful for ensuring that data such as phone numbers include parentheses or dashes in the correct places.

Suppose you use the format specifier \(NN\)-. This format specifier instructs the phone to automatically insert a left parenthesis before the user has entered anything and a right parenthesis and a dash after the user enters two digits. The following table summarizes this behavior.

For example, the following HDML deck generates the display shown in Figure 1-8:

<HDML VERSION=3.0>
    <ENTRY KEY=ssnum FORMAT="NNN\-NN\-NNNN">
        <ACTION TYPE=ACCEPT TASK=GO
            DEST=http://www.foo.com/jkh/ssinfo.cgi?SS=$ssnum>
        Enter SS#:
    </ENTRY>
</HDML>

FIGURE  1-8.     Entry card with automatic characters

Note that the phone stores the entire value in the entry field to the variable specified by the KEY option, including the automatic characters.

If you specify a default value for an entry card with automatic characters, you should include the automatic characters. For example, a valid default value for the entry card listed above would be 519-99-9999.

---

Providing choice lists with choice cards

Choice cards prompt the user to choose an item from a list of items that you specify. The following is a simplified synopsis for the choice card <CHOICE> statement:

<CHOICE NAME=name KEY=var DEFAULT=val IDEFAULT=val >
    display_text
    actions
    <CE VALUE=val tasks>text
    <CE VALUE=val tasks>text
    ...
</CHOICE>

Element	Meaning
NAME=name	The card name.
KEY=var	The name of the variable that gets the value (if any) of the chosen item.
IKEY=varname	A variable containing an index number that specifies the default item. When the user chooses an item, the phone sets the variable specified by IKEY to the number of the chosen item.
DEFAULT=val	The default value of the variable specified by the KEY option. If the variable specified by the KEY option already has a value, the DEFAULT option is ignored.
IDEFAULT=num	The index of the default entry, if the IKEY option is not specified or does not have a value.
actions	The actions to execute when the user presses a function key.
display_text	The prompt the card displays.
<CE VALUE=val task>text	An individual choice item.  val specifies the argument value the phone adds to the argument list when the user chooses the item.   task specifies a task (TASK option) to execute when the user chooses the item. The task can include options, such as DEST). For examples of specifying tasks for individual items, see Specifying a task for a choice item.  text specifies the label for the item.

For example, the following HDML deck generates the display shown in Figure 1-9:

<HDML VERSION=3.0>
    <CHOICE KEY=ch IKEY=num IDEFAULT=2>
        <ACTION TYPE=ACCEPT TASK=GO DEST=#displaychoice>
        Choose sign:
        <CE VALUE="Avoid making promises.">Capricorn
        <CE VALUE="Great things lie ahead.">Sagittarius
        <CE VALUE="New love interest awaits.">Pisces
    </CHOICE>
    <DISPLAY NAME=displaychoice>
         ($num) $ch
    </DISPLAY>
</HDML>

FIGURE  1-9.     Choice card

Note that, because the num variable does not initially have a value, the UP.Phone sets the default choice to the index specified by IDEFAULT (the second item). After the user chooses an option, the UP.Phone stores the chosen option's number to the num variable and its value to the ch variable.

Specifying a task for a choice item

HDML allows you to assign tasks to individual choice items. A choice item's task takes precedence over any action defined at the card or deck level.

For example, suppose you want to modify the previous example so that it allows the user to enter a sign that is not in the choice list. To do this, you add an item that specifies a task which displays an entry card. When the user chooses the item, the phone displays the entry card instead of the display card. The changes are shown in bold in the following code. The interface is shown in Figure 1-10.

<HDML VERSION=3.0>
    <CHOICE KEY=ch IKEY=num IDEFAULT=2>
        <ACTION TYPE=ACCEPT TASK=GO DEST=#displaychoice>
        Choose sign:
        <CE VALUE="Avoid making promises.">Capricorn
        <CE VALUE="Great things lie ahead.">Sagittarius
        <CE VALUE="New love interest awaits.">Pisces
        <CE TASK=GO DEST=#entersign>Other sign...
    </CHOICE>
    <DISPLAY NAME=displaychoice>
         ($num) $ch
    </DISPLAY>

<-- All other signs get the same horoscope -->
    <ENTRY NAME=entersign>
        <ACTION TYPE=ACCEPT TASK=GO DEST=#displaychoice
            VARS=ch=Expect+a+visitor>
         Enter your sign:
    </ENTRY>
</HDML>

The VARS option used in the entry card's action statement is explained in the next section.

FIGURE  1-10.     Choice card containing item that defines a task