The sample HDML decks in the UP.SDK Getting Started Guide manual contain only single display cards. It is possible for a single display card to contain a large amount of information. When a card has more lines than the phone can display at once, the user can scroll to see all of the lines. However, when you want to display more than a relatively small amount of information, it is recommended that you divide it into multiple display cards, rather than putting it all on one card. This enables the user to navigate quickly through the information.
Before defining a deck containing multiple display cards, it is helpful to look at a simple synopsis of the <DISPLAY> statement1:
<DISPLAY NAME=card_name>
actions
display_text
A <DISPLAY> statement can contain zero or more <ACTION> statements, each of which assigns a task to a key. The following is a simplified synopsis of the <ACTION> statement:
ACTION TYPE=key LABEL=label TASK=type DEST=url NUMBER=num>
For example, the following deck displays a weather forecast on three display cards. The cards are shown in Figure 1-1.
<HDML VERSION=3.0>
<DISPLAY>
<ACTION TYPE=ACCEPT LABEL=Tues TASK=GO DEST=#tues>
Current temps
<BR>Hi: 60
<BR>Lo: 28
</DISPLAY>
<DISPLAY NAME=tues>
<ACTION TYPE=ACCEPT LABEL=Wed TASK=GO DEST=#wed>
Tuesday temps
<BR>Hi: 78
<BR>Lo: 36
</DISPLAY>
<DISPLAY NAME=wed>
Wednesday temps
<BR>Hi: 80
<BR>Lo: 40
</DISPLAY>
</HDML>
FIGURE 1-1. Multiple display cards in a deck
When a phone first loads a deck, it automatically displays the first card in the deck. The order in which it displays subsequent cards depends on the navigation scheme specified by the deck's HDML and what the user does.
The deck defined above provides the simple navigation scheme indicated by the arrows in Figure 1-1. When the user presses ACCEPT in the first card, the phone displays the second card. This is specified by the <ACTION> statement in the first card:
This statement instructs the phone to change the label of the ACCEPT key from OK to Tues and to go to a card named tues (the second card in the deck) when the user presses the key. Likewise, the ACTION statement in the second card instructs the phone to change the label of the ACCEPT key from OK to Wed and to go to a card named wed when the user presses the ACCEPT key.
Each phone softkey has a default action associated with it. The default action for the ACCEPT key is to return to the previous card. For example, the third card in the deck above has no <ACTION> statement specifying behavior for the ACCEPT key. So, when the user presses ACCEPT, the phone returns to the previous card. For a complete list of default actions for phone keys, see the HDML Language Reference.
The UP.Phone maintains a history stack of the cards the user visits. Each time the user navigates forward to a card, the UP.Phone pushes it on to the history stack. When the user presses the PREV key, the UP.Phone pops the current card off the history stack and returns to the previous card.
UP.Phone history operation is similar to that of most Web browsers, except the user can't navigate forward in the UP.Phone history stack; the current card is always at the top of the stack.
For example, suppose the sample deck described above has the following URL:
Figure 1-2 depicts the state of the UP.Phone history stack as the user navigates in the deck described above.
To view the history stack in the UP.Phone simulator, choose History from the simulator Info menu. The simulator prints the stack from bottom to top in the Phone Information window.
The example HDML deck above includes three display cards. However, you are not required to put all of your service's cards in a single deck. In fact, because of transmission packet size limitations, you should avoid creating decks larger than 1200 bytes.2
You can rewrite the previous example so that each display card is in a separate deck (and separate HDML file). Assuming you save the decks in files named deck1.hdml, deck2.hdml, and deck3.hdml (in the same directory), you would write the HDML as follows:
<-- deck1.hdml -->
<HDML VERSION=3.0>
<DISPLAY NAME=today>
<ACTION TYPE=ACCEPT LABEL=Tues TASK=GO DEST=deck2.hdml>
Current temps
<BR>Hi: 60
<BR>Lo: 28
</DISPLAY>
</HDML>
<-- deck2.hdml -->
<HDML VERSION=3.0>
<DISPLAY NAME=tues>
<ACTION TYPE=ACCEPT LABEL=Wed TASK=GO DEST=deck3.hdml>
Tuesday temps
<BR>Hi: 78
<BR>Lo: 36
</DISPLAY>
</HDML>
<-- deck3.hdml -->
<HDML VERSION=3.0>
<DISPLAY NAME=wed>
Wednesday temps
<BR>Hi: 80
<BR>Lo: 40
</DISPLAY>
</HDML>
Note that the DEST options in deck1.hdml and deck2.hdml specify relative URLs. It is not necessary to specify a full URL, because the decks are in the same directory. It is also not necessary to specify the card name, because the phone automatically displays the first card in the deck.
You can define <ACTION> statements at several levels in HDML. The example in the previous section defines them at the card level. However, you can also define them at the deck level. An <ACTION> statement's scope covers the HDML element in which it is defined: if you define it in a deck's <HDML> statement, it applies to the whole deck; if you define it in a card's <DISPLAY>, <NODISPLAY>, <ENTRY>, or <CHOICE> statement, it applies only to the individual card.
For example, suppose you want to modify the previous example so that the user can press SOFT1 to view information on the moon cycle. To do this, you could add a deck-level action that requests the deck containing the moon information. The changes in the HDML are shown in bold:
<ACTION TYPE=SOFT1 LABEL=Moon TASK=GO DEST=moon.hdml>
<DISPLAY> FIGURE 1-3. SOFT1 action defined at deck level
When one <ACTION> statement falls within the scope of another, the statement with the narrower scope takes precedence. For example, the following HDML defines a deck-level ACCEPT action and a card-level ACCEPT action.
The ACCEPT action defined at the deck level applies to the entire deck. However, the card-level ACCEPT action defined for card1 overrides it.
FIGURE 1-4. Card-level action that supersedes deck-level action
In addition to specifying actions, which allow the user to user to navigate to different URLs, you can also define links. You can define links in any display text, except in choice cards (discussed below).
Like an HTML link, an HDML link specifies some link text that is distinguished from the surrounding text and a task to execute when the user chooses it. An HDML link can also change the ACCEPT key label and specify an accelerator (or shortcut) key.
When the user scrolls to a link, the phone displays a > marker next to it; the ACCEPT key label changes to the label specified by the link. If the user presses ACCEPT or the accelerator key, the UP.Phone executes the task specified by the link. Typically, the task consists of requesting another URL. However, it may involve other functions, such as dialing a voice phone call.
The following is a simplified synopsis of the <A> statement, which defines a link.
<A TASK=type DEST=url LABEL=label ACCESSKEY=num>link_text</A>
<ACTION> statement falls within the scope of another, the statement with The following HDML defines a card with several links (shown in Figure 1-5).
FIGURE 1-5. Display card with links
Note that the action defined for the ACCEPT key is valid as long as the user has not positioned the > symbol next to either of the links. When the user scrolls to a link, the label and the task defined by the link take precedence over the action.
