Before jumping into WML code, it’s worth going over a few fundamental issues that surround any XML-based markup language. More specifically, you need to know about the WML specification, which is the last word on WML, as well as the WML DTD and MIME types associated with WML. Following is the information you need to get started with WML:

As any legitimate XML-based language must, WML defines a root element for conforming documents—wml. As such, the wml root element serves as the container for all other elements in WML documents. To help facilitate display and navigation in limited screen space, a WML document is conceived as a deck of cards, one of which is visible at any given time. Although the document is typically transmitted as a single unit, it is navigated piece-by-piece, or card-by-card.

The wml element is the parent of the card element, which in turn contains all other elements in the document. You can have an unlimited number of cards in each document (deck). A card is intended to, but doesn’t necessarily, convey approximately one screen of information. (To scroll beyond the screen’s boundaries, the user can navigate with the arrow keys.)

Because so little text fits on the screen of a mobile device, efficient navigation is critical in a WML document. WML provides numerous ways of getting around, from the anchor element, which is adopted from HTML, to the monitoring of user events. One of WML’s solutions to the screen real estate crunch is its capability of mapping actions to the mobile device’s softkeys, which are the mysterious blank buttons just below the screen. The labels (names) that appear on the screen just above them may vary from one device to another, but their intention is usually clear. For the most part, they appear only when WML code instructs them to do so.

The softkeys provide navigation controls beyond what you can fit on the screen in the content of a document. For instance, a Menu or Options key displays the equivalent of an HTML navigation bar, whereas a Reset key takes the user back to the first card in the deck. The Link button, as shown in the examples in this hour, appears when the text contains hyperlinks.

Besides anchors, WML provides a selection list tool that lets you display a series of choices as a numbered list. Thus, the user can select an option with a number key on the keypad, in addition to using the Link button.

WML offers a number of action elements (go, prev, refresh, and so on) that move the user from one card to another under specified contexts, such as the use of go href="url" in the anchor element (a href, and so forth, is a shorthand version of this). These elements are flexible in their implementation and can be associated with a number of parent elements in order to provide a considerable amount of mobility.

Events in WML are comparable to events in any scripting or programming language; you set up the document to wait for a specified event to happen, and when it does the program automatically carries out a designated task. Some events you can code for are onenterforward, onenterbackward, and ontimer, which indicate entering a card in the forward direction, entering a card backward, and the elapsed time of a timer that is associated with a card, respectively.

Given the nature of mobile devices, screen space is severely limited and bandwidth is precious. Thus, we can’t afford to clog the airwaves with fancy formatting or layout directives, which is why WML offers only the simplest of formatting tags. WML does support tables, but they are very primitive, nothing like the sophisticated layout capabilities afforded by tables in HTML. The few text-formatting tags that do exist in WML have been adapted straight from HTML, making for a flat learning curve for traditional web developers.

Graphics support in WML is restricted to the WBMP (Wireless BitMap Picture) format, a 1-bit bitmap format whose files end in a .wbmp extension. One bit means on-or-off, black-or-white, which is just two colors. Besides the color depth restriction, the size is limited as well; WML images can’t measure more than 64 3 64 pixels. Because you probably aren’t accustomed to storing images in the WBMP format, you’ll need to use a graphics converter of some sort to convert other graphics formats to WBMP. You’ll find sources for such software listed in the “Inserting WBMP Images” section later in this hour.

As with just about any kind of software development, tools can ultimately determine how likely you are to succeed in completing a project. WML is no different, although its tool requirements are fairly straightforward. You will need the following items to build a wireless web site with WML:

