<CHOICE>

Choice cards display some text followed by a list of items from which the user can choose a single item, called a choice entry. To define a choice card, you use a <CHOICE> statement. The statement must include one or more <CE> statements defining the items on the list.

---

Syntax

<CHOICE	Beginning of the choice card header.
NAME=card_name	A name for the card. Other cards can specify this name as a destination.
MARKABLE=boolean	Flag specifying whether the card can be marked. To allow the card to be marked, specify TRUE. The default value is determined by the MARKABLE option for the deck (see <HDML>).   Always set MARKABLE=FALSE for cards that execute or confirm transactions that the user might not want to repeat.   If you set the MARKABLE=TRUE, it implicitly sets the PUBLIC option to TRUE, allowing other URLs to link directly to the card.
TITLE=card_title	The default bookmark name that appears when the user marks the card.
BOOKMARK=mark_URL	The URL the phone adds to the bookmark list if the user marks the card. If you do not specify the BOOKMARK option, the phone adds the URL of the current card to the bookmark list.
KEY=var_name	The name of the variable that gets the value (if any) of the chosen item.
IKEY=var_name	The name of a variable containing an index number specifying the default item. The number 1 specifies the first item, 2 specifies the second item, and so on.  For example, if var_name is myvar and the value of myvar is 2, the second item is the default item.   If you don't specify the IKEY option or the IDEFAULT option, the first item is the default.  When the user chooses an item, the phone sets the variable specified by IKEY to the number of the chosen item.
METHOD=choice_method	The choice method. To make the list numbered, specify NUMBER. If the list is numbered, the user can choose an item by pressing the item's number or by scrolling to it and pressing a key.   To make the list unnumbered, specify ALPHA. If the list is unnumbered, the user can choose an item only by scrolling to it and pressing ACCEPT.   If you do not specify the METHOD option at all, the choice method defaults to NUMBER. Note that the phone will number only the first nine items in the list.
DEFAULT=default_val	The default value of the variable specified by the KEY option. If the variable specified by the KEY option does not have a value when the card is first displayed, the phone assigns it the value specified by the DEFAULT option. If the variable specified by the KEY option already has a value, the DEFAULT option is ignored.
IDEFAULT=default_num	The index of the default entry, if the IKEY option is not specified or it specifies a variable with no value. If the IKEY option is specified, IDEFAULT is ignored.
>	End of the choice card header.
actions	The actions to execute when the user presses a function key.   If the choice item the user chooses specifies a task, it takes precedence over these actions.  For more information on specifying actions, see <ACTION>.
display_content	A formatted text title to display above the list of items. It should be as brief as possible.  Avoid using the <LINE> tag for this text; if you use it, text that exceeds the display width will be truncated.  Avoid using more than 24 characters of text. If you use more, it will scroll off the top of the screen on many devices and the user will have to scroll back to read the entire title.  For more information on specifying formatted text, see Formatted text.
<CE ...>text	An item (choice entry) the user can choose. For a description of the <CE> statement, see <CE>.  text is formatted text describing the choice entry. By default, the UP.Phone always displays the text in horizontal scrolling (<LINE>) mode. To make it wrap, insert a <WRAP> statement before the text. If you did not specify ALPHA for the choice method, the item's number is automatically prepended to the text.
. . .	Additional items (<CE> statements) as needed.
</CHOICE>	The choice card footer.

---

Examples

The following HDML deck generates the display shown in Figure 2-6:

<HDML VERSION=3.0>
    <CHOICE KEY=ch IKEY=num IDEFAULT=2>
        <ACTION TYPE=ACCEPT TASK=GO
            DEST="?choiceval=$ch&choicenum=$num">
        <CE VALUE=Hogs>Live hogs...
        <CE VALUE=Bellies>Pork bellies...
        <CE VALUE=Cattle>Feeder cattle...
    </CHOICE>
</HDML>

FIGURE  2-6.     Choice card

If the user presses 3 (or scrolls to the third item and presses ACCEPT), the current URL is called with the following arguments:

?choiceval=Cattle&choicenum=3

The phone sets the variables specified by the IKEY and IDEFAULT options according to which choice item is selected when the user leaves the card. The phone always sets these variables, regardless of the softkey the user presses to leave the card.

Suppose we modify the previous example deck so that the first card displays the variables specified by IKEY and IDEFAULT.

<HDML VERSION=3.0>
    <DISPLAY>
        <ACTION TYPE=ACCEPT TASK=GO DEST=#chcard>
        num = $num <BR>
        ch = $ch
    </DISPLAY>
    <CHOICE KEY=ch IKEY=num IDEFAULT=2 NAME=chcard>
        <ACTION TYPE=ACCEPT TASK=GO
            DEST="?choiceval=$ch&choicenum=$num">
        <CE VALUE=Hogs>Live hogs...
        <CE VALUE=Bellies>Pork bellies...
        <CE VALUE=Cattle>Feeder cattle...
    </CHOICE>
</HDML>

If the user goes to the choice card and then immediately presses PREV to return to the first card, the first card displays the variable values as shown in Figure 2-7.

FIGURE  2-7.     Pressing keys other than ACCEPT in a choice card