WML is a markup language based on XML (Extensible Markup Language). It is designed for specifying user interface behavior and displaying content on wireless devices such as phones, pagers, and PDAs (Personal Digital Assistants).
The Wireless Application Protocol (WAP) Forum, an industry organization dedicated to developing open standards for wireless communication, has provided a formal specification for WML. This specification, which includes the Document Type Definition (DTD) for WML, is available on the WAP Forum Web site at:
http://www.wapforum.org
The document you are reading now, the WML Language Reference, is based on the WAP Forum's WML specification.
For a formal XML specification, see "Extensible Markup Language (XML), W3C Proposed Recommendation," available from the W3C Web site at:
http://www.w3.org
WML is designed to support a range of devices, which typically have the following characteristics:
The devices that currently support WML fall into two principal categories:
It is anticipated that as handheld devices with sophisticated capabilities, such as voice recognition, become available, many of them will also support WML.
Because WML supports a variety of devices with different capabilities, this document describes it with reference to a "least common denominator device" or "reference device". The reference device has the following characteristics:
ACCEPT and OPTIONS, the labels for which appear above the key in the phone display area
PREV key for navigating backward
The following section provides a brief overview of the syntax rules associated with writing WML code. For examples and additional discussion, see Chapter 1 of the UP.SDK Developer's Guide.
WML uses the XML document character set--currently the Universal Character Set of ISO/IEC-10646 (Unicode 2.0)--and supports any proper subset of the Unicode character set (for example, US-ASCII, ISO-8859-1, or UTF-8). You do not need to use full Unicode (UCS-4) encoding unless you are using a character set other than UTF-8.
Unlike HTML, WML is case-sensitive. You must specify elements, attributes, and enumerated attribute values in all lowercase. You should also keep case-sensitivity in mind when you name cards or variables. For example, variable1, Variable1, and vaRiable1 are all different variables.
In WML, white space is defined as any of the following:
Except where specifically noted, WML converts one or more contiguous newlines, carriage returns, tabs, or spaces to a single space--in other words, ignores white space beyond a single character. For example, UP.Phones interpret the following code samples as equivalent:
| Sample 1 | Sample 2 | |
|---|---|---|
|
<wml><card><p> Some
text
</p> </card> </wml> |
|
<wml> <card> <p> Some text </p> </card> </wml> |
The examples in this manual use newlines and tabs for readability. This formatting, however, is not required (and is, in fact, removed by the UP.Link Server before transmission to the UP.Phone).
All WML decks must specify the following XML document type declaration at the beginning of each file:
wml_1.1.xml">
To add this prologue to any deck automatically, you can use the OutputDeck() function, one of several Perl utilities provided in the UP.SDK that help automate routine aspects of creating a WML service. For more information about the OutputDeck() function, see Chapter 5 of the UP.SDK Tools and APIs Reference.
To create a valid WML message entity (MIME type), you must specify the following content type header before the document prologue (see above):
Like the document prologue, the UP.SDK provides utilities that automate the process of creating valid HTTP responses. For more information, see Chapter 3 of the UP.SDK Developer's Guide and Chapters 7 and 8 of the UP.SDK Tools and APIs Reference.
Most WML elements have one or more attributes, some of which are required while others are optional. Attributes let you specify additional information about how the device should handle the element. Although the exact syntax of a WML statement depends on whether or not the element has content, attributes always appear within the element start tag, as shown below:
You must enclose attribute values within single (') or double (") quotation marks and separate each attribute-value pair with white space (see above). White space is not allowed, however, between the attribute name, equal sign, and attribute value.
Much like UNIX shell variables, you can use variables in your WML code in formatted text, URLs, selection items, or default values. To substitute a variable value, reference the variable using the syntax $(myvar).
NOTE
You can alternately reference a variable using the syntax $myvar, which, in most cases, yields the same results as using $(myvar). Using parentheses, however, is the preferred convention since it ensures correct value substitution.
The UP.Browser automatically applies URL escaping rules based on the context. If, however, you want to override the normal escaping rules for variables within URL strings, you can use the following options to force a particular behavior:
The UP.Browser ignores these options if you specify them for variables in contexts other than URL strings.
WML reserves the <, >, ', ", and & characters. To display one of these characters in formatted text, you must specify one of the following character elements.
The semicolon (;) is part of the character element and must be included. If you omit it, the WML compiler generates an error message.
& to specify the ampersand (&) character when you use CGI arguments within URL strings.