The most important tool in any WML developer’s arsenal is the mobile phone simulator because it is what allows you to test WML documents in the context of a wireless device. A mobile phone simulator acts as a microbrowser, which is a small-scale web browser that is designed specifically for wireless devices. The wireless tool used throughout this hour is the Nokia Mobile Browser Simulator, which is available for free download from Nokia (http://www.forum.nokia.com/main/0,,034-13,00.html). The Nokia Mobile Browser Simulator is handy because it isn’t very forgiving with your WML and XHTML Mobile code. It will quickly let you know if a tag or attribute is used improperly, and won’t display a page until the problem is fixed.

Another good alternative to the Nokia Mobile Browser Simulator is WinWAP, which actually looks more like a traditional HTML-based web browser than a WML microbrowser. WinWAP is a good test browser for WML documents because it is so simple to use. You can download a trial version of WinWAP at http://www.winwap.org/. For a more full-featured microbrowser and WML development environment, you might consider the Openwave SDK, which provides a highly useful microbrowser that resembles a virtual mobile phone. You can download the Openwave SDK for free at http://www.openwave.com/products/developer_products/.

In order to transmit WML documents, you need a WML gateway and a web server in place. The cell phone transmits the user’s information to a WAP gateway, which sends it on to the web server, which stores it as session information in the user profile.

Your web server needs to know how to process the MIME types of the WML documents, as mentioned in the section “Nuts and Bolts” earlier in the hour. You’ll need to take a look at your web server’s documentation to learn how to do that. Essentially, you need to introduce each MIME type to the server in a statement of its own. Following are the MIME types associated with WML:

To view the sample WML documents, you’ll need a mobile phone simulator such as the Nokia Mobile Browser Simulator, WinWAP, the Openwave SDK, or some other suitable WML tool that includes a microbrowser. Most of the major mobile phone manufacturers offer simulators that you can download and install and use to test WML pages in a microbrowser. With a microbrowser in hand, you’re ready to begin creating your first WML document.

To begin creating a WML document, you must first enter the familiar XML declaration, and then reference the WML DTD. The WML root element, wml, is then added as a paired tag. Following is code for a skeletal WML document, which accomplishes these basic tasks:

<?xml version="1.0"?>
<!DOCTYPE wml PUBLIC "-//WAPFORUM//DTD WML 1.3//EN"
  "http://www.wapforum.org/DTD/wml13.dtd">

<wml>
</wml>

After entering this code into a text editor, you should save it with a .wml extension, which is standard for WML documents. Granted, some microbrowsers don’t care about the file extension and will display documents okay regardless of the extension, but it’s good programming practice to get it right and use the correct file extension.

The card element is the basic unit of content in WML and the parent of all lower-level elements in the document; that is to say, it is the only child of the wml element. So, one card and a small snippet of text is all it takes to get you to the tiny silver screen. Of course, most practical WML documents consist of multiple cards.

The p, or paragraph, element is a direct import from HTML and is a child of the card element. However, unlike its HTML counterpart, it has a number of children, discussed later in the hour. You can use it to present straight text, as shown in Listing 23.1.

1: <?xml version="1.0"?>
2: <!DOCTYPE wml PUBLIC "-//WAPFORUM//DTD WML 1.3//EN"
3:   "http://www.wapforum.org/DTD/wml13.dtd">
4:
5: <wml>
6:   <card>
7:     <p>Hello, Movie Lovers!</p>
8:   </card>
9: </wml>

Figure 23.1 shows the resulting document as viewed in a microbrowser.

Figure 23.1. The obligatory “Hello” document.

As you can see, it isn’t too difficult to place a greeting into a WML document and make it available to the world of wireless devices.

Even though wireless device screens are typically somewhat limited in terms of their graphical capabilities, it is possible to format text in WML documents to a certain extent. The good news is that if you’ve ever formatted text in HTML, you’ll find the WML approach to be very familiar. Following are the text formatting elements used in WML:

Listing 23.2 shows how to put these formatting elements to use in formatting text.

 1: <?xml version="1.0"?>
 2: <!DOCTYPE wml PUBLIC "-//WAPFORUM//DTD WML 1.3//EN"
 3:   "http://www.wapforum.org/DTD/wml13.dtd">
 4:
 5: <wml>
 6:   <card>
 7:     <p><b>FilmTime!</b></p>
 8:     <p><big>FilmTime!</big></p>
 9:     <p><em>FilmTime!</em></p>
10:     <p><i>FilmTime!</i></p>
11:     <p><small>FilmTime!</small></p>
12:     <p><strong>FilmTime!</strong></p>
13:   </card>
14: </wml>

The results of the code in Listing 23.2 are shown in Figure 23.2.

Figure 23.2. A demonstration of text formatting elements.

As you can see in the figure, WML doesn’t go crazy in its support for text formatting, but it does cover the basics: bold, italic, and so on. Keep in mind that it is up to the microbrowser to determine exactly how to draw formatted text, so you may well get different results with other browsers.

A popular text layout feature of HTML is tables, which allow you to arrange text and other content in a grid-like array. Tables are supported in WML, but their role is modest as compared to tables in HTML. Think of WML tables as more like a typewriter’s tabs, useful for alignment but not much else.

There are many ways to structure and navigate around a document in WML, all of which have their pros and cons. Four of the more common approaches follow:

Which navigation approach you choose may be a matter of weighing the advantages and disadvantages of the particular document you’re creating, or it may be part of the style guide of the company you work for. There isn’t really a right or wrong way to navigate WML documents, but generally speaking, simpler is better.

Good Old Anchors

Anchors, which form the basis of hyperlinks in HTML, have the hands-down advantage in terms of WML navigation approaches due to the familiarity from HTML. The syntax follows the HTML anchor syntax exactly:

<a href="url">content</a>

This is actually the short form of the longer anchor element. In other words, though HTML relies on the somewhat cryptic a element, WML allows you to spell it out with the anchor element, like this:

<anchor href="url">content</anchor>

The best way to get acquainted with the anchor element is to see it in the context of a sample document. The hypothetical FilmTime wireless web site presents a list of movie titles that serve as links. The user navigates the list with the up or down arrow keys and makes a selection by clicking the Link button. Alternatively, they can use the Send button (the physical one) to jump to a link. Listing 23.3 contains the code for a WML document that uses anchors to allow the user to select from a listing of movies.

Example 23.3. A WML Document That Presents a Movie Listing (movielist.wml)

 1: <?xml version="1.0"?>
 2: <!DOCTYPE wml PUBLIC "-//WAPFORUM//DTD WML 1.3//EN"
 3:   "http://www.wapforum.org/DTD/wml13.dtd">
 4:
 5: <wml>
 6:   <card id="films">
 7:     <p align="center"><b>***FILMTIME!***</b></p>
 8:     <p><b>FILMS NEAR YOU</b></p>
 9:     <p><a href="#allkingsmen">All the King's Men</a></p>
10:     <p><a href="#theproducers">The Producers</a></p>
11:     <p><a href="#kingkong">King Kong</a></p>
12:   </card>
13:
14:   <card id="allkingsmen">
15:     <p><b>All the King's Men</b></p>
16:     <p>Remake of the classic novel, which charts the spectacular rise
17:       and fall of a charismatic Southern politician, &quot;Boss&quot;
18:       Willie Stark.</p>
19:   </card>
20:
21:   <card id="theproducers">
22:     <p><b>The Producers</b></p>
23:     <p>Remake of a Broadway hit about two producers who set out to
24:       make the worst movie ever but unwittingly turn out a smash hit,
25:       much to their dismay.</p>
26:   </card>
27:
28:   <card id="kingkong">
29:     <p><b>King Kong</b></p>
30:     <p>Remake of the 1933 classic, in which a giant ape is found on a
31:       mysterious island and brought back to New York City.</p>
32:   </card>
33: </wml>

As you can see, multiple card elements are used here to represent different screens of information, one for each movie. Each movie card in the document is assigned a unique ID via the id attribute (lines 14, 21, and 28). Lines 9–11 use the a element with the href attribute to link to the movie cards in the deck. The value of the href attribute is the id attribute of the card to which you’re linking. The result of this code is shown in Figure 23.3. In this browser, each link is underlined, much as it would be in a traditional HTML web browser. Other browsers may render them differently, such as using square brackets around the links.

Figure 23.3. A list of links, HTML fashion.

The select>option Setup

The previous example showed how to allow the user to select from a list of options using anchors. You can get almost the same effect by using the select element with its child, the option element. This results in a set of radio buttons for each selection option. As with the anchor approach, the user can hit the physical Options or Send key to jump to a link.

The select element itself is a child of the p (paragraph) element, which is in turn a child of the card element. In other words, you need to place the select element within a paragraph. Listing 23.4 illustrates the select>option construction in an example that allows you to select movie theatres from a list.

Example 23.4. Using WML to Select a Movie Theatre (theatrelist.wml)

 1: <?xml version="1.0"?>
 2: <!DOCTYPE wml PUBLIC "-//WAPFORUM//DTD WML 1.3//EN"
 3:   "http://www.wapforum.org/DTD/wml13.dtd">
 4:
 5: <wml>
 6:   <card>
 7:     <p align="center"><b>***FILMTIME!***</b></p>
 8:     <p><b>KING KONG NOW PLAYING AT...</b>
 9:     <select>
10:       <option onpick="#rio">Rio</option>
11:       <option onpick="#apollo">Apollo</option>
12:       <option onpick="#crown">Crown</option>
13:     </select>
14:     </p>
15:   </card>
16:
17:   <card id="rio">
18:     <p><b>Rio Theatre</b></p>
19:     <p>455 River Street, Anytown</p>
20:     <p>111.222.3333</p>
21:     <p>3:30, 5:30, 7:30</p>
22:   </card>
23:
24:   <card id="apollo">
25:     <p><b>Apollo Theatre</b></p>
26:     <p>779 Pax Romana Drive, Chesterton</p>
27:     <p>111.222.4444</p>
28:     <p>3:45, 5:50, 7:40</p>
29:   </card>
30:
31:   <card id="crown">
32:     <p><b>Crown Theatre</b></p>
33:     <p>83 Imperial Avenue, Kingston</p>
34:     <p>111.234.5566</p>
35:     <p>2:00, 4:30, 6:45</p>
36:   </card>
37: </wml>

In this example, a select element is used (line 9) to establish a list of theatres from which the user can select. Each theatre option is represented by an option element accompanied by an onpick attribute (lines 10–12), which determines the destination of the option link. The link destinations correspond to card IDs that appear later in the document (lines 17, 24, and 31). The rest of the listing is similar to the anchor example in structure, and the result is shown in Figure 23.4.

Figure 23.4. The select>option list makes it possible to easily select movies from a list.

Unlike the a href construction, select>option's output is a set of radio buttons, which allows the user to make the selection by navigating through the buttons.

 1: <?xml version="1.0"?>
 2: <!DOCTYPE wml PUBLIC "-//WAPFORUM//DTD WML 1.3//EN"
 3:   "http://www.wapforum.org/DTD/wml13.dtd">
 4:
 5: <wml>
 6:   <card id="one">
 7:     <do type="accept">
 8:       <go href="#two"/>
 9:     </do>
10:     <p align="center"><b>***FILMTIME!***</b></p>
11:     <p><i>King Kong</i> This remake of the 1933 classic follows an
12:       expedition to the mysterious Skull Island, where a legend of
13:       a giant gorilla draws explorers and filmmakers.</p>
14:   </card>
15:
16:   <card id="two">
17:     <do type="accept">
18:       <go href="#three"/>
19:     </do>
20:     <p align="center">-2-</p>
21:     <p>The legend, however, is both real and dangerous, living in a
22:       massive jungle that has protected him and other prehistoric
23:       creatures for decades.</p>
24:   </card>
25:
26:   <card id="three">
27:     <do type="accept">
28:       <go href="#four"/>
29:     </do>
30:     <p align="center">-3-</p>
31:     <p>Kong finds solace in a beautiful woman (Naomi Watts), and is
32:       subdued enough to be captured and brought back to New York.</p>
33:   </card>
34:
35:   <card id="four">
36:     <do type="reset">
37:       <go href="#one"/>
38:     </do>
39:     <p align="center">-4-</p>
40:     <p>However, as the captors and the public will learn, it takes a
41:       lot more shackles to hold back an animal of such monstrous
42:       size.</p>
43:   </card>
44: </wml>

Tasks, such as moving from one card to the next, can be set so that they are triggered by actions, such as timer events. For example, you could re-create the movie plot example so that it presents the same text in the same order but uses a timer that automatically flips the display to the next card. This is accomplished with an event called ontimer. Events are specified using the onevent element, which is a child of the card element. Following is the syntax of the onevent element:

<card>
  <onevent type=type>
    action
  </onevent>
</card>

To create a timer, you must set the type attribute of the onevent element to ontimer and then provide a separate timer element that specifies the duration of the timer. The unit of measurement of the timer’s value is a 10th of a second, which means that a value of 20 represents two seconds. Following is a code snippet that demonstrates how to set a two-second timer that flips to the second card in the movie plot document:

<card id="one">
  <onevent type="ontimer">
    <go href="#two"/>
  </onevent>
  <timer value="20"/>
  <p align="center"><b>***FILMTIME!***</b></p>
  <p><i>King Kong</i> This remake of the 1933 classic follows an
    expedition to the mysterious Skull Island, where a legend of
    a giant gorilla draws explorers and filmmakers.</p>
</card>

Better yet, there’s a shortcut that allows you to include the ontimer attribute directly in the card element, eliminating the need for the onevent element and its contents:

<card id="two" ontimer="#three">
  <timer value="50"/>
  <p align="center">-2-</p>
  <p>The legend, however, is both real and dangerous, living in a
    massive jungle that has protected him and other prehistoric
    creatures for decades.</p>
</card>

Map to Menu Button

WML allows you to map cards to the Menu (or Options) and other softkeys. This is accomplished with the do element, which has an attribute named type that is set to indicate which softkeys are targeted by the mapping. The type attribute of the do element can be any of the following actions that correspond to the microbrowser’s softkeys:

• accept— OK button

• delete— Delete button

• help— Help button

• options— Options or Menu button

• prev— Prev button, return to previous card

• reset— Return to first card of the deck, and/or reset variables

Listing 23.6 contains sample code for a WML document that demonstrates how to use the do element to map movie options to the Options softkey; pressing the Options/Menu key displays a list of links to other cards. Those cards, in turn, link to cards in other WML documents.

Example 23.6. An Example of How to Select a Movie in WML (movieselect.html)

 1: <?xml version="1.0"?>
 2: <!DOCTYPE wml PUBLIC "-//WAPFORUM//DTD WML 1.3//EN"
 3:   "http://www.wapforum.org/DTD/wml13.dtd">
 4:
 5: <wml>
 6:   <card id="top">
 7:     <p>Press the Menu button for more choices:</p>
 8:     <do type="options" name="movies" label="Movies">
 9:       <go href="#movies"/>
10:     </do>
11:     <do type="options" name="synopses" label="Synopses">
12:       <go href="#synopses"/>
13:     </do>
14:     <do type="options" name="theatres" label="Theatres">
15:       <go href="#theatres"/>
16:     </do>
17:   </card>
18:
19:   <card id="movies">
20:     <p align="center"><b>***FILMTIME!***</b></p>
21:     <p><b>FILMS NEAR YOU</b></p>
22:     <p><a href="moviedesc_allkingsmen.wml">All the King's Men</a></p>
23:     <p><a href="moviedesc_theproducers.wml">The Producers</a></p>
24:     <p><a href="moviedesc_kingkong.wml">King Kong</a></p>
25:   </card>
26:
27:   <card id="synopses">
28:     <p><b>SYNOPSES</b>
29:     <select>
30:       <option onpick="movielist.wml#allkingsmen">All the King's Men</option>
31:       <option onpick="movielist.wml#theproducers">The Producers</option>
32:       <option onpick="movielist.wml#kingkong">King Kong</option>
33:     </select>
34:     </p>
35:
36:   </card>
37:
38:   <card id="theatres">
39:     <p><b>THEATRES NEAR YOU</b>
40:     <select>
41:       <option onpick="theatrelist.wml#rio">Rio</option>
42:       <option onpick="theatrelist.wml#apollo">Apollo</option>
43:       <option onpick="theatrelist.wml#crown">Crown</option>
44:     </select>
45:     </p>
46:   </card>
47: </wml>

This example uses several do elements to link to parts of the document within the Options softkey. For example, the first do element (line 8) links to the “movies” card because of the nested go element (line 10); the href attribute of the go element is set to #movies. This approach is also used with the two other cards (“synopses” and “theatres”). Notice that the original anchor approach to linking cards is used in the “movies” card (lines 22–24), whereas the option element is used to allow selection within the “synopses” and “theatres” cards (lines 30–32 and 41–43). Figure 23.5 shows the resulting options for this document as viewed in the Nokia Mobile Browser Simulator; keep in mind that the mapping of these options will differ when viewed on an actual wireless device because of the softkeys.

Figure 23.5. Menu button activated.

In this relatively simple example, not a whole lot is accomplished by putting the choices in a separate options menu rather than directly on the screen. But on a larger commercial web site with a great number of cards, it could be a very efficient design element. As an example, consider other types of corporate sites where users have become accustomed to the Menu or Options button linking to a global set of choices, such as “Company,” “About,” “Careers at . . .,” and so on. The point is that as a site becomes deeper in terms of content, the options approach starts to pay off versus normal anchors.

As you learned earlier in the hour, it is possible to display images in WML documents. WML supports only one graphics format, WBMP, which stands for Wireless BitMap Picture. The WBMP format is a 1-bit monochrome format and, currently, the only graphics format supported by WML. Because most traditional paint applications don’t support WBMP just yet, you’ll have to find a converter application to convert traditional images, such as GIFs or BMPs, into the WBMP format. One such converter application is offered for free by the Waptiger WAP search engine. There is even an online version of Waptiger’s WBMP Converter at http://www.waptiger.com/bmp2wbmp/ that allows you to convert 1-bit BMP bitmaps to WBMP images. This online converter allows you to browse for an image on your local computer, after which it is converted to a WBMP image that is saved on your local computer—very handy indeed!

To display an image in WML, you must use the img element, which, like so many other WML elements, is a child of the p element. The src, alt, height, and width attributes of the img element come directly from HTML. Unlike traditional HTML images, however, WML limits the size of WBMP images to 64 3 64. Listing 23.7 contains the code for an example that demonstrates how to use the img element.

 1: <?xml version="1.0"?>
 2: <!DOCTYPE wml PUBLIC "-//WAPFORUM//DTD WML 1.3//EN"
 3:   "http://www.wapforum.org/DTD/wml13.dtd">
 4:
 5: <wml>
 6:   <card>
 7:     <p><img src="ftlogo.wbmp" alt="FilmTime Logo"
 8:       width="64" height="39"/>
 9:     </p>
10:   </card>
11: </wml>

This code uses the img element to embed the image named ftlogo.wbmp in the WML document (line 7). Notice that alternative text is specified for the image (line 7), as well as the width and height of the image (line 8). Figure 23.6 shows the results of viewing this document in the Nokia Mobile Browser Simulator.

Figure 23.6. Displaying a simple WBMP image in a WML document isn’t too difficult thanks to the img element.

The image shown in the figure is a logo for the hypothetical wireless web site FilmTime.

Although the keyboard of a mobile device is hardly ideal for text input—sometimes the user has to press the same key three times to enter a single character—it is easy enough to support in WML documents. Keyboard support is carried out via the input element, which is a child of the p element. The user types in the current value (input can also be initialized to a default value) and WML assigns it, for instance, the name email, as in the first occurrence of the input element in Listing 23.8.

 1: <?xml version="1.0"?>
 2: <!DOCTYPE wml PUBLIC "-//WAPFORUM//DTD WML 1.3//EN"
 3:   "http://www.wapforum.org/DTD/wml13.dtd">
 4:
 5: <wml>
 6:   <card id="subscribe">
 7:     <p align="center"><b>***FILMTIME!***</b></p>
 8:     <p>To subscribe to FILMTIME!, please enter your e-mail address:</p>
 9:     <p><input name="email"/></p>
10:     <do type="accept">
11:       <go href="#email-ok"/>
12:     </do>
13:   </card>
14:
15:   <card id="email-ok">
16:     <p>You entered <i>$email</i>. If this is correct, click OK.</p>
17:     <do type="accept">
18:       <go href="#username"/>
19:     </do>
20:   </card>
21:
22:   <card id="username">
23:     <p>Please enter your name.</p>
24:     <p><input name="username"/></p>
25:     <do type="accept">
26:       <go href="#thanks"/>
27:     </do>
28:   </card>
29:
30:   <card id="thanks">
31:     <p>Thanks, <b>$username</b>!</p>
32:     <p>Goodbye!</p>
33:   </card>
34: </wml>

In this example, the user is allowed to input his email address (line 9). The email address is given the name email, which is the name used to store the information for any further processing. When the user progresses to the next card, the email address is displayed to him by preceding its name with a dollar sign (line 16): $email. A similar approach is used to ask the user for his name (line 24), and then display it when telling him goodbye (lines 31 and 32).