Of course, comments will become more valuable as our code becomes more complex, but we can see how they work here:

<wml>
  <card>
   <!-- Say hello to the users -->
   <p>Wrox Travel</p>
   <p>Welcome to our WAP site!</p>
  </card>
</wml>

This single line of code tells you almost everything you need to know about WML comments. They start with the sequence '<!--', end with '-->', and you're free to put anything you like between these two delimiters - over multiple lines, if you need to. Better yet, comments are completely ignored by the WML compiler, so files containing them are no larger (when they're sent to user agents) than ones that don't.

You shouldn't use comments to state the obvious - that's a waste of effort (and probably disqualifies the one we've used above!) - but if there's anything in your code that may cause confusion, there's no reason not to include them. And when one helps you to decipher an otherwise mysterious section of code, you'll be glad that you did.

Common Attributes for WML Elements

At this point, we've pretty much exhausted the things there are to say about our sample WML file, so it must be time to start thinking about extending it. Assuming for now that we're not going to create any more decks at this stage, and since WML is based on XML, we're left with two possibilities: adding more elements to our existing deck, or adding attributes to the elements that already exist. In a moment, we'll look at an example that features both of these operations, but we need just a little more theory before we do so.

In WML, there are three attributes that can be used with almost all elements: xml:lang, class, and id. The first of these, xml:lang, is optional, and its value defines the (human) language of any data that may be presented to the user, so that the user agent can modify its behavior if need be (to display text in a different direction, perhaps, or to change hyphenation rules). We won't be giving any further coverage to the attribute in this book.

By specifying a class attribute with the same value to several different elements, you make them all part of the same class. This fact has no direct relevance to the microbrowser, or to the users of your applications, but it could be used by some external program that was tasked with processing your decks in some way, as a way of dealing with many elements together. The WML specification states that user agents should ignore this attribute, so we won't spend any more time on it here.

Finally, the id attribute is used to provide an element with a unique name within a single deck, so that it's possible programmatically to tell two elements of the same type apart. This functionality is absolutely essential when your deck contains more than one card, as we're about to discover.

When we introduce more WML elements in the chapters to come, we'll often enumerate the attributes they support, but we won't list these three - it would rapidly become very repetitive. With the exception of using the id attribute with the *card> element, we won't be needing them.

The <card> Element

Although it's true that WML applications are made up of decks, the latter seldom function as much more than containers for cards, and it's in these that you'll spend the majority of your development time. A card can contain text and images to be displayed to the user, controls that enable the user to make selections, and input fields for the user to enter data.

By convention, WAP-enabled devices will display a single card at a time. If a card is too large to fit the display all at once, the device may split the card and show it as a sequence of screens, or use some other mechanism (such as scroll bars). It is important, therefore, that you keep your cards small and test them across a range of devices to ensure that what gets displayed is coherent.

The <card> Element's id Attribute

As you build a WML application, you will want the user to be able to navigate from one card in the deck, to another. This means that we need a card to be able to refer to another card in the deck, which in turn means that we need some way of distinguishing cards uniquely. Is this starting to sound familiar?

The <card> element's id attribute specifies a name for a card, and looks like this:

<card id="name">
  content
</card>

With that in mind, let's see what happens if we attempt a slightly more sophisticated example.

Continued...