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:
Small display size (relative to conventional personal computers)
Limited memory and CPU size
Low bandwith, high-latency wireless connectivity
The devices that currently support WML fall into two principal categories:
Phones--which typically feature text displays of 4 to 10 lines and support user input through numeric and function keys.
Personal Digital Assistants (PDAs)--which typically feature display resolutions of 100X100 pixels (or better) and support enhanced user input through keypads, pointers, or handwriting recognition.
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:
A display area having a width of 12 (fixed-size) characters and a height of 4 lines, including one line reserved for function key labels (described below)
Support for the ASCII printable character set
Numeric and alphabetic character entry
Choice selection (using arrow or numeric keys)
Two programmable function keys, referred to as ACCEPT and OPTIONS, the labels for which appear above the key in the phone display area
A PREV key for navigating backward
Vertical scrolling with arrow keys
Horizontal scrolling of non-wrapping lines
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 and UTF-16.
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> |
<wml> <p> </p> |
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:
<?xml version="1.0"?>
<!DOCTYPE wml PUBLIC "-//WAPFORUM//DTD WML 1.1//EN"
"http://www.wapforum.org/DTD/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.
NOTE If you use the Openwave extensions in your WML content, you must include the following DOCTYPE header in the WML deck:
<!DOCTYPE wml PUBLIC "-//PHONE.COM//DTD WML 1.1//EN"
"http://www.phone.com/dtd/wml11.dtd" >
IMPORTANT Applications can make use of these extensions when accessed by a phone running UP.Browser 4.0 or higher. To identify the WAP browser type and version, capture the WAP-standard USER_AGENT header in the HTTP request. See the whoami.cgi example for implementation details.
To create a valid WML message entity (MIME type), you must specify the following content type header before the document prologue (see above):
Content-type: text/vnd.wap.wml
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.
IMPORTANT You must leave (at least) one blank line between the content type and the document prologue--if you omit this line, the compiler will generate an error.
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:
<element a1="value1" a2="value2" ...> content </element>
<element a1="value1" a2="value2" .../>
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).
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.
| Character | Character element |
|---|---|
<
|
|
>
|
|
'
|
|
"
|
|
&
|
|
$
|
|
|
Non-breaking space |
|
|
Soft hyphen |
­
|
The semicolon (;) is part of the character element and must be included. If you omit it, the WML compiler generates an error message.
IMPORTANT
Unlike HTML, you must use the special character element & to specify the ampersand (&) character when you use CGI arguments within URL strings.