http://www.developer.com/

Back to article

Learning WML - Tools and Structure


June 30, 2002

This series of articles describes how to provide Web content to mobile devices through WML (Wireless Markup Language). This article covers some essential tools for coding and debugging WML code, as well as the basics of creating WML decks. 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.

Essential Documentation and Tools

There are several tools you should assemble before beginning to code your WML applications.

Note: The recommendations in this article are simply that: recommendations. You can make do with a simple text editor (such as Windows Notepad or vi in Linux) and the Web server, but spending some time assembling some good tools will pay off in the long run.

Tip: If you decide not to use one of the WAP SDKs/IDEs and use Windows as your OS, try TextPad, a nifty text editor that's very versatile and code friendly (http://www.textpad.com).

Documentation

There is an abundance of WAP/WML documentation on the Web, mostly courtesy of the Open Mobile Alliance (OMA) and other WAP organizations. You should spend some time reading the user interface (UI) suggestions, developer guidelines, and language reference text at the sites listed in the following sections.

Open Mobile Alliance - http://www.openmobilealliance.org

The Open Mobile Alliance (OMA) is a relatively new standards organization made up of several key players in the WAP arena, including most cellular providers and phone manufacturers - visit http://www.openmobilealliance.org/members.html for a full list. The new site is still evolving, but much of the content from the previous site (the popular "WAP Forum") is still available. As of this writing, you can access the documentation by using the "Access to WAP specific information" link at the bottom of the main OMA page. A full list of WML release specifications, WAP specifications, and DTD definitions is available.

Openwave Developer Program - http://developer.openwave.com

Openwave, the company behind the popular Openwave Mobile Browser (formerly the UP.Browser) maintains a library of technical documents and developer guidelines. Follow the links on the left side of the main page to access WML language references (in the Technical Library), UI guidelines, lists of supported devices, and more.

Forum Nokia - http://www.forum.nokia.com

Nokia was one of the pioneers in the WAP arena and maintains an impressive number of emulators and related documentation. Their Documents section has a handy search feature to help find the document most applicable to your needs.

Emulators and SDKs

You could test your WML code with a cell phone, but most providers charge a premium for Web access, and testing could get rather expensive. Instead, use one of the following emulators, some of which are packaged with a full SDKsome even include a full Integrated Development Environment (IDE).

Note: Most of the emulators and SDKs are only available for Windows, although a few are available for Solaris and other operating systems.

Tip: No emulator can fully replace actual device testing. Although you can initially code and debug on one of the emulators, dont neglect testing on your actual target device(s) as well.

The Gelon Wapalizer - http://www.gelon.net

The Wapalizer is a Web-based WAP emulator and offers several skins to emulate popular phones. Simply type your URL into the Wapalizer box and click the Wapalize button to open your code in the default emulator. Alternatively, choose a different skin and use the emulated device's interface to navigate to your URL.

Note: The Wapalizer is not as robust as some of the other emulators. Although it's a handy way to quickly check a page, you should also use an emulator that closely resembles your target microbrowser.

The Openwave SDK - http://developer.openwave.com

The Openwave SDK 5.1 provides the best suite of tools I've run across; I use it as my primary coding and testing environment. The Openwave developer site (http://developer.openwave.com) has several SDKs available, depending on what WML language revision and feature set you need. SDK 5.1 can be used for most applications, providing that you stay within the coding boundaries for your target device's supported version of WML and you fully test your code on the target device(s).

Nokia Emulators - http://www.forum.nokia.com

Nokia maintains an impressive list of emulators, including several that tie in to their Mobile Internet Toolkit. Note that you must register on the site to download any of the tools. Many are Java-based, and therefore require you to install a Java Virtual Machine (JVM) on your system to run the tool.

Other Emulators

If your device isn't compatible with the emulators listed above, visit the manufacturer's site for the device to see whether they offer a compatible tool.

Tip: If you need to find out what browser your target device uses, access a nonexistent file on your Web server and examine your server logs for the browser identification information. (A nonexistent file makes it easy to find the pertinent log entry.) For example, if I use my Samsung A400 phone to access "missingfile.jpg" on my Web server, I find the following log entry:

[25/Jun/2002:16:27:50 -0500] "GET /wireless/missingfile.jpg HTTP/1.1" 404 306 "-" "SEC-spha400 UP.Browser/4.1.22b1 UP.Link/5.0.2.3c"

This entry shows the client ("spha400") and the browser and version (UP.Browser 4.1.22b, now the Openwave Mobile Browser, but still identified as UP.Browser).

Basic WML Structure and Rules

Now that we have our server set up and our toolkit stocked, we're almost ready to do some coding. First let's examine the basic form of WML documents and some basic coding rules.

Basic WML Deck Structure

The following listing shows the basic elements you need in most WML decks:

