Learning WML - Navigation, User Input, and Graphics

Wednesday Jul 24th 2002 by Steve Schafer

Do you want to develop for mobile devices? In this article, learn how to create advanced navigation as well as how to accept user input and display graphics using WML.

This series of articles describes how to provide Web content to mobile devices through WML (Wireless Markup Language). This article covers more advanced navigation, accepting user input, and displaying graphics. Future articles will cover advanced WML language, tips and tricks to provide content, and how to integrate other technologies such as PHP to make your pages more flexible.

Note: These articles cover WML version 1.1, which is supported by the majority of mobile devices in use today. The articles assume a working knowledge of HTML and general Web technologies, and further assume that you have read the previous article(s) in this series.

More Navigation Between Cards and Decks

In the previous article ("Learning WML - WML Tools and Coding Basics"), we covered basic navigation using <anchor> and <do> elements. These basic navigation constructs enable you to map links to the soft keys or place standard HTML-style hyperlinks into your cards. There are a few more useful navigation methods we should also cover.

Select Lists

The select list provides an easy way for the user to select between several predetermined values. Each value is enclosed within an <option> tag, much like an HTML list:

<select>     <option>First option</option>     <option>Second option</option></select>

Each option is automatically assigned a shortcut number, displayed next to it by the browser, as shown in the following figure.

Each <option> element is assigned a shortcut number which is displayed next to the element's text.

Image courtesy Openwave Systems Inc. (Openwave, the Openwave logo, Openwave SDK, Openwave SDK Universal Edition, Openwave SDK WAP Edition are trademarks of Openwave Systems Inc. All rights reserved.)

The user can either press the shortcut number associated with the option or use the standard navigation (arrow) keys to select the appropriate option and then press the Accept key.

Tip: The shortcut keys are only useful if you have 10 or fewer options, since there are only 10 numeric keys (0-9) that can be used to quickly select an option. If you have more than 10 options, consider adding a "More" option that displays the options in groups of 10 or fewer.

The "onpick" parameter can be used to select a deck/card to navigate to if the user selects that option. For example, the following code will navigate the user to the appropriate "color" card within the current deck:

<select>     <option onpick="#red">Red</option>     <option onpick="#green">Green</option>     <option onpick="#blue">Blue</option></select>

A full deck example follows:

<?xml version="1.0"?><!DOCTYPE wml PUBLIC "-//WAPFORUM//DTD WML 1.1//EN"    "http://www.wapforum.org/DTD/wml_1.1.xml"> <wml><card id="card1" title="Select example"><p><select>     <option title="Red" onpick="#red">Red</option>     <option title="Green" onpick="#green">Green</option>     <option title="Blue" onpick="#blue">Blue</option></select></p></card><card id="red" title="Red"><p>Your choice was Red.</p></card><card id="green" title="Green"><p>Your choice was Green.</p></card><card id="blue" title="Blue"><p>Your choice was Blue.</p></card></wml>

Tip: Notice the addition of the "title" parameter in each <option> tag. The text provided with this parameter is displayed as the Accept soft key's label when the option is selected.

We used the options to navigate to cards within the current deck. However, you could just as easily navigate to other decks or specific cards within those decks.


You can also set up navigation that is caused by a particular event. The <onevent> element provides several possible actions triggered by one or more intrinsic events.

The <onevent> tag has the following format:

<onevent type="type">     task</onevent>

The "type" can be one of the following:

Type Event
onpick User selects or deselects an <option> item.
onenterforward User navigates to a card in a forward manner (e.g., from a <go> or other link)
onenterbackward User navigates to a card in a backward manner (e.g., from a <prev> element or Back command)
ontimer A specified <timer> element expires

The "onenter" types can be used to display or omit particular information depending on how the user navigated to the card, or to force a refresh of dynamic information if the user reached the card by going backward (thereby getting the card from the cache and not a fresh copy from the server).

The "onpick" type is used when the <onevent> is nested within an <option> element to provide an action when the option is selected.

The "ontimer" type is used to provide a task at a particular time, independent of user actions (refreshing a page, moving to another page, etc).

The various tasks that can be used with the <onevent> element are described in the following table.

Task Use
<go> Navigates to a new card.
<prev> Navigates to the previous card.
<noop> Performs no task (no operation).
<refresh> Refreshes the current card's content.
<exit> Exits the current context. *
<spawn> Spawns a child task. *
<throw> "Throws" an exception that can be caught by an
optional <catch> element. *

* These tasks are specific to the Openwave browser. See the developer documentation at http://developer.openwave.com for more information.

The "ontimer" event can be used to display a splash screen (containing welcoming or copyright information), or to automatically return to a card after displaying an error. Its also very useful for refreshing a card to display up-to-date dynamic data.

In the following example, the deck displays a splash screen before the main menu:

