<ACTION>

An action associates a task with an UP.Phone function key (ACCEPT, PREV, or HELP, SEND, DELETE, SOFT1-SOFT2). When the user presses the function key, the UP.Phone executes the task.

The following tasks are currently supported:

• Requesting the current URL with different arguments

• Requesting another URL

• Requesting another URL, starting a nested activity

• Returning to the calling activity

• Cancelling the current activity, returning to the calling activity

• Displaying the previous card in the history

• Dialing a specified phone number

---

Action precedence for function keys

You can specify actions and tasks at several levels in HDML. For example, both a card, and the deck that contains, it can include actions that specify tasks for the ACCEPT key. The UP.Phone uses the rules of precedence described in the sections below to determine which task to execute.

ACCEPT

When the user presses ACCEPT, the UP.Phone uses the following rules to determine what action to take:

1. If the current card is a choice card and the choice entry the user selected specifies a task, the UP.Phone executes the task and skips the following rules.
2. If the user has scrolled to a link that specifies a task, the UP.Phone executes the task and skips the following rules.
3. If the current card defines an action for ACCEPT, it executes the task specified by the action and skips the following rules.
4. If the current deck defines an action for ACCEPT, it executes the task specified by the action and skips the following rule.
5. Displays the previous card.

PREV

When the user presses PREV, the UP.Phone uses the following rules to determine what action to take:

1. If the current card defines an action for PREV, it executes the task specified by the action and skips the following rules.
2. If the current deck defines an action for PREV, it executes the task specified by the action and skips the following rule.
3. Displays the previous card. If the current card is the first card in the current activity, the UP.Phone cancels the current activity and returns to the card that originally invoked it.

SOFT1-SOFT2

The UP.Phone handles the softkeys, SOFT1-SOFT2, in a similar fashion. The rest of this manual uses the term SOFTx to describe behavior that applies to SOFT1-SOFT2.

When the user presses SOFTx, the UP.Phone uses the following rules to determine what action to take:

1. If the current card defines an action for SOFTx, it executes the task specified by the action and skips the following rules.
2. If the current deck defines an action for SOFTx, it executes the task specified by the action and skips the following rules.
3. If 1) and 2) don't apply, it does nothing.

If you have specified an action for a key at the deck level but you want the key to be inactive in an individual card, specify an action with no task for the card.

HELP

When the user presses HELP, the UP.Phone uses the following rules to determine what action to take:

1. If the current card defines an action for HELP, it executes the task specified by the action and skips the following rules.
2. If the current deck defines an action for HELP, it executes the task specified by the action and skips the following rule.
3. Displays a built-in card containing a message that no help is available for the current location.

SEND

When the user presses SEND, the UP.Phone uses the following rules to determine what action to take:

1. If the current card defines an action for SEND, the UP.Phone executes the task specified by the action and skips the following rules.
2. If the current deck defines an action for SEND, the UP.Phone executes the task specified by the action.
3. If rules 1-2 don't apply, it does nothing.

DELETE

When the user presses DELETE, the UP.Phone uses the following rules to determine what action to take:

1. If the current card is a text entry card, the UP.Phone deletes the character to the left of the cursor.
2. If the current card defines an action for DELETE, the UP.Phone executes the task specified by the action and skips the following rules.
3. If the current deck defines an action for DELETE, the UP.Phone executes the task specified by the action.
4. If rules 1-3 don't apply, the UP.Phone does nothing.

---

Syntax

