This chapter provides reference information for WML 1.1 elements and attributes, and Openwave extensions to WML. The elements are listed in alphabetical order, with available attributes shown for each, and required attributes in bold.
NOTE
The Openwave extensions to WML are indicated by
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.
<a href="url" <!-- required --> title="label">
...any valid combination of <text>, <br/> and <img> elements
</a>
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> and <meta>). Each deck can have only one <access> element. All WML decks are public by default.
<head>
<access domain="domain" path="path"/>
...
</head>
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.
<anchor title="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:
<anchor> elementThe following WML defines the card shown in Figure 2-1.
<wml>
<card>
<p>
Some links:<br/>
<anchor title="Link1"><go href="d1.wml"/>News</anchor><br/>
<anchor title="Link2"><go href="d2.wml"/>Sports</anchor>
</p>
</card>
</wml>
The <b> element specifies bold text.
<b>text</b>
where text is the text to display in bold font.
<b>elementThe following WML defines the card shown in Figure 2-2.
<wml>
<card>
<p>
Press <b>OK</b> to go to the next screen.
</p>
</card>
</wml>
The <big> element specifies large font text.
<big>text</big>
where text is the text to display in large font.
IMPORTANT Support for this element is available when using version 4.0 or higher of the UP.Browser .
The <br/> element specifies a line break. For example, it causes the device to display the subsequent text or image on a new line.
IMPORTANT
When you define an <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.
<br/>
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> and <wml>.
<wml>
<card id="name" title="label" newcontext="boolean"
ordered="true" onenterforward="url" onenterbackward="url"
ontimer="url">
content
</card>
</wml>
where content represents the WML card definition and consists of one or more of the following elements:
IMPORTANT
The contents of a <card> element must be in the following order:
<onevent>
<timer>
<do>
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:
field groupings specified by one or more <fieldset> elements (if any) (see <fieldset>).
individual fields (with the text preceding each item definition used as a prompt)
<card> elementThe following WML defines the deck shown in Figure 2-3.
<wml>
<card>
<do type="accept">
<go href="#card2"/>
</do>
<p>
Press OK to display the next screen.
</p>
</card>
<card id="card2">
<p>
This screen displays Card 2.
</p>
</card>
</wml>
<go> task to an eventThe 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.
<go> task to an eventUsing 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> for more information).
The <catch> element specifies an exception handler that can process an exception passed by a throw task. Parameters sent with the exception are received with the <receive> element.
An onthrow event occurs when the exception is caught and can be bound to a task. The onthrow event can be handled with the onthrow attribute or by embedding an <onevent> inside the <catch> element.
A <spawn> element cannot contain more than one <catch> element with the same name.
<catch name="error#1" onthrow="/displayError">
<receive name="Msg"/>
</catch>
<catch> elementThe following example illustrates the use of the <catch> element in a stock trading application:
<?xml version="1.0"?>
<!DOCTYPE wml PUBLIC "-//PHONE.COM//DTD WML 1.1//EN"
"http://www.phone.com/dtd/wml11.dtd" >
<wml>
<card id="stock">
<do type="accept" label="Next">
<spawn href="#order">
<catch>
<receive name="status"/>
</catch>
<receive name="status"/>
</spawn>
</do>
<p>
Stock Trade Example<br/>
$(status)
</p>
</card>
<card id="order">
<do type="accept" label="Order">
<spawn href="#confirm" onexit="?">
<receive name="status"/>
</spawn>
</do>
<do type="options" label="Prev">
<exit>
<send value="Status: No Trade"/>
</exit>
</do>
<p>
Stock Order: <br/>
Stock : PHCM <br/>
Shares : 100 <br/>
</p>
</card>
<card id="confirm">
<do type="accept" label="Yes">
<exit>
<send value="Status: Completed"/>
</exit>
</do>
<do type="options" label="Cancel">
<throw name="onerror">
<send value="Status: Canceled"/>
</throw>
</do>
<p align="center">
<b>*** Confirm ***<br/>
Stock Order <br/>
</b>
</p>
</card>
</wml>
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.
IMPORTANT
The <do> element has been extended to support the specification of images as <do> element labels. This is specified with an <img> element embedded inside a <do> element. For example:
<do type="accept">
<go href="/foo"/>
<img src="img" localsrc="OK" alt="OK"/>
</do>
If the phone supports images, the localsrc, src and alt are used, in that order. If the phone does not support images, alt specifies the label.
If an <img> element is specified, the label attribute on <do> is ignored. If <img> is not specified, the label attribute on the <do> element is used.
<do type="type" label="label" name="name" optional="boolean">
task
</do>
where task represents the action to perform when the user activates the specified interface mechanism:
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. When defining multiple <do> elements, the OPTIONS softkey is labeled "menu," which provides a menu that includes all <do> elements typed accept or options.
The <em> element specifies emphasized text.
<em>text</em>
where text is the text to display in emphasized font.
IMPORTANT Support for this element is available when using version 4.0 or higher of the UP.Browser .
The <exit> element declares an exit task, indicating that the current context should be terminated. Values may be sent to the parent context with an embedded <send> element. The exit task causes the current context to be destroyed, including any variable and history state contained in the context.
For example, the following will terminate the current context, and returns control to the parent context.
<exit>
<send value="393"/>
<send value="$X"/>
</exit>
NOTE See <spawn> for example code.
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.
<fieldset title="label">content</fieldset>
where content represents the items to group together and consists of one or more of the following elements:
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.
<go href="url" sendreferer="boolean" method="method"
accept-charset="charset"
<postfield name="data" value="value"/>
content
</go>
where content represents the variables to set when opening the specified URL:
|
|
You can optionally specify one or more variables in a
|
IMPORTANT
Unlike other WML elements that have content, specifying content for the <go> element is optional. If you do not specify any content, you must use the syntax <go attributes/> rather than <go attributes>content</go>.
|
|
Required. The URL to open. |
|
|
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,
|
<go> elementThe following example illustrates the syntax for the <go> element:
<wml>
<card title="Employee" ordered="true">
<do type="ACCEPT" label="Find">
<go method="post" href="?next=list">
<postfield name="next" value="list"/>
<postfield name="L" value="$last"/>
<postfield name="F" value="$first"/>
</go>
</do>
<p>
Partial First Name:
<input title="First Name" name="first"/>
Partial Last Name:
<input title="Last Name" name="last"/>
</card>
</p>
</wml>
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:
<head> elementThe 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:
<wml>
<head>
<meta http-equiv="Cache-Control" content="max-age=3600"
forua="true"/>
</head>
<card>
...
...
</card>
<card>
...
...
</card>
</wml>
The <i> element specifies italic text.
<i>text</i>
where text is the text to display in italic font.
<i> elementThe following WML defines the card shown in Figure 2-5.
<wml>
<card>
<p>
<i>Red</i>, <i>blue</i>, and <i>yellow</i> are primary colors.
</p>
</card>
</wml>
The <img> element instructs the device to display an image within formatted text. Note that not all devices can display images.
NOTE
The <do> and <option> elements have been extended by Openwave to support the specification of images--a feature unavailable in WAP-only WML. This is specified with an <img> element embedded inside a <do> or <option> element.
<img alt="text" src="url" localsrc="icon" align="alignment"
height="n" width="n" vspace="n" hspace="n"/>
|
|
Required. Specifies the text to display if the device does not support images or cannot find the specified image. |
|
|
Required. 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. |
|
|
Specifies the amount of space to the left and right of the image. The default setting is zero. |
<img> elementThe following WML deck generates the display shown in Figure 2-7:
<wml>
<card>
<p>
Here's a smiley:
<br/><img alt=":-)" localsrc="smileyface" src=""/>
</p>
</card>
</wml>
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.
text
<input name="variable" title="label" type="type"
value="value" format="specifier"
emptyok="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.
|
|
Required. The name of the variable in which the device stores the text entered by the user. 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 |
|
|
Specifies the value of the variable named in the If the |
|
|
A number (0-9) that appears on the left side of the screen next to the link. If the user presses the corresponding key on the phone keypad, the phone executes the task defined by the link. We recommend that you number the links in the order in which they appear. |
|
|
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:
To limit the number of characters users can enter, you can specify a single digit number before the character tag--for example, format="3X" lets the user enter a maximum of three symbolic, numeric, or uppercase alphabetic characters.
To let users enter an unlimited number of characters, specify an asterisk (*) before the character tag--for example, format="*a" lets the user enter any number of symbolic or lowercase alphabetic characters.
<input> element<wml>
<card>
<p>
First Name:
<input name="fname" maxlength="15" /> <br/>
Last Name:
<input name="lname" maxlength="15" /> <br/>
State:
<input name="state" maxlength="2" emptyok="true"
value="CA" /> <br/>
Zipcode:
<input name="zipcode" maxlength="10" /> <br/>
Password:
<input name="password" maxlength="8" type="password"
/>
</p>
</card>
</wml>
The <link> element specifies a relationship between the containing deck and another document. This element must exist inside the <head> element.
<wml>
<head>
<link href="/next" rel="next"/>
</head>
. . .
</wml>
<link> elementThe following example demonstrates how to pre-load WML pages into the UP.Browser cache using the <link> element. This can provide a faster user experience while navigating. If the user clears and views the cache before loading the contents.wml file, they will see no URLs present in the cache. After contents.wml is loaded, then if the user views the cache again, they will see contents.wml, chap1.wml, chap2.wml and appendix.wml all in cache. Subsequent navigation to chap1, chap2 & appendix all result in a faster view because of cache hits.
CONTENTS.WML
<?xml version="1.0"?>
<!DOCTYPE wml PUBLIC "-//PHONE.COM//DTD WML 1.1//EN"
"http://www.phone.com/dtd/wml11.dtd" >
<wml>
<head>
<link href="chap1.wml" rel="next"/>
<link href="chap2.wml" rel="next"/>
<link href="appendix.wml" rel="next"/>
</head>
<card id="main">
<p>
Table of Contents:
<a href="chap1.wml" title="CHAP1">Chapter1</a><br/>
<a href="chap2.wml" title="CHAP2">Chapter2</a><br/>
<a href="appendix.wml"
title="APPND">Appendix</a><br/>
</p>
</card>
</wml>
CHAP1.WML
<?xml version="1.0"?>
<!DOCTYPE wml PUBLIC "-//PHONE.COM//DTD WML 1.1//EN"
"http://www.phone.com/dtd/wml11.dtd" >
<wml>
<head>
<link href="contents.wml" rel="next"/>
<link href="chap2.wml" rel="next"/>
</head>
<card id="main">
<do type="accept" label="CHAP2">
<go href="chap2.wml"/>
</do>
<do type="options" label="TOP">
<go href="contents.wml"/>
</do>
<p>Chapter 1</p>
</card>
</wml>
CHAP2.WML
<?xml version="1.0"?>
<!DOCTYPE wml PUBLIC "-//PHONE.COM//DTD WML 1.1//EN"
"http://www.phone.com/dtd/wml11.dtd" >
<wml>
<head>
<link href="contents.wml" rel="next"/>
<link href="appendix.wml" rel="next"/>
</head>
<card id="main">
<do type="accept" label="APPDX">
<go href="appendix.wml"/>
</do>
<do type="options" label="TOP">
<go href="contents.wml"/>
</do>
<p>Chapter 2</p>
</card>
</wml>
APPENDIX.WML
<?xml version="1.0"?>
<!DOCTYPE wml PUBLIC "-//PHONE.COM//DTD WML 1.1//EN"
"http://www.phone.com/dtd/wml11.dtd" >
<wml>
<head>
<link href="contents.wml" rel="next"/>
</head>
<card id="main">
<do type="accept" label="TOP">
<go href="contents.wml"/>
</do>
<p>
Appendix
</p>
</card>
</wml>
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> and <head>). Note that not all devices support every meta information type.
<head>
<meta http-equiv="Cache-Control" content="max-age=time"
forua= true />
...
</head>
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:
<meta http-equiv="Cache-Control" content="max-age=3600"
forua= true/>
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.
The UP.Browser now performs "if-modified-since" content negotation with the HTTP server, but only after a deck's TTL has expired. Decks may now specify "no-cache" in the Cache-control <meta> element, which is equivalent to "max-age=0." Decks may also specify "must-revalidate" in the Cache-control <meta> element, which forces the UP.Browser to revalidate the deck's TTL, even if the user navigates to the deck in the backward direction. Finally, if the Cache-control <meta> tag is not defined in the WML deck, the browser may derive the deck's TTL from the HTTP cache headers, based on the HTTP/1.1 caching model.
<meta http-equiv="Cache-Control" content="must-revalidate"
forua= true/>
<meta http-equiv="Cache-Control" content="no-cache"
forua= true/>
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:
A label that identifies the bookmark--this label comes from the title attribute within the <card> definition (see <card>).
The URL to open when the user selects the bookmark.
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:
<meta name="vnd.up.markable" forua="true" content="false"/>
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:
<meta name="vnd.up.bookmark" forua="true" content="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).
<noop/>
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 the following values for the type attribute:
| type value | Perform task if ... |
|---|---|
onpick
|
User selects or deselects an |
onenterforward
|
User navigates to a card through a |
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.
<optgroup title="label">content</optgroup>
where content represents one or more of the following:
|
|
You can specify any of the following elements:
|
Devices display these elements in the order in which you specify them.
IMPORTANT The UP.Browser software does not currently support this element.
The <option> element specifies a particular choice within a <select> element.
IMPORTANT
The <option> element has been extended) to allow an image in the <option> text flow. When including an image in the <option> element, the image attributes src and alt are both required. (see <img>). For example:
<option value="1">
<img src="/img1" localsrc="" alt="Choice 1"/>
</option>
<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:
|
|
|
The device displays this text to represent the selection item. |
<option> elementIn the following example, selecting an item sets the variable color to the value associated with that item (i.e. 1, 2, 3, or 4).
<wml>
<card>
<p>
Please select your favorite color:
<select name="color">
<option value="1">red</option>
<option value="2">blue</option>
<option value="3">green</option>
<option value="4">yellow</option>
</select>
</p>
</card>
</wml>
The <p> element specifies a new paragraph and has alignment and line-wrapping attributes.
<p align="alignment" mode="wrapmode">
content
</p>
The <postfield> element defines name/value pairs that are passed to the HTTP server receiving the <go> request. See the <go> for an example of the <postfield> element's use in WML.
<postfield name="name" value="value"/>
|
Required. A label that identifies the field. |
|
Required. A string specifying the default value for the variable specified by the |
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.
<prev>content</prev>
where content represents the variables to set when opening the previous URL:
|
|
You can optionally specify one or more variables in a
|
<prev> element<wml>
<head>
<meta forua="true" content="true"/>
</head>
<!--This is the first card-->
<card id="card1">
<onevent type="onenterforward">
<go href="#card2">
<setvar name="Var1" value="Telephone"/>
</go>
</onevent>
<do type="accept" label="MENU">
<go href="prevIndex.wml"/>
</do>
<p>
Card 1 <br/>
Var1 = $(Var1). <br/>
Click Menu to return to the test index.
</p>
</card>
<!--This is the second card-->
<card id="card2">
<p>
<do type="accept" label="PREV">
<prev>
<setvar name="Var1" value="32"/>
</prev>
</do>
Card 2 <br/>
Var1 = $(Var1). <br/>
Click PREV to go to Card 1.
</p>
</card>
</wml>
IMPORTANT
Unlike other WML elements that have content, specifying content for the <prev> element is optional. If you do not specify any content, you must use the syntax <prev/> rather than <prev>content</prev>.
<prev> element without contentThe following WML illustrates a <prev> element that does not contain any content.
<wml>
<card>
<do type="accept" label="Back">
<prev/>
</do>
<p>
Hello, Unwired World!
</p>
</card>
</wml>
ACCEPT key bound to <prev> task
The <receive> element is used to receive data sent from a child context. A <receive> element without a name attribute causes the value in the parameter block to be ignored.
When receiving a parameter block, <receive> elements assign a corresponding variable to each value in that parameter block. If there are insufficient values in the parameter block, each additional <receive> should be treated as if the parameter block contained an empty string in that position.
<receive name="X"/>
|
|
specifies the variable name. It is an error if the name attribute value is not a legal WML variable name. |
NOTE See <send> for example code.
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
|
<refresh> elementThe following WML builds on the example shown on page 23 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.
<wml>
<card title="Employee" ordered="true">
<do type="ACCEPT" label="Find">
<go method="post" href="?next=list">
<postfield name="NEXT" value="list"/>
<postfield name="L" value="$last"/>
<postfield name="F" value="$first"/>
</go>
</do>
<do type="OPTIONS" label="Clear">
<refresh>
<setvar name="first" value=""/>
<setvar name="last" value=""/>
</refresh>
</do>
<p>
Partial First Name:
<input title="First Name" name="first"/>
Partial Last Name:
<input title="Last Name" name="last"/>
</p>
</card>
</wml>
OPTIONS key bound to <refresh> task
The <reset> element causes all variables in the current context to be cleared. If a task element, <go>, <prev>, or <refresh> contains a <reset> element, the reset operation is performed when the task is executed. If the <catch> element contains a <reset> element, the operation is performed during the <throw> task processing.
<go href="/bar">
<reset/>
</go>
For example, if a <go> element includes a <reset>, all variables in the context would be unset as a result of executing the <go> task
<reset> element<?xml version="1.0"?>
<!DOCTYPE wml PUBLIC "-//PHONE.COM//DTD WML 1.1//EN"
"http://www.phone.com/dtd/wml11.dtd" >
<wml>
<card id="main">
<do type="accept" label="Get">
<refresh>
<setvar name="weather" value="Sunny"/>
<setvar name="temp" value="72"/>
<setvar name="wind" value="8 mph"/>
<setvar name="humidity" value="32%"/>
</refresh>
</do>
<do type="options" label="Clear">
<refresh>
<reset/>
</refresh>
</do>
<p>
Weather: $(weather) <br/>
Temp: $(temp) <br/>
Wind: $(wind) <br/>
Humidity: $(humidity)
</p>
</card>
</wml>
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
<select title="label" multiple="boolean" name="variable"
value="default" iname="index_var" ivalue="default"
tabindex="n">
content
</select>
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
|
Devices display these elements in the order in which you specify them.
|
|
Specifies a brief label for the |
|
|
Specifies whether the user can select multiple items. |
|
|
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. |
<select> elementIn 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".
<wml>
<card>
<p>
Please choose your favorite animals:
<select multiple="true" name="x" iname="i" ivalue="1;2">
<option value="D">Dog</option>
<option value="C">Cat</option>
<option value="H">Horse</option>
</select>
</p>
<do type="accept"><noop/></do>
</card>
</wml>
The <send> element specifies a single value to be included in a parameter block.
The UP.Browser creates a parameter block with a single entry for each <send> element. Each entry is identified by its position in the parameter block, and the position is derived from the order of the <send> elements.
<send value="$X99"/>
<send value="$X100"/>
|
|
Specifies the data to be sent in this parameter block position. If not specified, the value defaults to an empty string. |
NOTE See <spawn> for additional example code.
<send> element<?xml version="1.0"?>
<!DOCTYPE wml PUBLIC "-//PHONE.COM//DTD WML 1.1//EN"
"http://www.phone.com/dtd/wml11.dtd" >
<wml>
<card id="main">
<do type="accept" label="Get">
<spawn href="#GetErrorCode">
<receive name="errorcode"/>
<receive name="errorname"/>
</spawn>
</do>
<do type="options" label="Clear">
<spawn href="#ClearErrorCode">
<receive name="errorcode"/>
<receive name="errorname"/>
</spawn>
</do>
<p>
Error Codes: <br/>
ErrorCode: $(errorcode) <br/>
ErrorName: $(errorname)
</p>
</card>
<card id="GetErrorCode">
<do type="accept"
<exit>
<send value="99"/>
<send value="Inv. Key"/>
</exit>
</do>
<p> Return Error Codes</p>
</card>
<card id="ClearErrorCode">
<do type="accept">
<exit>
<send value=""/>
<send value=""/>
</exit>
</do>
<p> Clear Error Codes</p>
</card>
</wml>
The <setvar> element sets a variable to a specified value when the device executes a <go>, <prev>, <spawn>, or <refresh> task.
<setvar name="name" value="value"/>
|
Required. The name of the variable to set. The device ignores the |
|
Required. The value to assign to the variable. |
The <small> element specifies small font text.
<small>text</small>
where text is the text to display in small font.
IMPORTANT Support for this element is available when using version 4.0 or higher of the UP.Browser .
The <spawn> element declares a spawn task, indicating the creation of a child context and invocation of a URL in that child context. If the URL names a WML card or deck, the card is displayed, and the URL becomes the basis for a new history stack in the child context.
When the child context is exited via the exit task, an onexit intrinsic event occurs. The onexit event can be handled with the onexit attribute or by embedding an <onevent> inside the <spawn> element. A spawn task can initialize the child context's variables with the <setvar> element, parameters returned from the child context are bound to variables with <receive> elements, and exceptions that occur in child contexts can be caught with the <catch> element.
The spawn element may also contain one or more <postfield> elements. These elements specify information to be submitted to the origin server during the request.
<spawn href="/child" onexit="/continue">
<setvar name="Name" value="Joe"/>
</spawn>
The <spawn> element creates a new child context, and invokes the "/child" URL in this new context. The child context initializes with the variable "Name" which evaluates to "Joe". When the child context exits, the onexit event occurs, resulting in a <go> task to the "/continue" URL.
href
|
Required. Specifies the destination URL. The URL of the card to display. |
|
|
The onexit event occurs when the child context is exited with an exit task. |
|
|
Specifies whether the device should include the deck URL in the URL request. Specifying |
|
|
Specifies the HTTP submission method. Specifying |
accept-
charset
|
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, To view the complete IANA Character Set registry, go to |
<spawn> element<?xml version="1.0"?>
<!DOCTYPE wml PUBLIC "-//PHONE.COM//DTD WML 1.1//EN"
"http://www.phone.com/dtd/wml11.dtd" >
<!-- Browse Headlines -->
<wml>
<card title="Headlines">
<do type="accept">
<spawn href="$(cardname:noesc)">
<!-- Catch all exceptions -->
<catch/>
</spawn>
</do>
<p mode="nowrap">
Financial News
<select name="cardname">
<option value="#n1">Stock Market Up</option>
<option value="#n2">Fed Raises Interest Rates</option>
<option value="#n3">Labor Strike Looming</option>
</select>
</p>
</card>
<card id="n1" title="Story">
<do type="accept" label="Skip">
<go href="#n2"/>
</do>
<do type="options" label="Done">
<exit/>
</do>
<p>
Stock Market UP
<br/>----
<br/>blah blah blah blah blah blah blah blah
</p>
</card>
<card id="n2" title="Story">
<do type="accept" label="Skip">
<go href="#n3"/>
</do>
<do type="options" label="Done">
<exit/>
</do>
<p>
Fed Raises Interest Rates
<br/>---
<br/>blah blah blah blah blah blah blah blah
</p>
</card>
<card id="n3" title="Story">
<do type="accept" label="Skip">
<go href="#n1"/>
</do>
<do type="options" label="Done">
<exit/>
</do>
<p>
Labor Strike Looming
<br/>---
<br/>blah blah blah blah blah blah blah blah
</p>
</card>
</wml>
The <strong> element specifies strongly emphasized text.
<strong>text</strong>
where text is the text to display in strongly emphasized font.
IMPORTANT Support for this element is available when using version 4.0 or higher of the UP.Browser .
The <table> element allows you to specify columnar format. 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>
IMPORTANT
The UP.Browser does not support the align attribute. Tables are left-justified regardless of the align attribute value specified.
<table> element<wml>
<card>
<p>
Prague <img localsrc="sun" alt="" src=""/>
</p>
<p mode="nowrap">
<table columns="2">
<tr><td><i>High</i></td>
<td><i>Low</i></td></tr>
<tr><td>53</td>
<td>42</td></tr>
</table>
Today: Mostly sunny and cool.
<br/>Tonight: Cold with chance of light rain.
</p>
</card>
</wml>
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.
<td>content</td>
where content represents text inside the table cell, or the <img> or <anchor> elements.
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.
<tr>
<td>content</td>
</tr>
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>).
<wml>
<template onenterforward="url" onenterbackward="url"
ontimer="url">
content
</template>
</wml>
where content represents the general action to take when particular events occur:
|
|
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 <throw> element declares a throw task, indicating that an exception should be raised. Values may be sent to the exception handler with <send> elements included in the throw. Throwing an exception terminates the current context and causes the context to be destroyed, including any variable and history state contained in the context.
If the parent context does not contain an exception handler (a <catch> element) that matches this exception, or a </catch> element, the parent context is terminated and the exception is re-thrown to that context's parent. This operation repeats until an exception handler is found or all parent contexts have been terminated. In the case where all contexts are terminated, the UP.Browser performs a reset to a predictable state. Typically, this clears the history stack and displays the home deck.
For example, the following throws an exception with the name "user input error". In addition, a parameter block is included specifying more information about the error.
<throw name="user input error">
<send value="Bad numeric value"/>
</throw>
name
|
Required. Specifies the name of the exception. This name is used to find the correct handler for the exception. The name attribute value is case sensitive. |
NOTE See <catch> for example code.
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"/>
<timer> elementThe 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.
<wml>
<card ontimer="#card2">
<timer name="time" value="50"/>
<p>
Hello, Unwired World!
</p>
</card>
<card id="card2">
...
...
</card>
</wml>
The <u> element specifies underlined text.
<u>text</u>
where text is the text to display in underlined font.
IMPORTANT Support for this element is available when using version 4.0 or higher of the UP.Browser .
The <wml> element specifies a WML deck.
<wml xml:lang="lang">
<card>
content
</card>
</wml>
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. |
<wml> element<wml xml:lang="en-us">
<card>
...
...
</card>
</wml>