<?xml version="1.0"?><!DOCTYPE wml PUBLIC "-//WAPFORUM//DTD WML 1.1//EN" "http://www.wapforum.org/DTD/wml_1.1.xml"> <wml><head><meta.../></head><card id="cardid1" title="Card1"> ...</card><card id="cardid2" title="Card2"> ...</card> ...</wml>

You may remember the document preamble code (first two lines) from the previous article. These lines are necessary to identify the type of content (WML) to the browser. They need to be present in all files.

The deck is then started with a <wml> tag, and ended with a </wml> tag.

Note that the <head> section is optional, but is necessary to supply any meta information (via <meta> tags) required for your deck. Typically, cache instructions are passed via meta tags included in the <head> section. Leaving the <head> section blank by including only the <head> tags is a bad idea; it can cause some browsers to fail. Include this section only if you need to include <meta> or <access> tags.

What follows is the actual deck, made up of individual cards, each with a mandatory ID and title parameter. (Other parameters for the <card> and other tags will be covered in later articles.) Some browsers display the card title at the top of the display; others don't. It's important to make your card titles display-ready (short but meaningful, and so on).

Tip: It may be helpful to have this information stored in a file as a template for all your WML coding. Note that some SDKs provide a skeletal WML structure when you create a new file.

WML Language Rules

Let's quickly review some basic WML language rules:

  • Most tags have opening and closing components. Those that dont (<access>, <br/>, <img>, <meta>, and so on) include a slash at the end of the tag, signifying that the tag is singular (opening and closing).
  • The language is case sensitive, so all closing tags must match the capitalization of the opening tags. (<B>This is bold</b> will not have the desired results.)
  • All tag parameter values must be enclosed in quotes (for example, <p mode="nowrap">).
  • All text must be enclosed in a tag, even if that tag is just a simple paragraph tag (<p>).
  • There are some elements that must appear in a certain order. For example, within a element, the following must appear in order: <onevent>, <timer>, <do>.

WML Text Formatting

Like HTML, WML supports several types of text formatting. The following table describes the available text-formatting tags.

TagNameUse
<p>ParagraphMark blocks of text as paragraphs.
<br/>Line breakBreak the current line, much like pressing Enter in a word processing program.
<b>BoldBoldface the delineated text.
<big>BigMake the text appear in a large point size.
<em>EmphasizedEmphasize the text (usually with italics).
<i>ItalicDisplay the text in an italic font.
<small>SmallDisplay the text in a small point size.
<strong>StrongDisplay the text in a strongly emphasized font. (Usually a large point size and italic.)
<u>UnderlineDisplay the text in an underlined font.

Note: Many of these text attributes (such as <big>, and so on) are not supported by all mobile browsers.

The most important text formatting tag is the paragraph tag (<p>). This tag must appear around all text not delineated by other tags. It also controls how the browser presents the text if you add the optional mode attribute. The two supported modes are "wrap" and "nowrap", with "wrap" as the default. The wrap mode allows the text to flow down the device screen, breaking lines at appropriate spaces and punctuation. The nowrap mode uses a marquee-like display to display the text, scrolling the text horizontally when this mode is selected.

For example, take the following code:

<?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="Text Wrapping"><p mode="nowrap">No Wrap: The quick brown fox jumped over the lazy dog.</p><p mode="wrap">Wrap: The quick brown fox jumped over the lazy dog.</p></card></wml>

It results in the following display:


Figure 2-1 - The mode attribute determines how the

tag wraps 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.)


Figure 2-2 - Text set to nowrap will scroll horizontally when the browser selects that line. Note how the first line (nowrap) has scrolled in this figure. The text will continue to scroll until it reaches the end of the paragraph, where it will start over.

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.)

If you don't use the mode attribute, the client browser uses the currently selected mode, or the default "wrap" if no mode had been defined previously. Typically the nowrap mode is used for headlines and selection text, while wrap is used for general and body text.

Card Navigation

Now let's consider how to navigate between cards within a deck. As an example, we'll use a riddle, having the user navigate between the question and answer.

Take the following riddle:

Q: You cannot see it, you cannot touch it, it isn't a liquid, it isn't a solid, it isn't a gas, but it can be broken. What is it?

A: Silence.

We'll put the question in one card, the answer in another, and define links to move between the two. For the sake of variety, let's define the link forward (to the answer) as a button and the link backward (back to the question) as an in-text link. Consider the following code:

<?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="Question"><do type="accept" label="Answer"><go href="#card2" /></do><p mode="wrap">You cannot see it, you cannot touch it, it isn't a liquid, it isn't asolid, it isn't a gas, but it can be broken. <br/>What is it?</p></card><card id="card2" title="Answer"><p mode="nowrap">Silence.<br/><br/><br/><anchor><prev></prev>Back to Question</anchor></p></card></wml>

