Creating WML Documents

This section discusses the basics of setting up a WML document and describes several of the most common tasks involved in authoring a document for the wireless web. You'll work through an example of a mobile web site called FilmTime, which uses geographic coordinates to present a list of movies currently playing within 10 miles of the user's current position. Menus navigate the user through a series of choices about theatres, show times, and film synopses.

For the sake of simplicity, you won't worry about where FilmTime gets the user's coordinates, how it maps coordinates to a ZIP code, or how it processes database queries. You also won't worry about how the components you're authoring fit into the larger scheme of things, as the main objective is to introduce you to the elements rather than coaching you in designing a full-fledged application. In other words, this example focuses on the wireless aspects of such a web site, not on the technical details that don't directly involve WML.

For information and inspiration about the advanced aspects of WML (and of course, WAP), you can really take the bull by the horns and visit the formal WAP specification at http://www.wapforum.org/what/technical.htm. Or, you can go someplace more conversational, but no less exhaustive, such as http://www.wirelessdevnet.com/.

Though this tutorial does not introduce you to the full range of WML elements and their attributes, you will learn how to carry out the following tasks in WML:

  • Create a deck (WML container document) and a number of cards, or sections of the document

  • Enter and format text

  • Navigate around other cards in the deck

  • Associate events with a card element

  • Set up a field for user entry

  • Insert an image

The next few sections get you going with the creation of your first WML document and guide you through the fundamental tasks required to develop complete WML documents.

Before You StartTools of the Trade

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:

  • A text editor, such as the no-frills Windows Notepad or Simple Text, or a dedicated WML editor

  • A mobile phone simulatorsoftware that runs on your PC or online and displays content as the user sees and experiences it (on a "microbrowser"), complete with clickable buttons

  • Debugging capabilities, optionally, which typically accompany the simulator

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

If you visit the Nokia site to download the Nokia Mobile Browser Simulator, make sure you download the simulator, not the Nokia Mobile Internet Toolkit. The toolkit is an excellent set of tools but it is geared toward editing mobile content, not simulating it.

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

You might also want to consider an online mobile phone simulator such as Wapaka. Wapaka is a Java-based microbrowser that allows you to test WML web pages on a simulated mobile phone directly in a normal web browser. Wapaka is neat in that it allows you to change devices to experiment with different screen sizes. To check out Wapaka, visit http://www.digitalairways.com/wapaka/.

Laying Down the Infrastructure

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 tutorial. 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:

  • text/vnd.wap.wmlscript

  • image/vnd.wap.wbmp

  • text/vnd.wap.si

  • text/vnd.wap.sl

  • application/vnd.wap.wbxml

  • application/vnd.wap.wmlc

  • application/vnd.wap.wmlscriptc

The Basic WML Document

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"?>

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.

Microbrowsers for wireless content are much more proprietary than HTML browsers, which means that most major mobile device manufacturers offer their own microbrowser. Even so, the WAP standard is there to provide a high degree of consistency across different microbrowsers.

Setting Up Cards

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 tutorial. You can use it to present straight text, as shown in Listing 23.1.

Listing 23.1. A Simple WML Document with a Single Card (hello.wml)
1: <?xml version="1.0"?>
3:   "http://www.wapforum.org/DTD/wml13.dtd">
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.

Formatting Text

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:

  • b Bolds text

  • big Enlarges text relative to the browser's default text size

  • em Emphasizes text in a browser-defined fashion

  • i Italicizes text

  • small Reduces text relative to the browser's default text size

  • strong Renders text "strong," whatever that means to the given browser

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

Listing 23.2. A WML Document That Shows How to Format Text (formattext.wml)
 1: <?xml version="1.0"?>
 3:   "http://www.wapforum.org/DTD/wml13.dtd">
 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.

Four Ways to Navigate

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:

  • Anchors

  • The select>option construct

  • A series of links using the OK softkey

  • A separate card using other softkeys, such as the Menu key

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.

Listing 23.3. A WML Document That Presents a Movie Listing (movielist.wml)
 1: <?xml version="1.0"?>
 3:   "http://www.wapforum.org/DTD/wml13.dtd">
 5: <wml>
 6:   <card >
 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>
14:   <card >
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>
21:   <card >
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>
28:   <card >
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 911 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.

Listing 23.4. Using WML to Select a Movie Theatre (theatrelist.wml)
 1: <?xml version="1.0"?>
 3:   "http://www.wapforum.org/DTD/wml13.dtd">
 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>
17:   <card >
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>
24:   <card >
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>
31:   <card >
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 1012), 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.

Map to OK Button

Another approach to navigating through the cards in a WML document is to set up the choices as a sequence of cards through which the user navigates by hitting the OK softkey (accessible via Options in the Nokia microbrowser) until reaching the end of the deck. This feature is useful for presenting large chunks of narrative material. See the following section on assigning to other softkeys for a complete list of available actions.

If you're looking to create a document that has a presentation feel to it, you might consider combining the navigation with a timer (see "Associating an Event with a Task" next section) so that the presentation advances from one screen to the next automatically.

Listing 23.5 contains sample code for a WML document that uses the OK mapping for each card as the plot for the movie King Kong, laid out screen by screen.

Listing 23.5. Describing a Movie Plot with WML (moviedesc_kingkong.wml)
 1: <?xml version="1.0"?>
 3:   "http://www.wapforum.org/DTD/wml13.dtd">
 5: <wml>
 6:   <card >
 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>
16:   <card >
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>
26:   <card >
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>
35:   <card >
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>

In lines 7, 17, and 27, the accept value of the do element's type attribute assigns the enclosed go action to the OK softkey. I'll admit that I'm jumping ahead here a bit, but suffice it to say that the do element, which you learn more about in a moment, is how you assign an action to the OK softkey. More specifically, the value accept for the type attribute indicates that the action applies to the OK softkey. Other possible actions are prev and noop, the last of which is designed to eliminate any default behavior in the microbrowser that might result in an unintended jump (for instance). The last card in the document, beginning on line 36, sets the Reset button.

Associating an Event with a Task

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:

  <onevent type=type>

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 >
  <onevent type="ontimer">
    <go href="#two"/>
  <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>

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

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.

Listing 23.6. An Example of How to Select a Movie in WML (movieselect.html)
 1: <?xml version="1.0"?>
 3:   "http://www.wapforum.org/DTD/wml13.dtd">
 5: <wml>
 6:   <card >
 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>
19:   <card >
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>
27:   <card >
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>
36:   </card>
38:   <card >
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 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.

Inserting WBMP Images

As you learned earlier in the tutorial, 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 computervery handy indeed!

WBMP images are typically limited to 150 3 150 in size, although some tools restrict them even further. For example, Waptiger's WBMP Converter only converts images that are 127 3 127 or smaller.

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.

Listing 23.7. Displaying an Image in a WML Document (image.wml)
 1: <?xml version="1.0"?>
 3:   "http://www.wapforum.org/DTD/wml13.dtd">
 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.

Accepting User Input

Although the keyboard of a mobile device is hardly ideal for text inputsometimes the user has to press the same key three times to enter a single characterit 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.

Listing 23.8. Retrieving Information from the User (input.wml)
 1: <?xml version="1.0"?>
 3:   "http://www.wapforum.org/DTD/wml13.dtd">
 5: <wml>
 6:   <card >
 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>
15:   <card >
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>
22:   <card >
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>
30:   <card >
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).