Using variables to create a dynamic interface

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.

The previous section shows how you can allow the user to set variables in entry and choice cards, and how you can substitute variables into display text. The sections below demonstrate other ways you can use variables--how you can set them explicitly and how you can substitute them into HDML options.

---

Setting variables explicitly

The VARS task option allows you to set a list of variables when you navigate from one card to another. You can use it in actions (<ACTION> statements) and in tasks that you define for choice items (<CE> statements). You simply specify an ampersand-delimited list of name-value pairs for the variables you want to set. The VARS option has the following form:

VARS=variable1=value1&variable2=value2&variable3=value3 ...

You must escape the variable values using URL escaping conventions; for example, you must replace spaces with plus signs (+).

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 as shown in Figure 1-11.

<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>
        $var1
        <BR>$var2
    </DISPLAY>
</HDML>

FIGURE  1-11.     Card that explicitly sets variable values

Initializing variables

In some cases you might want to set or initialize a variable value without requiring the user to do anything. To do this, you use a no-display card. A no-display card instructs the phone to automatically execute an action without displaying anything. When the user navigates forward to a no-display card, the phone automatically executes its ACCEPT action.

For example, suppose we want to initialize the variable values as shown in the second card in Figure 1-11 without requiring the user to press ACCEPT. To do this, we use a no-display (<NODISPLAY>) card as follows:

<HDML VERSION=3.0>
    <NODISPLAY>
        <ACTION TYPE=ACCEPT TASK=GO DEST=#viewvalues
            VARS=var1=value+1&var2=value+2>
    </NODISPLAY>
    <DISPLAY NAME=viewvalues>
        $var1
        <BR>$var2
    </DISPLAY>
</HDML>

When the user loads this deck, the first card never appears. Instead, the second card appears immediately, with the variables values already set (as shown in Figure 1-12).

FIGURE  1-12.     Variables initialized with a no-display card

There are many other ways you can use no-display cards. For more information, see Using no-display cards.

---

Referencing variables

You can substitute variable values into the following:

• Any formatted text

• Destination (DEST) options

• Choices

• Choice and entry card defaults

HDML variable substitution is much like UNIX shell variable substitution. The following table describes how you can substitute variable values.

In most cases, you can just reference a variable with a dollar sign ($); you do not need to specify the esc or noesc options. For more information on using these options, see the HDML Language Reference.

The following sections describe how to reference variables in different contexts.

---

Guidelines and tips for using variables

The following are some tips and guidelines for using variables:

• Do not use recursive variable references, such as $($variable_name). Recursive variable references are invalid HDML.

• Use variables sparingly. The phone stores them in RAM, which is extremely limited on most phone models.

• Keep variable names short. The phone stores variable names in RAM along with variable values; lengthy variable names consume scarce RAM.