Wireless Markup Language (WML) Tutorial

Defining Tasks

The do element is used to specify tasks, and may be applied to a card or a deck. Tasks are performed in response to some event, such as clicking a button. The implementation is user agent dependent. For example, a phone may provide an Options button, and a PDA may use a special key depending on the type of the task provided as an attribute of the do element. The following table shows the possible values for the type attribute.

Values for the type Attribute
Value Description
accept Positive acknowledgement, for example a button
delete Delete option, for example a button
help Help option, maybe context sensitive
options Provides a list of options, for example through a button
prev Provides a means of navigating to the previous card
reset Provides a means of resetting the device's current state
unknown No specific type defined, equivalent to type=""

The label attribute is used to provide a name for the task. The following example may be used to define a card to accept an instruction, with the label Announcements.

<do type="accept" label="Announcements">

Binding Tasks

For each do element, they must be a task bound to it. The following table lists the possible tasks that may be bound.

Binding Tasks
Task Syntax Description
go <go href="#somewhere"/> Used to specify a URI.
noop <noop/> No operation, does nothing. Used to override deck level tasks.
prev <prev/> Navigates to the previous card.
refresh <refresh>
  <setvar name="x" value="32"/>
</refresh>
Used to refresh the card's variables. At least one variable must be specified with the setvar element. The setvar element has two attributes, the name of the variable to set, and the value to set for the variable.

The go Element

The go element is used to specify a URI for a task. The following table lists the attributes that may be used with this element.

Attributes for the go Element
Attribute Description
href

A required attribute which specifies the URI to open.

<go href="#somecard"/>
method

Determines which HTTP submission method will be used. The possible choices are post and get. By default, the get method is used. However, if you specify a postfield, the post method will be used by default. The post method is useful if you're submitting non-ASCII data.

<go href="#somecard" method="post">
    <postfield name="start" value="$first"/>
    <postfield name="end" value="$last"/>
</go>

The postfield element is used to post fields to the HTTP server in name/value pairs.

The following example links to three other cards. The links have been specified as tasks, which has the advantage that the viewing area isn't taken up with links.

tasks.wml
<?xml version="1.0" encoding="iso-8859-1" ?>
<!DOCTYPE wml PUBLIC "-//WAPFORUM//DTD WML 1.1//EN"
    "http://www.wapforum.org/DTD/wml_1.1.xml">
<wml>
<card id="index" title="Welcome">
<do type="accept" label="First Card">
    <go href="#first"/>
</do>
<do type="accept" label="Second Card">
    <go href="#second"/>
</do>
<do type="accept" label="Third Card">
    <go href="#third"/>
</do>
<p align="center">
    Juicy Studio<br/>
    <img src="images/smile.wbmp" alt="Smile" width="20" height="20"/><br/>
    W@P
</p>
</card>
<card id="first" title="First Card">
<do type="prev" label="Back">
    <prev/>
</do>
<p>
    This is the first card.<br/>
</p>
</card>
<card id="second" title="Second Card">
<do type="prev" label="Back">
    <prev/>
</do>
<p>
    This is the second card.<br/>
</p>
</card>
<card id="third" title="Third Card">
<do type="prev" label="Back">
    <prev/>
</do>
<p>
    This is the third card.<br/>
</p>
</card>
</wml>

Output From Program

The following shows the output from the above script. In this example, the accept type has been rendered with an Options button on the device. When the options button is pressed, the three choices are displayed. When the card has been selected, the Back button has been rendered on the device.

The image shows the screen of a mobile phone with the output from the program.

 

Using Templates

The template element may be used to define event bindings for the whole deck rather than just a card. If a card defines a task of the same type, the card will take precedence over the template. The noop element may be used to disable something defined at deck level. The following table shows the attributes available for the template element.

Attributes for the Template Element
Attribute Syntax Description
onenterbackward <template onenterbackward="#somecard">
    <!-- Some task -->
</template>
Specifies the URL to go to if the user navigates to a card through the prev element
onenterforward <template onenterforward="#somecard">
    <!-- Some task -->
</template>
Specifies the URL to go to if the user navigates to a card through the go element
ontimer <template ontimer="#somecard">
    <!-- Some task -->
</template>
Specifies the URL to go to when a timer expires

The following example defines a template for a help option. The help card redefines the help task to a noop element, as it's not required in that card.

help.wml

<?xml version="1.0" encoding="iso-8859-1" ?>
<!DOCTYPE wml PUBLIC "-//WAPFORUM//DTD WML 1.1//EN"
    "http://www.wapforum.org/DTD/wml_1.1.xml">
<wml>
<template>
    <do type="help" label="Help">
        <go href="#help"/>
    </do>
</template>
<card id="index" title="Welcome">
<do type="accept" label="First Card">
    <go href="#first"/>
</do>
<do type="accept" label="Second Card">
    <go href="#second"/>
</do>
<do type="accept" label="Third Card">
    <go href="#third"/>
</do>
<p align="center">
    Juicy Studio<br/>
    <img src="images/smile.wbmp" alt="Smile" width="20" height="20"/><br/>
    W@P
</p>
</card>
<card id="first" title="First Card">
<do type="prev" label="Back">
    <prev/>
</do>
<p>
    This is the first card.<br/>
</p>
</card>
<card id="second" title="Second Card">
<do type="prev" label="Back">
    <prev/>
</do>
<p>
    This is the second card.<br/>
</p>
</card>
<card id="third" title="Third Card">
<do type="prev" label="Back">
    <prev/>
</do>
<p>
    This is the third card.<br/>
</p>
</card>
<card id="help" title="Help">
<do type="help">
    <noop/>
</do>
<do type="prev" label="Back">
    <prev/>
</do>
<p>
    Smile, press any button and hope for the best. Good luck!
</p>
</card>
</wml>

Output From Program

The following shows the output from the above script. When Options is selected, the Help now appears in the menu for all of the cards, except the help card. The cards first, second, and third now have an options menu which contains the Help option. Other user agents may use a seperate button.

The image shows the screen of a mobile phone with the output from the program.

In this sequence, the second card is chosen from the Options. The second card has an Options button, as the help is automatically assigned to it on this device.

The image shows the screen of a mobile phone with the output from the program.

The onevent Element

The onevent element is used to catch events. The event should be bound to one of tasks, go, noop, prev, or refresh. The onevent element has a type attribute which defines the type of event. The following table shows the types of event that are trappable.

Attributes of the onevent Element
Attribute Description
onenterbackward

Specifies the URL to go to if the user navigates to a card through the prev element

<onevent onenterbackward="#somecard">
    <!-- Some task -->
</onevent>
onenterforward

Specifies the URL to go to if the user navigates to a card through the go element

<onevent onenterforward="#somecard">
    <!-- Some task -->
</onevent>
onpick

Specifies the URL to go to if the user selects an option through a select element.

<onevent onpick="#somecard">
    <!-- Some task -->
</onevent>
ontimer

Specifies the URL to go to when a timer expires

<onevent ontimer="#somecard">
    <!-- Some task -->
</onevent>

You might also like...

Comments

About the author

Gez Lemon United Kingdom

I'm available for contract work. Please visit Juicify for details.

Interested in writing for us? Find out more.

Contribute

Why not write for us? Or you could submit an event or a user group in your area. Alternatively just tell us what you think!

Our tools

We've got automatic conversion tools to convert C# to VB.NET, VB.NET to C#. Also you can compress javascript and compress css and generate sql connection strings.

“Theory is when you know something, but it doesn't work. Practice is when something works, but you don't know why. Programmers combine theory and practice: Nothing works and they don't know why.”