Card 1

The first card is simply text, enclosed in paragraph tags. However, we've added a <do> element to change the behavior of the Accept key - one of the default navigation keys on most mobile devices (see the next section on keys for more information). This <do> element has type and label attributes. The type attribute tells the browser how the <do> is called. In this case it's by remapping the Accept key's function. The label supplies a label for the key, namely "Answer" in this example.

Note: This label bends one of the UI suggestions of using a maximum of five letters for key labels.

Within the <do> element is a <go> instruction, supplying the address (href) to "go" to when the key is pressed. The href is in the following form:

<Deck>#<CardID>

Since the destination is in the same deck, the deck name can be omitted and only the CardID is necessary.

Note: The order of the <do> and <p> elements is arbitrary. I prefer to put my navigation directives before my text wherever possible. It would be acceptable to reverse their order. Whichever you choose it pays to be consistent.

Card 2

The second card also uses a paragraph element, but incorporates a link within the element by using the <anchor> tag. The form of the <anchor> tag is as follows:

<anchor title="label">typetext</anchor>

The label attribute supplies an optional label to the Accept button when the link is selected. We've omitted this attribute in the example, allowing the default "Link" (or other device default) to be displayed.

The type of anchor can be <go>, <prev>, or <refresh> - you simply add the appropriate element to define the type. We've used <prev> to return to the previous card.

The text is the actual text shown for the link, in this case "Back to Question".

Note that the <anchor> is enclosed in the paragraph and that the paragraph is set to nowrap. This will prevent the link from wrapping to several lines. We aren't worried about the plain text ("Silence") wrapping in this example, but we could easily enclose the <anchor> in its own nowrap <p> tag and change the text paragraph to wrap.

Result

The above code has the following result:


Figure 2-3 - The left display is Card1, the right is Card2. Notice that the emulator displays a check mark instead of the standard "Link" text for the Accept button.

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.)

Expanding the Example

You might have noticed that our second navigation method - mapping the <prev> command to the Accept key - is superfluous. Most devices incorporate a standard "Back" button that could be used to return to the question without the overhead of remapping a key. With that in mind, let's put the key to a better purpose: moving to another question.

Change the <anchor> to the following:

<anchor><go href="#card3" />Next Question</anchor>

Then, duplicate cards 1 and 2 and re-label them as 3 and 4. You also need to change the link in card 3 (to card 4) and supply a new question and answer. The result would be similar to the following:

<?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="Question"><do type="accept" label="Answer"><go href="#card2" /></do><p mode="wrap">You cannot see it, you cannot touch it, it isn't a liquid, it isn't asolid, it isn't a gas, but it can be broken. <br/>What is it?</p></card><card id="card2" title="Answer"><p mode="nowrap">Silence.<br/><br/><br/><anchor><go href="#card3" />Next Question</anchor></p></card><card id="card3" title="Question"><do type="accept" label="Answer"><go href="#card4" /></do><p mode="wrap">What is greater than God, more evil than the devil, poor people have it,rich people want it, and if you eat it you will die?</p></card><card id="card4" title="Answer"><p mode="wrap">Nothing. Nothing's greater than God, nothing's more evil than the devil, poorpeople have nothing, rich people want nothing more than they alreadyhave, and if you eat nothing you will die.</p><p mode="nowrap"><br/><br/><anchor><go href="#card5" />Next Question</anchor></p></card></wml>

Note: Because the answer to the second question is lengthy, I moved the <anchor> to its own nowrap paragraph, as discussed earlier. Also, I set up the last link to a nonexistent "card5," assuming that we would add more questions and answers.

Understanding Device Keys

Most mobile devices have a limited number of keys to aid in navigation. Many have a default Back key (my Samsung cell phone uses the CLR key), as well as Accept and Options keys (my Samsung uses OK and MENU, respectively).

Note: See the WAP documentation for a particular device to determine which keys perform which default purposes.

The Accept and Option keys are referred to as soft keys because you can redefine their meaning and default labels with the software, in this case WML code. Many of the navigation elements allow you to specify which keys you want the soft keys to interact with. For example, in our riddle example we specified "accept" to modify the Accept key. We could have used "options" to redefine the other soft key (on the lower right side of the display).

Tip: When defining multiple <do> elements on the same card, the affected soft key will be labeled "MENU" and allow access to a menu of defined <do> elements.

Unfortunately, there are few firm standards for default keys. Some device manufacturers map different keys to the WAP interface, while some have more proprietary solutions such as a jog wheel to move between options and functions. The best thing to do before planning an interface is to read the UI and application style guides and test your target devices.

Next Time

The next article in this series will cover additional navigation options such as select lists, user input, and graphical display of bitmaps and icons.

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.

# # #

Sitemap | Contact Us

Thanks for your registration, follow us on our social networks to keep up-to-date