Actions

HDML allows you to define actions, which associate a phone function key with a task, such as downloading and displaying a specified card or deck, or dialing a phone number.

If you do not define an action for a key, the phone executes the key's default task when the user presses it. The following table lists supported function keys and their default tasks:

---

Destinations

Destinations are URLs that specify digests, decks, and cards to download and display on the phone. Destinations are similar to conventional World Wide Web URLs, with several extensions:

• A destination that identifies an HDML deck uses a conventional URL, for example:
  http://devgate2.uplanet.com/examples/password.hdml
  

• The first card in a deck has the same URL as the deck itself.
  To identify another card in the deck, you append a hashmark (#) and the cardname to the deck URL. For example, the following destination identifies a card named card2 in the password.hdml deck:
  http://devgate2.uplanet.com/examples/password.hdml#card2
  

• If you are referencing a card that is within the same deck, you can use the card name by itself, for example:
  #card2
  

---

A simple example

The following HDML deck contains two cards, which specify actions. The action in the first card instructs the phone to display the second card when the user presses ACCEPT; the action in the second card instructs the phone to request the URL http://devgate2.uplanet.com/ when the user presses ACCEPT.

<HDML VERSION=3.0>
    <DISPLAY NAME=card1>
        <ACTION TYPE=ACCEPT TASK=GO DEST=#card2>
        Card 1
    </DISPLAY>
    <DISPLAY NAME=card2>
        <ACTION TYPE=ACCEPT TASK=GOSUB
                DEST=http://devgate2.uplanet.com/c.hdml>
        Card 2
    </DISPLAY>
</HDML>

FIGURE  1-3.     Cards that specify actions

---

Action scope and precedence

You can define actions at both the deck and the card level. The scope of an action defined at the deck level is the entire deck. The scope of an action defined at the card level is the current card only. Actions defined at the card level take precedence over actions defined at the deck level.

For example, the following deck defines actions at both the deck and the card level.

<HDML VERSION=3.0>
    <ACTION TYPE=ACCEPT TASK=GO DEST=#cardA>
    <ACTION TYPE=SOFT1 TASK=GO DEST=#cardC>
    <DISPLAY NAME=card1>
        <ACTION TYPE=ACCEPT TASK=GO DEST=#cardB>
        Card 1
    </DISPLAY>
. . .
</HDML>

If the user presses SOFT1 while the phone is displaying card1, the phone goes to cardC. However, if the user presses ACCEPT, the phone goes to cardB--that is, it executes the ACCEPT action defined by the Display card and ignores the ACCEPT action defined by the deck.