Statement	Description
<ACTION	Beginning of the ACTION statement.
LABEL=key_label	The label for the key. key_label should be five characters or shorter. The default label for the ACCEPT key is OK.  If you are associating a task with the ACCEPT key, the label is optional. If you are associating a task with the PREV key, any label you specify is ignored. If you are associating the task with any other key (for example SOFT1), the label is required.   Some devices restrict softkey labels to a subset of the character set allowed in display text. For more information on this restriction, see Softkey label character sets.
TYPE=key	The key to associate the task with:  ACCEPT     (LABEL optional) HELP       (LABEL required) PREV       (LABEL ignored) SOFT1      (LABEL required) SOFT2      (LABEL required) SEND       (LABEL required) DELETE     (LABEL required)  For a description of the default actions and action precedence for each of these keys, see Action precedence for function keys.
TASK=task_type	The task to execute:  GO GOSUB RETURN CANCEL PREV CALL NOOP   For descriptions of these tasks and the options you can use with them, see the table in Task types.
DEST=dest_url	The URL to request in GO and GOSUB tasks.  If the current activity is nested and the task is a RETURN or CANCEL task, DEST specifies a URL to request upon returning to the calling activity. However, if the calling activity does not designate the current activity as "friendly," the UP.Phone ignores the DEST option. The DEST option overrides the NEXT or CANCEL options of the calling activity.
REL=NEXT	Instructs the phone to prefetch the URL specified by the DEST option. The phone loads and caches the URL while the user is viewing the current card.   If the user invokes the action (requesting the URL) the phone can retrieve the URL from the cache instead of requesting it from the UP.Link server. This gives the user a perception of enhanced performance.  There is no guarantee that the phone will be able to prefetch the specified URL. For example, if the phone is on a circuit-switched network and the circuit is down, the phone will not open a circuit. If the phone fails to execute the prefetch, it does not retry it.  If you specify the REL=NEXT option, the URL is added to the end of the phone's cache. If the user does not request the URL soon after the phone caches it, the phone pushes it out of the cache, and caches other data instead.  If several tasks on a card specify the REL=NEXT option, the phone prefetches the URLs in the order in which the tasks are listed.
METHOD=get_or_post	If the DEST option specifies a URL, the method used to request the URL: GET or POST.  If you do not specify this option, the default, GET, is used.  It is strongly recommended that you use the POST method instead of the GET method. Using the POST method ensures that the UP.Link server will properly transcode data from the phone to the correct character set for your application (as specified by the HTTP headers set by your application). For more information on character sets and HTTP headers, see the UP.SDK Developer's Guide.
POSTDATA=data	The data to post if the METHOD option specifies POST. If the data contains multiple arguments, delimit the arguments with ampersands (&).
ACCEPT-CHARSET=chset	Specifies the character set which the HDML application expects data returned from the phone to use.   It can specify character set names, such as the following:  utf-8 us-ascii iso-8859-1 shift-jis   For a complete list of character set names, see Supporting multiple character sets  If you do not specify the ACCEPT-CHARSET option, the character set defaults to the character set of the deck (as specified by the deck's HTTP headers). For more information on character sets and HTTP headers, see the UP.SDK Developer's Guide.
VARS=varpairs	A list of variables to set for the current activity (if the task is GO) or nested activity (if the task is GOSUB). The variable list must be in query-string format, for example:  var1=value1&var2=value2   Variable values must be escaped according to URL escaping conventions. The phone unescapes the VARS option before setting the value of the variables.
RECEIVE=var_list	A semicolon-delimited list of variables to which the phone stores the return values from a GOSUB task.  The phone stores return values according to ordinal position. For example, if you specify the following option:   receive=var1;var2   the phone stores the first return value to var1 and the second return values to var2.  If you want to skip a return value, you must include a semicolon as a placeholder. For example, to ignore the first return value and store the second return value to var2, you specify the following option:  receive=;var2
RETVALS=val_list	A semicolon-delimited list of values that an activity invoked with GOSUB returns to the invoking activity. The RETVALS option is allowed only with the RETURN task.  The values must be escaped according to URL-escaping conventions.
NEXT=next_url	The URL to request after a nested activity returns.   If the FRIEND option in the GOSUB task is set to TRUE, the NEXT option can be overridden by the DEST option in the nested activity's RETURN task.
CANCEL=cancel_url	The URL to request after a nested activity invoked by a GOSUB task cancels.  If the FRIEND option in the GOSUB task is set to TRUE, the CANCEL option can be overridden by the DEST option in the nested activity's CANCEL task.
FRIEND=boolean	A boolean value specifying whether the nested activity specified in a GOSUB task is "friendly." A friendly nested activity can use the DEST and CLEAR options in RETURN and CANCEL tasks and override the NEXT and CANCEL options of the calling task.  To indicate the nested activity is friendly, specify TRUE. The default is FALSE.
SENDREFERER=boolean	A boolean value specifying whether the UP.Browser should provide the URL of the current deck when requesting the URL specified by the DEST or NEXT options. If you set it to TRUE, the UP.Browser specifies the deck's URL in the "Referer" header of the request.   The UP.Browser attempts to use the shortest possible relative URL in the "Referer" header if possible.  The default value is FALSE.
CLEAR=boolean	A boolean value specifying whether a RETURN or CANCEL task from a nested activity unsets all the calling activity's variables. To unset the calling activity's variables, specify TRUE. The default is FALSE.   The phone ignores the CLEAR option unless the calling activity specifies that the current activity is "friendly."
NUMBER=number	For a CALL task, the phone number to call.
SRC=image_url	The URL of an image to display in place of the softkey label (see Using images as softkey labels). If a valid name is specified for the ICON option, the device ignores this option.  Because SOFT1 and SOFT2 do not have default labels, you must specify the LABEL option if you use an image for either of these softkeys. The device will use this label if it cannot find the image you specify.
ICON=icon_name	The name of a local image to display in place of the softkey label (see Using images as softkey labels). If the UP.Browser cannot find the image in ROM, it retrieves it from the UP.Link server.   Because SOFT1 and SOFT2 do not have default labels, you must specify the LABEL option if you use an image for either of these softkeys. The device will use this label if it cannot find the image you specify.  See Figure 2-14 for a list of the icon names you can specify for this option.
>	End of the ACTION statement.

Task types

The following table lists the task types you can specify for the TASK option. It also lists the other options you can use with each task type. Required options appear in bold.

Example

The following code defines a deck with two display cards (see Figure 2-2). The deck defines an action which assigns the CANCEL task and a label to the SOFT1 key; this action applies to both cards in the deck. The first card defines an action which specifies that the phone will request the second card when the user presses ACCEPT. The second card does not define an action for the ACCEPT key, so the phone implements the default (go to the previous card in the history). Neither card defines an action for the PREV key, so the phone uses the default behavior (go to the previous card in the history).

<HDML VERSION=3.0>
<ACTION TYPE=SOFT1 TASK=CANCEL LABEL=Cancel>
<DISPLAY NAME=card1>
    <ACTION TYPE=ACCEPT TASK=GO DEST=#card2>
    Card 1
</DISPLAY>

<DISPLAY NAME=card2>
    Card 2
</DISPLAY>
</HDML>

FIGURE  2-2.     Deck with two display cards

Using images as softkey labels

You can use images as softkey labels by specifying the SRC or ICON options within an <ACTION> statement. The following example illustrates how to use icons for both the ACCEPT and SOFT1 function keys (see Figure 2-3).

<HDML VERSION=3.0>
<CHOICE KEY=choice>
    <ACTION TYPE=ACCEPT ICON=righthand TASK=GO DEST=#card2>
    <ACTION TYPE=SOFT1 LABEL=Call ICON=phone1 TASK=CALL
        NUMBER=$choice>
    <CE VALUE="415-555-1234">Jim Smith
    <CE VALUE="415-555-5678">Sandra Johnson
    <CE VALUE="415-555-9090">Lisa Cantrell
</CHOICE>

<DISPLAY NAME=card2>
    <ACTION TYPE=ACCEPT ICON=righthand>
    Card 2
</DISPLAY>
</HDML>

FIGURE  2-3.     Deck that uses icons as softkey labels