<?xml version="1.0"?><!DOCTYPE wml PUBLIC "-//WAPFORUM//DTD WML 1.1//EN"    "http://www.wapforum.org/DTD/wml_1.1.xml"> <wml><card id="splash" title="Welcome!"><onevent type="ontimer">      <go href="#main" /></onevent><timer name="delay" value="50"/><p mode="wrap">Welcome to ACME Incorporated.</p></card><card id="main" title="Main Menu"><p>Main menu here...</p></card></wml>

Note: The <timer> element's value parameter is measured in tenths of a second, so our splash screen stays active for 5 seconds (50 tenths).

Tip: The <card> element includes an optional "ontimer" parameter, which alleviates the need for a separate <onevent> element. Using this parameter, the above example could be shortened as follows:

 . . .  <card id="splash" title="Welcome!" ontimer="#main"> <timer name="delay" value="50"/> . . . 

Accepting User Input

Although the forms capability of WML isn't as robust as standard HTML, the <input> element is very flexible and allows a variety of data to be accepted from the user.

The <input> element has the following minimal form:

<input name="variable_name" />

In this form, the element accepts user input and stores it in the variable specified. The input is freeform; that is, it is not constrained to any particular format (numeric, alphanumeric, etc.) or length--although most mobile browsers impose a length limit of 256 characters.

Note: A full discussion of WML variables is outside the scope of this article, but will be provided in the next article. For this exercise it is important to know that variables exist and can be set by <input> and <setvar> elements, among others. A variable can then be referenced by prefixing its name with a dollar sign ("$"), or using the preferred method of enclosing the name in parentheses and prefixing the whole structure with a dollar sign. For example, the variable "firstname" can be referenced as "$firstname" or "$(firstname)". When the variable is referenced, WML will substitute the variable's value for its reference.

The <input> element also supports the optional parameters shown in the following table.

titleSupplies a title for the element. Some devices display this title in the default Accept soft key label; others display it as "tooltip" text while the element is selected.
typeSet to "text" or "password," this parameter controls whether the text is displayed as it is entered or displayed in the browser's password character(s) (usually "*").
valueThe default value for the element. Note that if the variable specified in the "name" parameter already has a value, or if the value specified with this parameter doesn't conform to the specified "format" parameter, the value is ignored.
accesskeyDisplays the specified number (0-9) next to the element. The key can be used to quickly select the element.
formatSpecifies the format mask of the input. See the format section below for details on masking.
emptyokControls whether the element can be left empty. The valid values for this parameter are "true" (the default) or "false."
maxlengthMaximum length of the input, in characters.

