Not all of the BNF statements can be found in this section. For a complete listing of the HDML BNF, see "HDML 2.0 BNF Summary."
deck ::= deck-header { action }* { card }+ deck-footer
deck-header ::= <HDML o-version ol(deck-options) >
deck-options ::= o-ttl | o-deckseq | o-public |
o-accessdomain | o-accesspath | o-markable
deck-footer ::= </HDML>
A deck starts with the <HDML> tag and ends with the </HDML> tag. It contains an optional list of default actions and one or more cards. There must be at least one card. Actions specified at the deck level are used as default actions by the whole deck. Individual cards may override deck actions as needed. See "The ACTION Element" for syntax and full description.
o-version := version = value
The version of the deck indicates the particular version of the HDML language that is used in the rest of the deck. It is of the form m.n where m is the major version number and n is the minor version number. This specification describes HDML version 2.0.
o-ttl ::= ttl = {numeric}+
Decks can be cached by the user agent for a period of time. The TTL option indicates the number of seconds that the deck can be cached from time of reception. If no TTL is given, the deck will be cached for an indeterminate period of time. If the value of TTL is 0 (zero) then the deck is cached only in the context of the current activity. See "Deck Time-to-Live" for more details on the behavior of expired decks.
o-public ::= public = boolean-value
The PUBLIC option indicates whether deck access control has been enabled for this deck. If PUBLIC=TRUE, cards in any deck can access the deck. If PUBLIC=FALSE, then the ACCESSDOMAIN and ACCESSPATH options are enabled and indicate which decks can access the deck. The default value of PUBLIC=FALSE.
o-accessdomain ::= accessdomain = url
o-accesspath ::= accesspath = path
The ACCESSDOMAIN and ACCESSPATH options specify which decks may access the deck. When one card goes to another card, access control is performed to determine whether that destination is allowed. The access control options protect cards that, for example, return sensitive information.
If a deck has an ACCESSDOMAIN and/or ACCESSPATH option, the referring deck's URL must match the values of the options. Matching is done as follows: the access domain is suffix-matched against the domain name portion of the referring URL, and the access path is prefix matched against the path portion of the referring URL.
The ACCESSDOMAIN option defaults to the current deck's domain. The ACCESSPATH option defaults to "/".
To simplify the development of applications which may not know the absolute path to the current deck, the ACCESSPATH option will accept relative URLs. The user agent will convert the relative path to an absolute path and then perform prefix matching against the ACCESSPATH option.
Given the following access control options:
ACCESSDOMAIN="uplanet.com"
ACCESSPATH="/cbb"
The following referring URLs would be allowed to go to the deck:
http://red.uplanet.com/cbb/stocks.cgi
https://yellow.uplanet.com/cbb/bonds.cgi
http://uplanet.com/cbb/demos/alpha/packages.cgi?x=123&y=456
The following referring URLs would not be allowed to go to the deck:
http://up.dbc.com/cbb
http://up.uplanet.com/internal/foo.hdml
o-markable ::= markable = boolean-value
A user agent can save the location and state of the currently viewed card by bookmarking it. The MARKABLE option specifies whether the cards in this deck (or this card if specified as a card option) can be bookmarked or not. Typically, bookmarking should be disabled for decks that are returned as a result of a transaction or other URL that has side-effects. If bookmarking is enabled, the transaction or side-effect could be repeated when the URL is invoked again by the user agent. Specifying the MARKABLE=TRUE enables bookmarking. The default is FALSE.
MARKABLE=TRUE on a deck implies PUBLIC=TRUE on the deck.
card ::= display-card | nodisplay-card | choice-card | entry-card
A card is one of four types: DISPLAY, NODISPLAY, CHOICE, and ENTRY. Each type is described in a section below.
card-options ::= o-name | o-title | o-bookmark | o-markable
All card types can have the above options.
o-name ::= name = identifier
The optional NAME option gives a name to the card. If a card has a name, then it can be referred to as a fragment in a destination.
o-title ::= title = value-with-vars
The TITLE option specifies the title of the card. If no TITLE option is specified, the first text line of the card is used as the title. The title is used in the following ways:
o-bookmark ::= bookmark = destination
The BOOKMARK option specifies the URL to use when bookmarking the card. The default is the URL of the current card. This option is used if you want to force the bookmark to go to another card (like a NODISPLAY card that sets up variables) instead of the current card.
display-card ::= display-header display-content display-footer
display-header ::= <DISPLAY ol(display-options) >
display-options ::= card-options
display-content ::= { action }* formatted-text
display-footer ::= </DISPLAY>
DISPLAY cards give information for the user to read. See "Formatted Text" below for a full description of the format of information that can be displayed. DISPLAY cards may also contain actions. These override any actions specified at the deck level.
<DISPLAY>
<ACTION TYPE=ACCEPT LABEL="Done">
You just won the lottery!
</DISPLAY>
nodisplay-card ::= nodisplay-header nodisplay-content nodisplay-footer
nodisplay-header ::= <NODISPLAY ol(nodisplay-options) >
nodisplay-options ::= card-options
nodisplay-content ::= { action }*
nodisplay-footer ::= </NODISPLAY>
NODISPLAY cards do not give information for the user to read. Rather, they immediately execute the card's ACCEPT or PREV action. All other actions are ignored. The following table lists the actions taken depending on the manner in which the NODISPLAY card was invoked.
| Invoking Task | Action-Taken |
|---|---|
| TASK=GO | ACCEPT |
| TASK=RETURN or TASK=CANCEL and DEST=this card | ACCEPT |
| TASK=RETURN and caller's NEXT=this card | ACCEPT |
| TASK=CANCEL and caller's CANCEL=this card | ACCEPT |
| TASK=RETURN | PREV |
| TASK=PREV | PREV |
| TASK=CANCEL | PREV |
choice-card ::= choice-header display-content { entries } choice-footer
choice-header ::= <CHOICE ol(choice-options) >
choice-options ::= card-options | o-method | o-key | o-ikey | o-default |
o-idefault
entries ::= { choice-entry }+
choice-footer ::= </CHOICE>
CHOICE cards let users pick from a list of choices. The initial display content is shown to the user, followed by the choices. Each choice can have one line of formatted text (which may be wrapped by the user agent if too long).
<CHOICE KEY=name>
Choose a name:
<CE VALUE=John>John Doe
<CE VALUE=Jane>Jane Dove
</CHOICE>
o-method ::= method = method-type
method-type ::= number | alpha
How the choices are displayed and chosen is based on the METHOD option. This option is a hint only, and can be disregarded by the user agent. The NUMBER method indicates that the user agent should number the list and should allow quick selection of a choice entry by number, if possible. The ALPHA method indicates that the user agent should not number the list and should allow quick selection of a choice entry based on the contents of the text, if possible. For example, with the ALPHA method, the choice entries might be selected by entering the first letter(s) of the entry. With both the NUMBER and ALPHA method, the user agent should not reorder the entries. If not specified, the default is METHOD=NUMBER.
o-key ::= key = identifier
o-default ::= default = value-with-vars
The KEY option, if present, indicates the name of the variable to be set to the entry value when an entry is picked. The value of the variable comes from the choice entry (see below). An entry is picked when any action (ACCEPT, PREV, SOFT*) is selected.
The DEFAULT option indicates the default value of the variable named in the KEY option. When the card is entered, if the variable named in the KEY option is not set, it will be assigned the default value. If the variable already contains a value, the DEFAULT option is ignored.
o-ikey ::= ikey = identifier
o-idefault ::= idefault = value-with-vars
The IKEY option, if present, indicates the name of the variable to be set to the entry index when an entry is picked. The entry index is the position of the currently selected choice entry in the choice card. An index of 0 indicates that no choice entry is selected. The IDEFAULT option indicates the default selected entry. When the card is entered, if the variable named in the IKEY option is not set, it will be assigned the default selected entry. If the variable already contains a value, the IDEFAULT option is ignored. If the IKEY option is not specified, the IDEFAULT value will be applied every time the card is entered.
On entry into a choice card, the user agent selects the initial entry in the following way.
Once an entry is selected, the variable named by KEY is updated to the value of the entry.
choice-entry ::= choice-entry-header choice-entry-content choice-entry-footer
choice-entry-header ::= <CE ol(choice-entry-options) >
choice-entry-options ::= o-value | task-options
choice-entry-content ::= formatted-line
choice-entry-footer ::= { </CE> }
Each choice entry displays text to the user. A choice entry is a variant of the ACCEPT action in that you can specify task-options to be used if the ACCEPT action is taken while the choice entry is selected. In addition, a choice entry can specify a value to be assigned to the variable named in the CHOICE card's KEY option.
A choice-entry-footer is optional and is implied by a subsequent <CE> or </CHOICE> tag.
An example of choice entries with task options follows:
<CHOICE>
<CE TASK=GOSUB DEST="email.cgi">Email
<CE TASK=GOSUB DEST="fax.cgi">Faxes
<CE TASK=GOSUB DEST="weather.cgi">Weather Reports
</CHOICE>
o-value ::= value = value
If the VALUE option is present, it supplies the value of the variable named in the KEY option in the CHOICE element. The variable gets set when any action is selected.
entry-card ::= entry-header display-content entry-footer
entry-header ::= <ENTRY ol(entry-options) >
entry-options ::= card-options | o-key | o-default | o-format | o-noecho |
o-emptyok
entry-footer ::= </ENTRY>
ENTRY cards let users input an optionally formatted character string. The display-content is shown the user, followed by an area to input characters. The characters entered are constrained by the entry format. An example ENTRY card for a US phone number follows:
<ENTRY KEY=number FORMAT="\(NNN\) NNN\-NNNN">
Enter phone number:
</ENTRY>
The KEY option indicates the name of the variable in the current activity to be set by this entry. It is similar to the KEY option in CHOICE cards. The entry area is pre-loaded with the value of the variable, and the value of the variable will be set to the text in the entry area when any actions (ACCEPT, PREV, SOFT*, etc.) are taken.
If the entry card is entered with the variable named in the KEY option not set, the DEFAULT option will be used to initialize the variable. If no KEY option is specified, the entry area will be initialized with the DEFAULT option, if it exists. Note, if the text entry is formatted (see below), the DEFAULT option must conform to the format. If it does not conform to the format, the behavior of the user agent is undefined.
o-format ::= format = value
The FORMAT option specifies the format for user input entries. The string consists of format control characters and static text which is displayed in the input area. The format control characters specify the data expected to be entered by the user. The user agent should constrain user input so that no incorrect or unexpected values can be entered. The default format is "*M".
The format codes are:
| A | entry of any upper-case alphabetic character or punctuation |
| a | entry of any lower-case alphabetic character or punctuation |
| N | entry of any numeric character |
| X | entry of any upper-case alphabetic. numeric character, or punctuation |
| x | entry of any lower-case alphabetic. numeric character, or punctuation |
| M | entry of any MiXeD-cAsE alphabetic characters, numeric characters, or punctuation assuming first character is upper-case |
| m | entry of any MiXeD-cAsE alphabetic characters, numeric characters, or punctuation assuming first character is lower-case |
| *f | entry of any number of characters; f is one of the above format
codes and specifies what kind of characters can be entered
This format may only be specified once, and it must appear at the end of the format string. |
| nf | entry of n characters where n is from 2 to 9; f
is one of the above format codes and specifies what kind of characters can
be entered
This format may only be specified once, and it must appear at the end of the format string |
| \c | display the next character, c, in the entry field; allows quoting of the format codes so they can be displayed in the entry area |
o-noecho ::= noecho = boolean-value
The NOECHO option indicates whether this text entry should echo the characters entered or not. Typically, you set NOECHO=TRUE for password entry and the like. The default is NOECHO=FALSE.
o-emptyok ::= emptyok = boolean-value
The EMPTYOK option indicates whether this text entry will accept empty input even though a non-empty format string has been specified. Typically, you set EMPTYOK=TRUE for formatted entry fields that are optional. The default is EMPYTOK=FALSE.
formatted-line ::= { { line-format } {alignment-format} text-line }
formatted-text ::= formatted-line*
text-line ::= {text | variable | image | text-format | tab-format}*
Formatted text is what is shown to the user in most cards. Formatted lines are used for choice entries.
line-format ::= <WRAP> | <LINE>
::= <BR>
The BR element is used to separate multiple lines of text. The treatment of a line too long to fit on the screen is specified by the WRAP and LINE elements. If WRAP is specified, the line is word wrapped onto multiple lines. If LINE is specified, the line is not wrapped. The user agent must provide a mechanism to view entire non-wrapped lines. An example of this is horizontal scrolling. The WRAP and LINE elements imply a line break.
When the optional line-format element is not specified, a default is assumed. The default line-format is dependent on the context of the text element. Text in the display-content portion of DISPLAY, CHOICE and ENTRY cards will default to a WRAP mode. Text in the formatted line of a choice entry (CE) element will default to LINE mode.
alignment-format ::= <CENTER> | <RIGHT>
The alignment codes specify how the line is to be laid out. The line is either centered, left-justified, or right-justified. If not specified, all lines default to left-justified.
text-format ::= <B> | <I>
::= </B> | </I>
The <B> and <I> elements turn on bold and italic fonts, respectively. The </B> and </I> elements cancel the formatting. These need not be strictly nested. Redundant application and cancellation should be tolerated. Formatted-text and formatted-line elements start in plain mode (no bold or italic).
tab-format ::= <TAB>
The TAB element is used to create aligned columns. Rather than tab to specific character positions, the TAB element separates the text for each column. To ensure the narrowest display width, the user agent should determine the width of the column from the maximum width of the text (or images) in each line for each column. The extent of the columns is from the first line with TAB elements through the last contiguous line with TAB elements. Some lines may have fewer TAB elements than others, in which case they are assumed to have no text for the extra columns.
image ::= <IMG ol(image-options) >
image-options ::= o-alt | o-name | o-src
Images are treated as large words and are simply displayed as part of the text. The image data is kept in a separate data stream identified by URL or name.
o-src ::= src = destination
The SRC option specifies the URL for image. If the user agent supports images, it will download the image from the specified URL, and render it when the text is being displayed.
o-name ::= name = value-with-vars
The NAME option specifies an alternative, internal graphic representation for the image. This representation will be used if it exists, otherwise the image will be downloaded from the URL specified in the SRC option. This allows user agents to provide an internal set of generic images, (e.g., smile, sun, cloud, etc.).
o-alt ::= alt = value-with-vars
The ALT option specifies an alternative textual representation for the image. This representation will be used when the image can not be displayed, i.e. when the user agent does not support images, or the image data is not available.
action ::= <ACTION ol(action-options) >
action-options ::= o-type | o-label | o-image | task-options
The ACTION element binds a label, an optional image, and a task to the user agents navigational user interface. The actions are specified at an abstract level, and are identified as SOFT1 through SOFT8, ACCEPT, PREV, and HELP. When the action selected, the indicated task takes place.
Actions can be specified both for the deck as a whole and per card. When specified for the deck they remain in effect for the entire deck. When specified for a card, they temporarily override any deck actions while the card is visible. Note that the override is done independently for each action type (a card can override one action while letting the deck specify the rest).
The user agent will make a best effort to provide a user interface for SOFT1-SOFT8. If necessary, SOFTx actions can be ignored by the user agent if it is not possible to provide a user interface for them.
o-type ::= type = key
key ::= soft1 | soft2 | soft3 | soft4 | soft5 |
soft6 | soft7 |soft8 | accept | prev | help
The TYPE option specifies which navigational user-interface action the element applies to. The TYPE option is required.
o-label ::= label = value-with-vars
If the user agent is able to dynamically label the user interface actions (for example if it uses soft keys), the LABEL option is the text to display for that action. The user agent may truncate or ignore the label depending on the characteristics of its navigational user interface. To work well on a broad range of user agents, is suggested that labels be 6 characters long or shorter.
o-image ::= image = url
The IMAGE option is the URL of the image to display for the action, if supported by the user-agent.
Destinations are processed by the user agent in two phases. First, it parses the destination as a simple option value with variables:
destination ::= value-with-vars
url ::= value-with-vars
path ::= value-with-vars
Variable substitution is done in the first phase of processing.
Second, the user agent parses the destination as a URL.
destination ::= url { # fragment }
Destinations are used with GO and GOSUB tasks to indicate the next deck or card to download and display. Destinations conform to the URL specification defined in [RFC1808] and [RFC1738].
The fragment portion of the URL identifies which card in the deck to display. The name of the card (as specified in the NAME option) is used.
Actions and choice entries can specify tasks to be performed when the user selects them.
task-options ::= o-task | o-dest | o-vars | o-receive | o-retvals | o-next |
o-cancel | o-sendreferer | o-friend | o-clear | o-confirm |
o-data | o-number | o-go | o-call
o-task ::= task = task-type
task-type ::= go | gosub | prev | return |
cancel | post | call | noop
The TASK option specifies which task to perform. The other options provide the information needed to perform the task. The following table describes the tasks and lists the options required for each: Options in bold are required for that task.
| Task | Description | Options
(required if underlined) |
|---|---|---|
| GO | Display the specified HDML card. | dest, vars, sendreferer |
| GOSUB | Push a new activity on the activity stack, and display the specified HDML card. When the sub-activity returns, put the return values into the "receive" variables and go to the "next" URL. If the sub-activity cancels, go to the "cancel" URL. Setting FRIEND=TRUE indicates that the sub-activity is friendly and is allowed to override the NEXT and CANCEL options and to unset all of the current activity's variables. | dest, vars, sendreferer, friend, receive, next, cancel |
| PREV | Display the previous card in the activity history. If currently displaying the first card in the activity, perform a CANCEL. | |
| RETURN | Return to the calling activity with the specified return values. Go to
the URL in the previous activity's NEXT option. If it is not specified, go
to the calling card in the previous activity.
If the previous activity flagged the current activity with FRIEND=TRUE, DEST may be used to override which card to display next. Setting CLEAR=TRUE unsets all the previous activity's variables. |
retvals, dest, clear |
| CANCEL | Cancel the current activity. Go to the URL in the previous activity's
CANCEL option. If it is not specified, go to the calling card in the previous
activity.
If the previous activity flagged the current activity with FRIEND=TRUE, DEST may be used to override which card to display next. Setting CLEAR=TRUE unsets all the previous activity's variables. |
dest, clear |
| CALL | Place a phone call to the specified phone number if the user agent is running on a voice phone. | number |
| NOOP | Do nothing. This is primarily used to disable the default behavior of actions |
Some examples:
<ACTION TYPE=ACCEPT LABEL="Next" TASK=GO DEST="#card2">
<ACTION TYPE=ACCEPT LABEL="Search" TASK=GOSUB
DEST="search.cgi" RECEIVE="name"
NEXT="email.cgi?NAME=$name">
<ACTION TYPE=ACCEPT TASK=RETURN RETVALS="John Doe">
<ACTION TYPE=PREV DEST="#cancelShield">
<ACTION TYPE=SOFT1 LABEL="Cancel" TASK=CANCEL>
<CE TASK=CALL NUMBER="411">Directory Assistance
<ACTION TYPE=SOFT1 TASK=NOOP>
o-dest ::= dest = destination
The DEST option specifies the URL of the card to display or invoke in the GO, GOSUB, and sometimes RETURN and CANCEL tasks.
o-vars ::= vars = value-with-vars
The VARS option specifies the variables to set in the current (in the case of GO) or sub (in the case of GOSUB) activity. The variables are specified in URL query-string format. For example:
vars="var1=value1&var2=value2"
The values should be escaped according to URL escaping conventions. The user agent will unescape the VARS option before setting the value of the variables.
o-receive ::= receive = receive-list
receive-list ::= { ; }* identifier { ; { identifier } }*
When invoking a card with the GOSUB task, the RECEIVE option specifies the names of the variables to assign the return values to. Return values are positional. For example, if you want to put the third return value into "myvar", you can specify the following RECEIVE option:
receive=;;myvar
If the sub-activity returns fewer values than assigned in the RECEIVE option, the remaining named variables without values are cleared. Return values not assigned to variables are ignored.
o-retvals ::= retvals = retval-list
retval-list ::= value-with-vars { ; value-with-vars }
When returning from a sub-activity with the RETURN task, the RETVALS option specifies the values to return to the invoking activity. Return values are positional.
o-next ::= next = destination
When invoking a sub-activity with the GOSUB task, the NEXT option specifies the destination to go to after the sub-activity returns.
o-cancel ::= cancel = destination
When invoking a sub-activity with the GOSUB task, the CANCEL option specifies the destination to go to if the sub-activity is canceled.
o-sendreferer ::= sendreferer = boolean-value
The SENDREFERER option specifies whether the user agent should indicate the URL of the current deck (i.e. the referring deck) when requesting the DEST, NEXT, and CANCEL decks from a server. This allows a server to perform access control on URLs based on which decks are linking to them. The URL will be the smallest relative URL possible if it can be relative at all. For example, if SENDREFERER=TRUE, an HTTP based user agent will indicated the URL of the current deck in the HTTP "Referer" request header [RFC2068]. The default is SENDREFERER=FALSE.
o-friend ::= friend = boolean-value
The FRIEND option is used in the GOSUB task to indicate that the sub-activity is friendly. A friendly sub-activity is allowed to use the DEST and CLEAR options in RETURN and CANCEL tasks. The default is FRIEND=FALSE.
o-clear ::= clear = boolean-value
The CLEAR option is used in the RETURN and CANCEL tasks to unset all the calling activity's variables. The unsetting is done before the retvals are assigned to the variables listed in the calling action's RECEIVE option. This is only available to sub-activities that have been marked as friendly by the calling activity. If the sub-activity has not been marked as a friendly, this option is ignored. The default is CLEAR=FALSE.
o-number ::= number = value-with-vars
The NUMBER option specifies the phone number for a CALL task.
Variables are set as a side-effect of card navigation. The GO and GOSUB tasks can set variables using the VARS option. The GOSUB and RETURN tasks can set variables with the RECEIVE and RETVAL options.
When a variable is set, if the variable is already present, its value is replaced.
To substitute a variable into the deck, the following syntaxes are used:
variable ::= $ identifier
::= $( identifier { : conversion } )
conversion ::= n { oesc }
::= e { scape }
variable-text ::= variable | text
The value of variables can be converted into a different form as they are substituted. A conversion can be specified in the variable reference following the semi-colon. The following table summarized the current conversions:
| Conversion | Effect |
|---|---|
| noescape | Make no change to the value of the variable. |
| escape | URL escape the value of the variable. |
If no conversion is specified, the variable is substituted using the conversion format appropriate for the context. The ACCESSDOMAIN, ACCESSPATH, BOOKMARK, CANCEL, DEST, GO, IMAGE, NEXT, SRC, and VARS options default to escape conversion, otherwise no conversion is done. Context sensitive escape conversion can be disabled with specifying the noesc conversion after the variable identifier.
In order to include the '$' character in text, it must be explicitly escaped, for example:
&dol;
In order to include the '$' character in options that are supposed to be URL escaped (for example, VARS), it must be explicitly escaped using URL escape form, that is:
%24