Variables

HDML variables are named pieces of information that the phone substitutes into HDML at runtime. They allow you to write HDML that dynamically changes display content and navigation based on user input. You can set variables explicitly, or you can allow the user to set them with choice or entry cards. You can substitute variable values into display text and certain HDML options such as the DEST (destination) option.

---

Variable naming

There are relatively few guidelines for variable naming:

• The following nonalphanumeric characters are not allowed:
  $, <, >, =, /, \, &, *, #

• Case is significant: myvar and Myvar are two different variables

• Variable names are stored in device memory, so they should be relatively short

---

Variable scope

Variables are scoped to activities. You can reference a variable anywhere within the activity in which it is set; you can't reference it in other activities.

---

Setting variables

The VARS task option allows you to set a list of variables when you navigate from one card to another. For example, the following deck includes a display card which sets the value of two variables when the user presses ACCEPT. A second display card displays the variable values.

<HDML VERSION=3.0>
    <DISPLAY>
        <ACTION TYPE=ACCEPT TASK=GO DEST=#viewvalues
            VARS=var1=value+1&var2=value+2>
        Press OK to view variable values.
    </DISPLAY>
    <DISPLAY NAME=viewvalues>
        <WRAP>$var1
        <WRAP>$var2
    </DISPLAY>
</HDML>

FIGURE  1-9.     Setting variables

---

Capturing user input to variables

You capture user input to a variable by specifying the variable's name in the KEY option of a choice or entry card. For example, the following HDML defines an entry card that stores the user's input to a variable named usrname.

<HDML VERSION=3.0 MARKABLE=false>
    <ENTRY NAME=nameentry KEY=usrname>
        <ACTION TYPE=ACCEPT TASK=GO DEST="#greeting">
        Your name:
    </ENTRY>
     . . .

---

Referencing variables

You can substitute variable values into the following:

• Formatted text

• Option values

• Choices

• Choice and entry card defaults

HDML variable substitution is much like UNIX shell variable substitution. The following table describes the methods of substituting variable values:

For example, the following HDML allows the user to set a variable in an entry card; it then substitutes the variable's value in the display text of another card. Figure 1-10 displays the resulting interface.

<HDML VERSION=3.0 MARKABLE=false>
    <ENTRY NAME=nameentry KEY=usrname>
        <ACTION TYPE=ACCEPT TASK=GO DEST="#greeting">
        Your name:
    </ENTRY>
    <DISPLAY NAME=greeting>
        Hello $(usrname)!
    </DISPLAY>
</HDML>

FIGURE  1-10.     Setting and substituting variable values

Using the esc and noesc options

In most cases, you do not need to specify the esc or noesc options. The phone substitutes the variable using the conversion appropriate for the context. Specifically, the phone uses URL escaping when you specify a variable in the following options:

• ACCESSDOMAIN

• ACCESSPATH

• BOOKMARK

• CANCEL

• DEST

• GO

• IMAGE

• NEXT

• SRC

By default, the phone does not use URL escaping in any other context.

There are a few cases when you might need to specify the esc or noesc options. For example, If you use a variable to specify a full destination URL, you must use the noesc option. If you do not, the phone will include escape characters when it inserts the variable value, which will result in an invalid, doubly-escaped URL. For example, the following HDML displays a card that allows the user to enter the URL of an HDML service. When the user presses ACCEPT, the phone requests the URL that the user entered.

<HDML VERSION=3.0>
   <ENTRY KEY=desturl>
      <ACTION TYPE=ACCEPT TASK=GOSUB DEST="$(desturl:noesc)">
         Enter an HDML URL:
   </ENTRY>
</HDML>

FIGURE  1-11.     Setting and substituting variable values

If you did not use the noesc option to substitute the variable value, the phone would request the following, invalid URL:

Http%3a%2f%2fuplanet.com%2fjkh%2ftest.hdml

---

Passing variables between activities

HDML provides several mechanisms to pass variable information between activities:

• An activity can use the VARS option (with the GOSUB task) to set variable values for a nested activity

• When an activity invokes a nested activity, it can use the RECEIVE option to specify variables that accept return values from the nested activity; the nested activity uses the RETVALS option to return values to these variables

• When a nested activity returns, it can specify the CLEAR option to unset all the variables of the activity that called it.