Note: The "accesskey" parameter allows you to create a form of several input fields where the user can easily navigate between the fields. However, as the Openwave applications point out (http://developer.openwave.com), wizards that display card-sized chunks of data entry fields are much better received and make a better application design.

The "format" parameter's value is composed of a series of characters that provide a mask for the input. The following table describes the valid instructional characters for the format mask:

AAny symbol or uppercase alpha character (no numbers).
aAny symbol or lowercase alpha character (no numbers).
NAny number (no symbols or alphabetic characters).
XAny symbol, number, or uppercase alpha character (cannot be changed to lowercase alpha).
xAny symbol, number, or lowercase alpha character (cannot be changed to uppercase alpha).
MAny symbol, number, or alpha character; by default, the first character is uppercase.
mAny symbol, number, or alpha character; by default, the first character is lowercase.

The format mask can also include symbols, which will be displayed in their appropriate position in the input.

For example, to accept a phone number, including the area code, you could use this format mask:

format = "(NNN) NNN-NNNN"

When using the same character multiple times in a row, you can prefix the character with a number indicating how many times it repeats. Using this method, our phone number mask could be written like this:

format = "(3N) 3N-4N"

However, this format isn't as recognizable as a phone number mask.

Note: To specify an unlimited number of the same character, prefix the character with an asterisk (*).

A simple deck to accept a person's first name (up to 25 characters) and then greet the person by name would resemble the following listing:

<?xml version="1.0"?><!DOCTYPE wml PUBLIC "-//WAPFORUM//DTD WML 1.1//EN"    "http://www.wapforum.org/DTD/wml_1.1.xml"> <wml><card id="GetName" title="Get Name"><do type="accept">      <go href="#Hello"/>  </do>  <p>What is your first name?<input name="name" format="*M" maxlength="25" /></p></card><card id="Hello" title="Hello"><p>Hello, $(name)!</p></card></wml>

Notice that the <input> element uses the "M" format mask, supplying an uppercase letter as the default first character. The "maxlength" parameter constrains the input's length, despite the "*" in the mask.

The deck navigation in this example is controlled by a <do> element linked to the Accept key. In some devices the user will have to press the Accept key twice--once to exit the input element and another to trigger the navigation.

There are many useful things you can do with user-supplied input besides echo it back in other cards. The next article in this series will discuss several other uses for user input.

Graphics and Icons

The current generation of mobile devices includes very limited graphics capability. Most mobile browsers only support black-and-white bitmapped images, although a few recent browsers have added support for color and even animated formats (GIF, PNG, JPG). Some mobile gateways also perform on-the-fly conversions of graphics, most notably from BMP to WBMP.

Tip: Unless you are developing for a particular platform where you know the capabilities, use only small black-and-white WBMP graphics. Most graphics applications do not support the WBMP format, but several converters exist, including a Web-based converter at Teraflops (http://www.teraflops.com/wbmp/).

Note: Refrain from using graphics whenever possible; using graphics breaks the mobile application development rules of "fast" and "simple."

To create a graphic for mobile use you will need a graphics application that supports the WBMP format, or at least black-and-white bitmap format and a suitable converter. Drawing upon our earlier splash screen example, let's create a graphical logo for ACME.

To start, we need to choose a suitable size for the graphic. It's advisable to stick with a small size such as 100 x 100 pixels. The graphic shown in the following figure was created with the following steps (note that the options and procedure might differ in your graphics application):

  1. Create a new graphic, sized 80 x 80 pixels.
  2. Convert the graphic to black-and-white, or "line art."
  3. Select the appropriate background color (black or white) and fill the entire graphic.
  4. Use the text tool to create text in appropriate sizes and fonts (using the opposite color of the background).
  5. Save the results in GIF format.
  6. Use the online tool at Teraflops.com to convert the GIF to WBMP format.
  7. Upload the resulting graphic (acme.wbmp) to the Web server.

Tip: We advise using a graphics program that supports objects instead of straight bitmapped images. Graphics programs allow you to work with individual objectsmoving, sizing, etcbefore committing them to the electronic canvas.

The ACME Incorporated logo.

Images are added to WML cards using the <img> tag. This tag has the following syntax:

<img alt="alt-text" src="url" />

Note that the "alt" and "src" parameters are mandatory in all <img> tags. The <img> tag also supports the following optional parameters:

Parameter Use
localsrc Specifies an icon. (See the later section on icons.)
align Aligns the image relative to the current line of text. Supports "top," "middle," and "bottom."
height Specifies the exact height of the displayed image.
width Specifies the exact width of the displayed image.
hspace Specifies how much white space should be displayed at each side of the image (horizontal space).
vspace Specifies how much white space should be displayed above and below the image (vertical space).

Note: Not all mobile browsers support the sizing and spacing parameters.

Incorporating the logo into our previous splash screen example, we get the following result (see figure):

<?xml version="1.0"?><!DOCTYPE wml PUBLIC "-//WAPFORUM//DTD WML 1.1//EN"    "http://www.wapforum.org/DTD/wml_1.1.xml"> <wml><card id="splash" title="Welcome!" ontimer="#main"><timer name="delay" value="50"/><p mode="wrap" align="center">     Welcome to<br/>     <img alt="ACME Incorporated" src="acme.wbmp" /></p></card><card id="main" title="Main Menu"><p>Main menu here...</p></card></wml>

Our new splash screen.

Image courtesy Openwave Systems Inc. (Openwave, the Openwave logo, Openwave SDK, Openwave SDK Universal Edition, Openwave SDK WAP Edition are trademarks of Openwave Systems Inc. All rights reserved.)

Icons are very small graphics to be used as highlights or ornamentation. Most mobile browsers support at least a limited number of icons. For the purposes of this discussion we will use icons supported by the Openwave browser. A full list of these icons can be found in the WML Language Reference documents on the Openwave developer site (http://developer.openwave.com).

Icons are placed as graphics, using the <img> tag and its "localsrc" attribute, along with the appropriate icon number(s). For example, a smiley face is icon number 68; it would be placed in the contents of a card with the following tag:

<img alt=":-)" src="" localsrc="68" />

Note that the "alt" and "src" tags are mandatory, even if left blank.

Tip: When using icons for ornamentation, be sure to specify alternate text that can serve the same purpose or that resembles the icon.

Let's suppose that ACME is a travel agency. We could add an airplane icon to the bottom of the splash screen with this tag (see figure):

<img alt="airplane" src="" localsrc="168" />

Our new splash screen complete with airplane icon.

Image courtesy Openwave Systems Inc. (Openwave, the Openwave logo, Openwave SDK, Openwave SDK Universal Edition, Openwave SDK WAP Edition are trademarks of Openwave Systems Inc. All rights reserved.)

Tip: Because the WML language is fairly limited for emphasizing text, consider using icons such as triangles (icons 5-8) to draw attention to specific text. For example, this code is used to call attention to the fact that the user has reached the end of an article:

  <img alt="--" src="" localsrc="righttri1" />  End  <img alt="--" src="" localsrc="lefttri1" />

Next Time

The next article in this series will cover variables, passing values between decks, and beginning WMLScript coding.

About the Author

Steve Schafer is president and CEO of Progeny Linux Systems, a Linux-based consulting company in Indianapolis, Indiana. He has written several technical books and articles and can be reached at sschafer@synergy-tech.com.

# # #

Mobile Site | Full Site
Copyright 2017 © QuinStreet Inc. All Rights Reserved