This chapter provides reference information for WML 1.1 elements and attributes. The elements are listed in alphabetical order, with available attributes shown for each.
The <access> element specifies access control information for a WML deck. You must specify this element within the deck header along with any meta information for the deck (for more information, see <head> element and <meta> element). Each deck can have only one <access> element. All WML decks are public by default.
domain" path="path"/>
NOTE
For a detailed explanation and examples of how the domain and path attributes work together, see the UP.SDK Developer's Guide.
The <anchor> element anchors a task to a string of formatted text, often called a link. You can specify a link within any formatted text or image. When a user selects the link and presses ACCEPT, the device executes the task.
label">task text</anchor>
where task represents the action to perform when the user activates the link and text is the text the device will display to represent the link:
You must anchor one of the following task elements to a link: | |||
|
|
<go> <prev> <refresh> |
(see <go> element) | |
Devices typically set this text off from surrounding text, for instance, by enclosing it in square brackets (see example) or underlining it if the device can display bitmap images. | |||
The following WML defines the card shown in Figure 2-1.
wml"/>News</a><br/>wml"/>Sports</a>
Figure 2-1. Card containing links
NOTE
Note that the ACCEPT label changes depending on which link is selected.
This is the short syntax form for anchors. It uses the <a> tag instead of the <anchor> tag, and can only be used to define (implied) <go> tasks that require a URL specification:
The <b> element specifies bold text.
text</b>
where text is the text to display in bold font.
The following WML defines the card shown in Figure 2-2.
Figure 2-2. Card containing bold text
The <big> element specifies large font text.
text</big>
where text is the text to display in large font.
The <br/> element specifies a line break, i.e. causes the device to display the subsequent text or image on a new line.
<input> or <select> element, the UP.Browser displays the text you specify before the element definition as a user prompt for the item. If you define multiple <input> or <select> elements within a card, you cannot insert line breaks within that text--if you specify the <br> element in the text flow preceding these elements, the UP.Browser uses it as a break point for partitioning your fields into multiple screens. The net result is that only the last portion of your user prompt appears on the same screen as the entry field or selection list.
NOTE
Unlike HTML, all WML elements require the end-element character (/). Thus, to insert a line break in WML, you must specify <br/> rather than <br>
A WML deck consists of one or more <card> elements, each of which specifies a single interaction between the user and the device. Devices display a maximum of one card at a time--in some cases, however, a single card may appear as a series of screens. For information on related elements, see <template> element and <wml> element.
name" title="label" newcontext="boolean"true" onenterforward="url" onenterbackward="url"url">
content
where content represents the WML card definition and consists of one or more of the following elements:
You can specify any of the following elements in your card definition: | |||
|
|
<onevent> <timer> <do> <a> <fieldset> <img> <input> <select> <p> |
(see <onevent> element) (see <p> element | |
<card> element must be in the following order:
With the exception of the elements listed above, devices display these elements in the order in which you specify them.
Specifies a name for the card. The name acts as a fragment anchor for navigating to that card. For example, you can specify | |
Specifies a brief label for the card. The UP.Browser uses the label as the default bookmark name when the user bookmarks the card. Some devices might use it for other purposes, such as popup tooltips. Note: The UP.Browser does not display the title as part of the card content. The phone manufacturer may optionally display the title if there is sufficient screen real estate. The title attribute should be considered as a hint to the user and not as part of the card content. | |
Specifies whether the device should initialize the context whenever the user navigates to the card through a | |
Specifies the organization of card content (see Order options below). | |
Specifies the URL to open if the user navigates to this card through a | |
Specifies the URL to open if the user navigates to this card through a | |
Specifies the URL to open if a specified |
The ordered attribute lets you specify how the device will display multiple content items within a card.
True displays the items in a linear sequence (the default value). Use this setting for short forms containing (mostly) required fields. If a device cannot display all the items on one screen, it divides them into multiple screens based on:
<fieldset> elements (if any) (see <fieldset> element).
False allows users to navigate between items in any order. Use this setting for cards containing optional fields or items with no logical order. If a device cannot display all the items on one screen, it may display a summary card that uses the title attribute for each item to identify the available options. Users can navigate to individual items from the summary card (and then select an option or enter a value, depending on the item definition).
The following WML defines the deck shown in Figure 2-3.
Figure 2-3. Card navigation within a deck
The two sample cards shown in Figure 2-4 illustrate the relationship between the onenterforward attribute and the <onevent> element. In this case, specifying onenterforward as an attribute of the <card> element is exactly the same as specifying the <onevent> element with type="onenterforward"--both cards produce the same results.
Figure 2-4.
Equivalent methods for binding a <go> task to an event
Using the abbreviated form implicitly associates a <go> task with the event. The main reason to use the expanded form is to associate a <noop>, <prev> or <refresh> task instead (see <onevent> element for more information).
The <do> element associates a task with an element within the user interface (for example, a function key, graphically-rendered button, or voice-activated command). When the user invokes the user interface mechanism, the device performs the associated <do> element task.
type" label="label" name="name" optional="boolean">task
where task represents the action to perform when the user activates the specified interface mechanism:
You must bind one of the following task elements to the user interface mechanism: | |||
|
|
<go> <prev> <noop> <refresh> |
(see <go> element) | |
You can specify the following values for the type attribute (all types are reserved except where noted):
None of these type values imply a specific user interface mechanism. Some devices map each type to a physical key, while others map them to context-dependent gestures (for example, pressing or press-holding a jog shuttle). Thus, when designing your user interface, keep in mind that you cannot specify (or assume) the particular mechanism that a device will use.
NOTE
If you define multiple <do> elements of the same type in one card, you should specify the name attribute for each <do> element to uniquely identify each instance of the same type.
The <em> element specifies emphasized text.
text</em>
where text is the text to display in emphasized font.
The <fieldset> element allows you to group multiple text or input items within a card. Specifying one or more <fieldset> elements lets you control how the device presents card content in order to simplify user navigation.
label">content</fieldset>
where content represents the items to group together and consists of one or more of the following elements:
You can specify any of the following elements in a | |||
|
|
<fieldset> <input> <select> |
(a nested | |
You can also specify formatted text in a | |||
Devices display these elements in the order in which you specify them.
Specifies a brief label for the |
The <go> element is a task element that instructs the device to open a specified URL. If the URL specifies a particular card, the device displays that card. If the URL specifies a deck, the device displays the first card in that deck.
url" sendreferer="boolean" method="method"charset" data" value="value"/>content
where content represents the variables to set when opening the specified URL:
You can optionally specify one or more variables in a | |||
|
|
<setvar>
| (see <setvar> element) | |
<go> element is optional. If you do not specify any content, you must use the syntax <go attributes/> rather than <go attributes>content</go>.
Specifies whether the device should include the deck URL in the URL request. Specifying | |
Specifies the HTTP submission method. Specifying | |
Specifies the character encodings that your application can handle. The device uses this attribute to transcode data specified by the
The syntax for this attribute is a comma- or space-delimited list of IANA character sets. For example,
|
The following WML code illustrates the syntax for the <go> element:
The <head> element specifies information about the deck as a whole, including metadata and access control information.
head>content head>
where content represents deck-level header information:
You can optionally specify either of the following elements in a WML deck header: | ||||
|
|
<access> <meta> |
(see <access> element) | ||
The following example illustrates how to specify the maximum age of a deck. The WML definition includes a <meta> statement that uses cache-control within the <head> element
The <i> element specifies italic text.
text</i>
where text is the text to display in italic font.
The following WML defines the card shown in Figure 2-5.
Figure 2-5. Card containing italic text
The <img> element instructs the device to display an image within formatted text. Note that not all devices can display images.
NOTE
You cannot embed images inside <do> or <option> elements--in other words, you cannot use images as function key labels or menu items.
text" src="url" localsrc="icon" align="alignment"n" width="n" vspace="n" hspace="n"/>
Specifies the text to display if the device does not support images or cannot find the specified image. | |
The URL of the image to display. If you specify a valid icon for the | |
The name of a known icon. If the device cannot find the icon in ROM (Read-Only Memory), it attempts to retrieve it from the UP.Link Server. If you specify a valid icon (see Figure 2-6 for a list of icon names), the device ignores the | |
Specifies image alignment relative to the current line of text. | |
The UP.Browser software does not currently support this attribute. | |
The UP.Browser software does not currently support this attribute. | |
The UP.Browser software does not currently support this attribute. | |
The UP.Browser software does not currently support this attribute. |
The following WML deck generates the display shown in Figure 2-7:
localsrc="smileyface" src=""/>
Figure 2-7.
Card containing localsrc icon
NOTE
Some localsrc icons have different forms when displayed at different font sizes. Since you cannot control the display size, keep in mind that the appearance of these icons may vary slightly on different devices.
The <input> element lets the user enter text which the device assigns to a specified variable. You can, if desired, also specify a default value for the entry.
text variable" title="label" type="type"value" default="default" format="specifier"boolean" size="n" maxlength="n" tabindex="n"/>
where text represents the text and/or image the device will display to prompt the user for entry.
The name of the variable in which the device stores the text entered by the user. If the variable has no value, the device sets it to the value specified for the
When the device displays the | |
Specifies a brief label for the input item. Some devices use the label as a tooltip when displaying the input field. Others might use it as a label for a user interface mechanism that lets the user navigate to the item. For example, if a device cannot display all card content on one screen and | |
Specifies how the device should display text the user enters. Specifying | |
This attribute is identical in syntax and behavior to the | |
A string specifying the default value for the variable specified by the
If the
If you specify a value that does not conform to the format specified by the | |
Specifies a data format that the user entry must match (see Specifying a format mask below). If you omit this attribute, the device assumes | |
Specifies whether the user can leave the field blank. Specifying | |
The UP.Browser software does not currently support this attribute. | |
Specifies the maximum number of characters the user can enter. If you do not specify the | |
The UP.Browser software does not currently support this attribute. |
You can specify the following values for the format attribute:
format="3X" lets the user enter a maximum of three symbolic, numeric, or uppercase alphabetic characters.
*) before the character tag--for example, format="*a" lets the user enter any number of symbolic or lowercase alphabetic characters.
The <meta> element provides meta information for a WML deck. This element is specified within the deck header along with any access control information for the deck (for more information, see <access> element and <head> element). Note that not all devices support every meta information type.
property content="value" scheme="format"/>
The 3.1 UP.Browser supports the following meta information types.
Like conventional Web browsers, the UP.Phone has a memory cache. It caches each deck that the user visits in order to quickly redisplay it without requesting it from the UP.Link Server again. The length of time that a device keeps a deck in cache is called the time to live (TTL). The default UP.Phone TTL is 30 days (or until memory is exhausted). If a deck contains time-sensitive information, you can specify a shorter TTL so that the device will reload the deck from the server more frequently. The following example illustrates how to use a <meta> statement to set the TTL:
The max-age parameter specifies the time (in seconds) to cache the deck. The example above instructs the device to drop the deck from the cache after 1 hour (3600 seconds). To determine the right TTL for a deck, you should balance the time-sensitivity of the information with the degradation in response time caused by reloading information from the server. Setting max-age to zero causes the UP.Browser to reload the deck every time the user navigates to it in a forward direction; however, if the user navigates back to the deck, the UP.Browser displays the card from the information in cache.
UP.Phone bookmarks are similar to conventional Web browser bookmarks. When a user bookmarks a card, the UP.Browser creates a bookmark that consists of two items:
title attribute within the <card> definition (see <card> element).
Because all decks are now bookmarkable by default, the markable <meta> element is only used to turn off bookmarking for a deck. The syntax for the statement is as follows:
When a user bookmarks a card, the UP.Browser automatically sets the bookmark URL to the URL for the deck. If you want to use a different URL, you can specify another <meta> element in the deck header using the following syntax:
url"/>
where url is the URL you want to use for the bookmark.
The <noop> element is a task element that instructs the device to do nothing, i.e. "no operation." This element is useful for overriding deck-level <do> elements, called shadowing (see the UP.SDK Developer's Guide for more information on shadowing).
The <onevent> element associates a state transition, or intrinsic event, with a task. When the intrinsic event occurs, the device performs the associated <onevent> task.
onevent type="type">task</onevent>
where task represents the action to perform when the intrinsic event occurs:
You can specify any one of the following actions for the | |||
|
|
<go> <prev> <noop> <refresh> |
(see <go> element) | |
You can specify the following values for the type attribute:
| type value | Perform task if ... |
|---|---|
|
onpick
|
User selects or deselects an |
|
onenterforward
| |
|
onenterbackward
|
User navigates to a card through a |
|
ontimer
|
A specified |
The <optgroup> element allows you to group multiple <option> (or nested <optgroup>) elements within a card. Creating option groups lets you specify control information about how the device should present the card content.
label">content</optgroup>
where content represents one or more of the following:
|
|
<optgroup> <option> |
(a nested | |
Devices display these elements in the order in which you specify them.
The <option> element specifies a particular choice within a <select> element.
option title="label" value="value" onpick="url">content option>
where content represents the text the device will display to represent the particular selection item and the action to perform if the user selects it:
You can optionally specify the following element in your item definition: | |||
|
|
<onevent>
| (see <onevent> element) | |
The device displays this text to represent the selection item. | |||
In the following example, selecting an item sets the variable color to the value associated with that item (i.e. 1, 2, 3, or 4).
The <p> element specifies a new paragraph and has alignment and line-wrapping attributes.
"alignment" mode="wrapmode">
The <postfield> element defines name/value pairs that are passed to the HTTP server receiving the <go> request. See the <go> element for an example of the <postfield> element's use in WML.
"name" value="value"/>
The <prev> element is a task element that instructs the device to remove the current URL from the history stack and open the previous URL. If no previous URL exists on the history stack, specifying <prev> has no effect.
content</prev>
where content represents the variables to set when opening the previous URL:
You can optionally specify one or more variables in a | |||
|
|
<setvar>
| (see <setvar> element) | |
<prev> element is optional. If you do not specify any content, you must use the syntax <prev/> rather than <prev>content</prev>.
The following WML illustrates a <prev> element that does not contain any content.
Figure 2-8.
Card with ACCEPT key bound to <prev> task
The <refresh> element is a task element that instructs the device to refresh the specified card variables. The device also refreshes the display if any of those variables are currently shown.
refresh>content</refresh>
where content represents the variables to refresh:
You must specify at least one variable in a | |||
|
|
<var>
| (see <setvar> element) | |
The following WML builds on the example shown in Example by adding a "Clear" option that lets the user clear the First Name and Last Name fields in order to enter new search criteria. The code specifies a second <do> element that uses <refresh> to reset the first and last variables to NULL when the user presses the OPTIONS key. Figure 2-9 illustrates how the card appears on the device.
Figure 2-9.
Card with OPTIONS key bound to <refresh> task
NOTE
You can use the <refresh> element to set variables to any values, not just to "reset" them to NULL as shown in this example.
The <select> element specifies a list of options from which the user can choose. You can specify either single- or multiple-choice <select> elements.
text label" multiple="boolean" name="variable"default" iname="index_var" ivalue="default"n">content
where text represents the text and/or image the device will display to prompt the user for selection and content represents the list of items from which to choose. You can define selection content using one or more of the following elements:
You can specify either of the following elements in a | |||
|
|
<optgroup> <option> |
(not currently supported by the UP.Browser) | |
Devices display these elements in the order in which you specify them.
Specifies a brief label for the | |
The name of the variable in which the device stores the value(s) associated with the option(s) chosen by the user. The value associated with each option comes from the
The value(s) in the specified variable determine the default selection(s) when the device displays the In the case of multiple selections, the values are stored as a semicolon-separated list (see example). | |
A string specifying the default value(s) for the variable specified by the
If the | |
Identical to the
| |
Identical to the | |
The UP.Browser software does not currently support this attribute. |
In the following example, "Dog" and "Cat" are the default selections if the variable i has no value when the device displays the card. Choosing "Cat" and "Horse" sets the variable x to the value "C;H" and the variable i to the value "2;3".
The <setvar> element sets a variable to a specified value when the device executes a <go>, <prev>, or <refresh> task.
var name="name" value="value"/>
The <small> element specifies small font text.
small>text</small>
where text is the text to display in small font.
The <strong> element specifies strongly emphasized text.
strong>text</strong>
where text is the text to display in strongly emphasized font.
The <table> element allows you to specify columnar format. You can control the overall alignment of the table, but not the alignment of individual cells. WML tables are similar to HTML tables but with fewer capabilities.
When defining a table, you have to declare the number of columns, followed by some content. The content can include empty rows and columns.
<table title="name" align="left|right|center" columns="number
of columns">
...row and data declarations
</table>
The <td> element is used as a container to hold a single table cell data within a table row. Table data cells may be empty. The user agent should do a best effort to deal with multiple line data cells that may result from using images or line breaks.
content</td>
where content represents text inside the table cell, or the <img> or <anchor> elements.
You can specify either of the following elements in a | |||
|
|
<img> <anchor> |
(see <img> element) | |
The <tr> element is used as a container to hold a single table row. Table rows may be empty, in other words, all cells are empty.
content</td>
where content represents text inside the table cell, or the <img> or <anchor> elements.
A WML deck may contain a <template> element that defines deck-level event bindings, i.e. characteristics that apply to all cards in the deck. You can override these characteristics for a particular card by specifying the same event bindings within the <card> definition (see <card> element).
url" onenterbackward="url"url">content
where content represents the general action to take when particular events occur:
You can specify either of the following elements in a template definition: | |||
|
|
<do> <onevent> |
(see <do> element) | |
Specifies the URL to open if the user navigates to a card through a | |
Specifies the URL to open if the user navigates to a card through a | |
Specifies the URL to open if a specified |
The <timer> element provides a method for invoking a task automatically after some period of user inactivity. Any task or user action that activates the card starts the timer, and executing any task element stops it. You can only associate one task per timer, and you can only define one timer per card.
timer name="variable" value="value"/>
The following example illustrates how a timer can initialize and reuse a counter. The device resets the timer to the value of the time variable each time the user navigates to the card. If time has no value, the device sets the timer to 5 seconds. When the timer expires, the device automatically displays the second card in the deck.
The <u> element specifies underlined text.
text</u>
where text is the text to display in underlined font.
The <wml> element specifies a WML deck.
wml xml:lang="lang">content
where content represents the WML elements that define the actions of the deck.
Specifies the natural or formal language for the WML document. Specifying the The UP.Browser software does not currently support this attribute. |