WAP/WML

Wap Server
Setup Tutorial
.....................3
Publishing WAP 1.x / WAP 2.0 Content over the Mobile Internet................................3
What are MIME Types?................................................................................................3
WAP 1.x / WAP 2.0 MIME Types and File Extensions.................................................4
Setting up MIME Types with Apache...........................................................................5
Setting up MIME Types with Tomcat...........................................................................6
Setting up MIME Types with Microsoft IIS..................................................................6
Setting up MIME Types without Administrator Rights.................................................7
If the Web / WAP Server is Apache...........................................................................7
Using a Server-side Technology................................................................................8
Setting up Default Documents of WAP / Web Sites......................................................9
What is a Default Document / Directory Index / Welcome File?..............................9
Why Should we Set the Default Document of a WAP Site?.....................................9
Setting Default Documents of WAP / Web Sites with Apache..................................9
Setting Default Documents of WAP / Web Sites with Tomcat................................10
Setting Default Documents of WAP / Web Sites with Microsoft IIS..........................10
WML Tutorial
...................12
Wireless Markup Language / WML Tutorial..............................................................12
WML (Wireless Markup Language) Introduction.......................................................12
What is WML 1.x?..................................................................................................12
WAP 2.0...................................................................................................................12
WML 2.0.................................................................................................................13
WML Deck and Card..................................................................................................13
WML Document Structure......................................................................................13
Hello World WML Example....................................................................................13
Prolog......................................................................................................................14
XML Declaration and Character Encoding.............................................................14
DOCTYPE Declaration...........................................................................................15
<wml> Element.......................................................................................................16
<card> Element.......................................................................................................16
<p> Element............................................................................................................16

WML Generic
Metadata:
<meta>.......19
WML Cache Control: Setting Expiry Period of a WML File......................................20
Wap Server Setup Tutorial
Publishing WAP 1.x / WAP 2.0 Content over the Mobile Internet

The steps for publishing WAP 1.x or WAP 2.0 content over the mobile Internet are very
straightforward:

1. Install and configure a web server as if you were setting up a web site.
2. Make sure the MIME types of WAP 1.x and WAP 2.0 documents have been set
up properly in the configuration file of the web server.

3. Place your WAP 1.x and WAP 2.0 documents in the web server as if they were
ordinary web documents.

4. Start the web server.

5. Make sure the web server is connected to the wired Internet.

For example, if you want to view the helloWorldEg1.xhtml document of our XHTML
MP tutorial on a mobile phone, you will type
http://www.developershome.com/examples/wap/xhtmlmp/helloWorldEg1.xhtml in the
WAP browser.

If you have not registered a domain name for your WAP site, you can specify the IP
address of your WAP server as the host part of the URL. For example, let's say the IP
address is 123.123.123.123. To visit the WAP site, you will enter
http://123.123.123.123/ on a WAP browser.

As mentioned before, if you are creating a secure WAP application like mobile banking,
you need to consider whether to set up your own WAP gateway to ensure maximum
security.

What are MIME Types?

When a web or WAP browser receives a document, it needs some way to

determine the type of content the document contains so that it can decide how to
deal with the document.
MIME (Multipurpose Internet Mail Extensions) is developed for such purpose.

A MIME type is associated to a file type.

For example, the MIME type "text/html" is associated to HTML files and the
MIME type "text/vnd.wap.wml" is associated to WML files.

Web servers choose a suitable MIME type and include it in an HTTP response
automatically. They keep a conversion table that contains the mappings between MIME
types and file extensions.
For example, let's say a WAP browser requests a WML file named helloWorld.wml from
a web / WAP server. The web / WAP server will search for the MIME type associated to
the ".wml" extension in the conversion table and includes it in the HTTP response
automatically.

WAP 1.x / WAP 2.0 MIME Types and File Extensions

Before a web / WAP server can be used to serve WAP 1.x or WAP 2.0 content, you need
to make sure its MIME settings have been configured properly. Otherwise WAP
browsers cannot display the WAP pages.

The latest versions of some web servers have set the MIME types of WAP 1.x and WAP
2.0 properly by default, which means you do not need to modify anything.

The following table lists the MIME types of WAP 1.x:

File extension MIME type Content of the file

.wml text/vnd.wap.wml WML markup in plain-text

form

.wmlc application/vnd.wap.wmlc Compiled WML markup

.wbmp image/vnd.wap.wbmp WBMP image

.wmls text/vnd.wap.wmlscript WMLScript code in plain-

text form

.wmlsc application/vnd.wap.wmlscriptc Compiled WMLScript

code

The following table lists the MIME types of WAP 2.0:

File extension MIME type Content of the file

application/vnd.wap.xhtml+xml
.xhtml or .html or .htm XHTML MP markup in
or plain-text form

application/xhtml+xml

or

text/html
 File extension MIME type Content of the file

.css text/css WCSS (WAP CSS or

Wireless CSS) code in
plain-text form

As you can see in the above table, there are three possible MIME types for XHTML MP
files:

application/vnd.wap.xhtml+xml
This is the MIME type specified by the Open Mobile Alliance. If
"application/vnd.wap.xhtml+xml" is not set as the MIME type, XHTML MP
documents cannot be viewed on some WAP browsers (e.g. browsers on some
Nokia Series 60 mobile phones).
application/xhtml+xml
This is the MIME type for XHTML Family document types. (XHTML MP
belongs to the XHTML family.)

text/html
This is the MIME type for HTML documents. XHTML MP is HTML-
compatible.

Advantage of using "text/html": Using "text/html" ensures that XHTML MP

documents can be displayed on ordinary web browsers. Some web browsers
(e.g. Internet Explorer 6) do not display documents with MIME types like
"application/vnd.wap.xhtml+xml" and "application/xhtml+xml".
For example, let's say "application/vnd.wap.xhtml+xml" is associated to your
XHTML MP documents. If you use IE 6 to load any one of them, it will pop up
a dialog box asking you whether to save the file on the hard disk.

Disadvantage of using "text/html": Browsers will parse XHTML MP

documents as HTML documents but not XML documents. Hence, invalid XML
syntax may not be detected.

Sometimes you may want to detect the MIME types supported by a client
browser and then assign an appropriate MIME type to your XHTML MP
documents dynamically. For example, if you find that a browser supports the
"application/vnd.wap.xhtml+xml" type, you will assign
"application/vnd.wap.xhtml+xml" to your XHTML MP documents. If you find
that a browser only supports the "text/html" type (e.g. IE 6), you will assign
"text/html" to your XHTML MP documents. Please refer to the "Choosing
MIME Types Dynamically" section of our XHTML MP tutorial if you want to
learn the details.
Setting up MIME Types with Apache

In Apache, the mappings between MIME types and file extensions are stored in the
configuration file apache_home/conf/mime.types, where apache_home is the path under
which Apache was installed on your server.

To set up MIME types, open the mime.types file. Lines that begin with the # character
are comments and they will be ignored by Apache. Each of the other lines begins with a
MIME type, then follows by one or more file extensions. It has the following form:

mimeType fileExtension1 fileExtension2 fileExtension3 ...

Here are some examples:

text/html html htm

application/vnd.wap.xhtml+xml xhtml
text/vnd.wap.wml wml
text/vnd.wap.wmlscript wmls
image/vnd.wap.wbmp wbmp

Setting up MIME Types with Tomcat

In Tomcat 5.x and 4.x, the default mappings between MIME types and file extensions
are stored in the file tomcat_home/conf/web.xml, where tomcat_home is the path under
which Tomcat was installed on your server. The mappings specified there are applied to
all web / WAP applications hosted on your Tomcat server. Application-specific
mappings should be set in the WEB-INF/web.xml file under the directory of your web /
WAP application.

Each mapping is specified with the <mime-mapping>, <extension> and <mime-type>

tags. Here is an example:

<web-app>

...

<mime-mapping>
<extension>xhtml</extension>
<mime-type>application/vnd.wap.xhtml+xml</mime-type>
</mime-mapping>

<mime-mapping>
<extension>wml</extension>
<mime-type>text/vnd.wap.wml</mime-type>
</mime-mapping>

<mime-mapping>
<extension>wmls</extension>
<mime-type>text/vnd.wap.wmlscript</mime-type>
</mime-mapping>
 <mime-mapping>
<extension>wbmp</extension>
<mime-type>image/vnd.wap.wbmp</mime-type>
</mime-mapping>

...

</web-app>

Setting up MIME Types with Microsoft IIS

Microsoft IIS provides a GUI for setting up MIME types. Below lists the steps for
setting up MIME types with IIS 5.0 on Microsoft Windows 2000 Professional:

1. Bring up the Internet Information Services window by selecting Control Panel

-> Administrative Tools -> Internet Service Manager.
2. In the tree on the left-hand side, you should see an item whose caption is your
computer's name. Right-click on it to pop up a menu.

3. Click Properties in the menu to bring up the Properties window.

4. Click the Edit button located in the Computer MIME Map frame to bring up the
File Types window.

5. In the File Types window, you can see a list of MIME mappings. Use the buttons
labeled "New Type...", "Remove" and "Edit..." to make any change you want.

The steps for setting up MIME types with other versions of IIS should be similar.

If your IIS is of version 3.0 or below, the procedure is less user-friendly. It involves
editing the registry at the key
HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\
Services\InetInfo\Parameters\MimeMap. Please refer to other sources for the details.

Setting up MIME Types without Administrator Rights

The ways described above for setting up MIME types involve changing the
configuration of the WAP / web server, which requires you to have administrator rights.
However, in many situations, you do not have administrator rights. For example, it is
common to host WAP / web sites on a server managed by a web hosting company.

In general, there are two ways for setting MIME types when you do not have
administrator rights:

1. Using a .htaccess file (for Apache)

2. Using a server-side technology
If the Web / WAP Server is Apache...

If the web / WAP server is Apache, you can place the MIME settings in a file called
.htaccess using the format below:

addtype mimeType fileExtension

For example, your .htaccess file may contain something like this:

addtype text/vnd.wap.wml wml

addtype application/vnd.wap.wmlc wmlc
addtype image/vnd.wap.wbmp wbmp
addtype text/vnd.wap.wmlscript wmls
addtype application/vnd.wap.wmlscriptc wmlsc
addtype application/vnd.wap.xhtml+xml xhtml

The new MIME settings will be applied to the directory that contains the .htaccess file
and all its subdirectories.

Notes:

The .htaccess file should be set to world-readable.

The administrator may configure the web / WAP server to ignore .htaccess files.
In such cases, the above method will not work.

Using a Server-side Technology

Server-side technologies such as ASP, ColdFusion, JSP, Perl and PHP can be used to set
the MIME type of a document without the need to change the configuration file of the
web / WAP server.

For example, let's say we have a XHTML MP file helloWorld.xhtml with the following
content:

<?xml version="1.0"?>
<!DOCTYPE html PUBLIC "-//WAPFORUM//DTD XHTML Mobile 1.0//EN"
"http://www.wapforum.org/DTD/xhtml-mobile10.dtd">

<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<title>XHTML MP Example</title>
</head>

<body>
<p>Hello World</p>
</body>
</html>
Suppose the web / WAP server supports ASP. We can rename the above file to
helloWorld.asp and add a line of ASP code to it, like this:

<?xml version="1.0"?>
<!DOCTYPE html PUBLIC "-//WAPFORUM//DTD XHTML Mobile 1.0//EN"
"http://www.wapforum.org/DTD/xhtml-mobile10.dtd">

<% Response.ContentType = "application/vnd.wap.xhtml+xml" %>

<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<title>XHTML MP Example</title>
</head>

<body>
<p>Hello World</p>
</body>
</html>

Now if the helloWorld.asp file is requested, the web / WAP server will set the MIME
type "application/vnd.wap.xhtml+xml" in the HTTP response.

In the following sections, we will describe how to set MIME types with ASP,
ColdFusion, JSP, Perl and PHP. Most servers provided by web hosting companies
support at least one of these technologies.

Setting up Default Documents of WAP / Web Sites

What is a Default Document / Directory Index / Welcome File?

The default document of a WAP / web site is the file to be served if the user
requests a directory.
It can also be called the directory index or welcome file.

Let's say the default document is index.html. If the user requests the URL
http://www.developershome.com/, the file located at
http://www.developershome.com/index.html will be served to the user.

Why Should we Set the Default Document of a WAP Site?

Make sure you have set an appropriate file as the default document of your WAP site
because:

Typing text on a mobile phone using the keypad is very time-consuming.

Users like short URLs. For example, they like
"http://wap.developershome.com/" more than
"http://wap.developershome.com/index.xhtml".

On most web servers, the pre-set default document is very often index.html, index.htm,
default.html or default.htm. Since you are now setting up a WAP site, one thing that you
may want to do is to change the file extension of the default document to ".wml" or
".xhtml".

In the following sections, you will learn how to set the default document of WAP / web
sites with Apache, Tomcat and IIS.

Setting Default Documents of WAP / Web Sites with Apache

In Apache, the default documents of a WAP / web site are specified with the
DirectoryIndex directive in the configuration file located at
apache_home/conf/httpd.conf, where apache_home is the path under which Apache was
installed on your server.

To change the setting, search for the line that begins with "DirectoryIndex" in the
httpd.conf file. Then you can modify the line according to the following form:

DirectoryIndex file1 file2 file3 ...

Here is an example:

DirectoryIndex index.wml default.wml

The above line specifies that:

When a user requests a directory, the web / WAP server should serve index.wml.
If index.wml does not exist in the directory, the web / WAP server should serve
default.wml.

If the directory does not contain both index.wml and default.wml, the web / WAP
server may send back the directory listing (a list of files contained in the
directory) or the 404 "file not found" error to the client. The actual action
depends on the configuration of the web / WAP server.

Setting Default Documents of WAP / Web Sites with Tomcat

In Tomcat 5.x and 4.x, the pre-set default document settings are stored in the file
tomcat_home/conf/web.xml, where tomcat_home is the path under which Tomcat was
installed. The settings in this file will be applied to all WAP / web sites hosted on your
Tomcat server.

Default documents are specified with the <welcome-file-list> and <welcome-file> tags.
Here is an example:

<web-app>
...
<welcome-file-list>
<welcome-file>index.wml</welcome-file>
<welcome-file>index.jsp</welcome-file>
</welcome-file-list>
...
</web-app>

The above example specifies that:

When a user requests a directory, the web / WAP server should serve index.wml.
If index.wml does not exist in the directory, the web / WAP server should serve
index.jsp.

If the directory does not contain both index.wml and index.jsp, the web / WAP
server may send back the directory listing (a list of files contained in the
directory) or the 404 "file not found" error to the client. The actual action
depends on the configuration of the web / WAP server.

If you want the settings to be applied to only one WAP site but not to all sites hosted on
your Tomcat server, you should place the above markup in WEB-INF/web.xml under
the directory of that WAP site, but not in tomcat_home/conf/web.xml.

If the <welcome-file-list> tag exists in both tomcat_home/conf/web.xml and WEB-

INF/web.wml, the settings specified in WEB-INF/web.xml will override those specified
in tomcat_home/conf/web.xml.

Setting Default Documents of WAP / Web Sites with Microsoft IIS

Microsoft IIS provides a GUI for setting up default documents of WAP / web sites.
Below lists the steps for setting up default documents with IIS 5.0 on Microsoft
Windows 2000 Professional:

1. Bring up the Internet Information Services window by selecting Control Panel

-> Administrative Tools -> Internet Service Manager.
2. In the tree on the left-hand side, you should see an item whose caption is your
computer's name. Right-click on it to pop up a menu.

3. Click Properties in the menu to bring up the Properties window.

4. Select the WWW Service item in the Master Properties combo box and click the
Edit button next to it.

5. In the Default Web Site Properties window, click the Documents tab.

6. Click the Enable Default Document check box if it is not checked. Then use the
buttons labeled "New..." and "Remove" to add or remove file names. The file at
the top of the list will be served first.

The steps for setting default documents with other versions of IIS should be similar.
WML Tutorial
Wireless Markup Language / WML Tutorial

WML (Wireless Markup Language) is the first markup language standard for wireless
devices. It is supported by all the major mobile phone manufacturers. At the beginning
of this WML tutorial, you can learn about the basics of WML, such as the deck and card
concept, WML's document structure and syntax, etc. Then topics like font styles,
images, tables, anchor links and softkeys will be covered. After that we will move on to
more advanced topics of WML like events, input elements, variables, and the
submission of form data to the server. Plenty of code examples are given in the WML
tutorial to help you understand the concepts and techniques.

WML (Wireless Markup Language) Introduction

What is WML 1.x?

WML (Wireless Markup Language) 1.x is the markup language defined in the WAP 1.x
specification. WAP is the standard created by the WAP Forum (now the Open Mobile
Alliance [OMA]) that brings the World Wide Web to wireless devices. It specifies the
protocol stack and application environment of mobile Internet browsing applications.

The role of WML in mobile Internet applications is the same as that of HTML in web
applications. WAP sites are written in WML, while web sites are written in HTML.

WML 1.x is very similar to HTML. Both of them use tags and are written in plain text
format. Some tags in WML 1.x are directly borrowed from HTML. If you have
experience in using the HTML markup language, you should be able to learn WML 1.x
quickly.

Some features of WML 1.x are specific to wireless devices. For example, WML 1.x
provides a way for developers to program the softkeys of mobile phones. This feature is
not supported in HTML since computers do not have any softkey.

The most up-to-date version of the WAP 1.x specification is WAP 1.2.1, which defines
WML 1.3.

WML files have the extension ".wml". The MIME type of WML is "text/vnd.wap.wml".

WML supports client-side scripting. The scripting language supported is called

WMLScript. Its syntax is based on JavaScript. If you want to learn it, our WMLScript
tutorial will be a good starting point for you.

WAP 2.0

WAP 1.x is an earlier version of the WAP standard. The most current version is WAP
2.0. The markup language defined in WAP 2.0 is XHTML MP (XHTML Mobile
Profile). It is a subset of the XHTML used on the web. XHTML MP supports a mobile
version of cascading style sheet called WCSS (WAP CSS). It is a subset of the CSS2
used on the web plus some WAP specific extensions.

Most of the new mobile phone models released are WAP 2.0-enabled. As WAP 2.0 is
backward compatible to WAP 1.x, WAP 2.0-enabled mobile devices can display both
XHTML MP and WML documents.

WML 1.x is an earlier technology. However, that does not mean it is of no use, since a
lot of wireless devices that only supports WML 1.x are still being used. Besides, some
useful features of WML are not available in XHTML MP. For example, XHTML MP
does not support events, variables and client-side scripting. The major WML features
lost in XHTML MP are discussed in the "WML Features Lost in XHTML MP" section
of our XHTML MP tutorial.

If you write the markup of your mobile Internet site in WML, both old and new WAP-
enabled wireless devices can be used to view your mobile Internet site. The user base of
your WAP application is maximized.

WML 2.0

WAP site developers need not to care about WML 2.0. WML 2.0 is created for
backward compatibility purposes and it is not for use by WAP site developers. To
develop a WAP site with the WAP 2.0 standard, use XHTML Mobile Profile.

WML Deck and Card

A major difference between HTML and WML is that the basic unit of navigation in
HTML is a page, while that in WML is a card. A WML file can contain multiple cards
and they form a deck. When a user goes to a WAP site, the mobile browser loads a
WML file that contains a deck of cards from the server. Only one card will be shown on
the screen of the wireless device each time. If the user goes to another card of the same
deck, the mobile browser does not have to send any request to the server since the file
that contains the deck is already stored in the wireless device.

WML is designed in this way because wireless devices have a high latency for
connecting to the server. Downloading a deck of cards at a time can lower the number
of round trips to the server.

You can put links, text, images, input fields, option boxes and many other elements in a
card.

WML Document Structure

Hello World WML Example

Let's take a look at our first WML example. It shows the structure of a typical WML
document.

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

<wml>
<card id="card1" title="WML Tutorial">
<p>Hello World</p>
</card>

<card id="card2" title="WML Tutorial">

<p>Welcome to the world of WML</p>
</card>
</wml>

The result of the "Hello World" WML example in mobile phone emulators is shown
below:

Sony Ericsson T610 Sony Ericsson T68i Nokia Mobile Browser 4.0

In the following sections, we will describe the elements used in the above WML
example.

Prolog

Prolog refers to the first two lines of our "Hello World" WML example:

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

Every WML document starts with the prolog. The first line is the XML declaration and
the second line is the DOCTYPE declaration.

The prolog components are not WML elements and they should not be closed, i.e. you
should not give them an end tag or finish them with />.

XML Declaration and Character Encoding

All WML documents are XML documents. So, there is an XML declaration at the start.
The XML declaration specifies the XML version of the document. The character
encoding of the document can also be specified here, like this:

<?xml version="1.0" encoding="UTF-8"?>

The above line states that the XML version of the WML document is 1.0 and the
character encoding is UTF-8. If the character encoding of the WML document is UTF-8
or UTF-16, there is no need to declare the character encoding as it can be detected
automatically.
Note that there should have no whitespace before the XML declaration. If not, some
WAP browsers or WAP gateways cannot process the WML file.

DOCTYPE Declaration

All WML documents must have the DOCTYPE declaration. It should be placed
between the XML declaration and the <wml> element. Below is the DOCTYPE
declaration for WML 1.3. You can simply copy and paste it into your WML files.

<!DOCTYPE wml PUBLIC "-//WAPFORUM//DTD WML 1.3//EN"

"http://www.wapforum.org/DTD/wml13.dtd">

The DOCTYPE declaration specifies the name of the DTD (Document Type Definition)
and the URL to the DTD. The DTD contains information about the syntax of the
markup language. It defines what elements and attributes can be used in the markup and
the rules that they should be used. For example, the DTD of WML specifies that the
<card> element should be enclosed in the <wml></wml> tag pair. If you do not follow
this rule, your WML document is said to be invalid. WAP browsers will complain if you
try to view an invalid WML document.

If you are interested in the DTD of WML 1.3, it can be downloaded at

http://www.wapforum.org/DTD/wml13.dtd.

If you want your WML code to conform to an earlier version of the WAP standard, you
have to change the DTD.

This is the DTD declaration for WML 1.2:

<!DOCTYPE wml PUBLIC "-//WAPFORUM//DTD WML 1.2//EN"

"http://www.wapforum.org/DTD/wml12.dtd">

This is the DTD declaration for WML 1.1:

<!DOCTYPE wml PUBLIC "-//WAPFORUM//DTD WML 1.1//EN"

"http://www.wapforum.org/DTD/wml_1.1.xml">

Validation tools can be used to check whether your WML document conforms to the
WML language rules by comparing your WML document with the DTD specified in the
DOCTYPE declaration. Such validation tools are integrated in some IDEs.

<wml> Element

<wml> is the root element of WML. All other elements should be enclosed within the
<wml></wml> tags.

<card> Element

The <card> element specifies the content of a card. There are two cards in our Hello
World WML example. As you can see in the earlier screenshots, only one card is
displayed at a time. We will discuss how to navigate from one card to another when we
talk about anchor links later in this tutorial.

In our Hello World WML example, two attributes, id and title, have been specified to
the <card> tag. We use the id attribute to define a unique ID for a card. Card IDs are
needed for navigation between cards. However, the id attribute has no use in the Hello
World WML example and it is OK to remove it.

The title attribute is used to set the title of a card. Typically, a title is displayed at the top
of a wireless device's screen. Most WAP browsers display the title of a card, although a
few very old ones do not. If the title is too long, WAP browsers will truncate the title to
match the size of the title bar.

Unlike HTML 4.01 Transitional, text cannot be enclosed directly in the <card></card>
tag pair. For example, the following markup code is incorrect in WML:

<card id="card1" title="WML Tutorial">

Hello world. Welcome to our WML tutorial.
</card>

To correct the above WML markup code, enclose the text in <p></p> tags. The
following markup code is the correct version of the previous one:

<card id="card1" title="WML Tutorial">

<p>Hello world. Welcome to our WML tutorial.</p>
</card>

<p> Element

The <p> element defines a paragraph of text. Other content such as images can also be
included in a paragraph. WAP browsers always render a paragraph on a new line.

The <p> element supports two attributes: align and mode. The align attribute is used to
change the horizontal alignment of a paragraph. The values left, center and right are
supported. The following WML example illustrates how to align a paragraph centrally
using the align attribute:

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

<wml>
<card id="card1" title="WML Tutorial">
<p align="center">Hello world. Welcome to our WML tutorial.</p>
</card>
</wml>

Sony Ericsson T610 Sony Ericsson T68i Nokia Mobile Browser 4.0
The mode attribute is used to set the text-wrapping mode. Two values, wrap and
nowrap, are supported. If wrap is specified to the mode attribute, text longer than the
screen width will be broken apart and displayed on multiple lines. If nowrap is specified
to the mode attribute, the text of the paragraph will be displayed on a single line and
how a long line is displayed depends on the WAP browser used. For example:

Nokia Mobile Browser 4.0

It supports horizontal scrolling. You can see the text off the screen by pressing
the "Left" or "Right" button.
Sony Ericsson T610 and T68i mobile phone emulators
A line of text longer than the screen width is divided into smaller parts and they
are displayed on the screen alternately.

Openwave Mobile Browser 6.2.2

A line of text longer than the screen width is displayed using a marquee
animation, i.e. the line of text scrolls across the screen.

The following WML example illustrates the effect of the "nowrap" and "wrap" mode on
some mobile phone browsers:

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

<wml>
<card id="card1" title="WML Tutorial">
<p mode="nowrap">Hello world. Welcome to our WML tutorial.</p>
<p mode="wrap">You can learn how to build your own WML site in this
tutorial.</p>
</card>
</wml>

Sony Ericsson T610

Sony Ericsson T68i

Nokia Mobile Browser 4.0

Note that if a paragraph's mode attribute is not specified and it is not the first paragraph
of the current card, the text-wrapping mode of the previous paragraph will be applied to
it. For example, if we change the markup of the previous WML example to the lines
below, both paragraphs in the card will be displayed with the "nowrap" mode.

...
<card id="card1" title="WML Tutorial">
 <p mode="nowrap">Hello world. Welcome to our WML tutorial.</p>
<p>You can learn how to build your own WML site in this tutorial.</p>
</card>
...

XML is a stricter markup language than HTML. As WML documents are XML
documents, the syntax rules of WML are stricter than HTML. For example, tags and
attributes in WML are case-sensitive and they must be in lowercase, while those in
HTML are case-insensitive. Thus, the following markup code is invalid in WML but not
in HTML:

<P>WML tutorial paragraph 1</P>

<p>WML tutorial paragraph 2</P>
<p ALIGN="right">WML tutorial paragraph 3</P>

This is the correct version of the above markup code in WML:

<p>WML tutorial paragraph 1</p>

<p>WML tutorial paragraph 2</p>
<p align="right">WML tutorial paragraph 3</p>

Another example is that you must close all tags in WML, while you can omit some end
tags in HTML. For example, the following markup code is invalid in WML but not in
HTML:

<p>WML tutorial paragraph 1

<p>WML tutorial paragraph 2
<p>WML tutorial paragraph 3

The above markup code becomes valid in both HTML and WML if you close all the
<p> tags properly, like this:

<p>WML tutorial paragraph 1</p>

<p>WML tutorial paragraph 2</p>
<p>WML tutorial paragraph 3</p>

Some tags do not have any content to be enclosed, so they do not come in pairs. One
example is the <br> tag, which is used to tell a browser to start a new line. To close such
tags, put a "/" before ">", like <br/>. You need to use <br/> instead of <br> in WML.

Web browsers are more tolerant towards invalid markup than WML browsers. If a
HTML page contains markup that does not conform to the specification, a web browser
will still try to understand the HTML page and display it as best as it can. WML
browsers will not do this. If a WML document contains invalid markup, the WML
browser will output an error message directly.

WML Generic Metadata: <meta>

You can specify some generic metadata in your WML file using the <meta/> tag.
Metadata is placed at the document head. The <head> and </head> tags mark the start
and end of the document head respectively. A WAP browser will ignore the metadata if
it does not understand the metadata's meaning. You can specify metadata of any sort in a
WML file without affecting the cards' look. For example, you may want to state the
author name in your WML file without displaying it on the screen. The following
example illustrates how to do this:

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

<wml>
<head>
<meta name="author" content="Andrew"/>
</head>
<card id="card1" title="WML Tutorial">
<p>Hello World</p>
</card>
</wml>

WML Cache Control: Setting Expiry Period of a WML File

One use of the <meta/> tag is to set the expiry period of a WML file in cache. Cache is
some memory space in a wireless device that stores temporarily the WML files
downloaded from servers. If the WAP browser finds that a WML file requested by you
is located in the cache and it has not been expired, the WAP browser will display the file
in the cache without contacting the server so as to minimize the delay. If your WML
card contains time-sensitive content such as financial data, you may want to set a small
value or even zero for the expiry period, so that users will not see an outdated WML
card later. The following WML example shows how to use the <meta/> tag to set the
expiry period of a WML file to zero:

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

<wml>
<head>
<meta http-equiv="Cache-Control" content="no-cache"/>
</head>

<card id="card1" title="WML Tutorial">

<p>Hello World. Welcome to our WML tutorial.</p>
</card>
</wml>

Here is another example that demonstrates how to set the expiry period of a WML file
to 300 seconds:

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

<wml>
<head>
<meta http-equiv="Cache-Control" content="max-age=300"/>
</head>
<card id="card1" title="WML Tutorial">
<p>Hello World. Welcome to our WML tutorial.</p>
</card>
</wml>

The line:

<meta http-equiv="Cache-Control" content="max-age=0"/>

has the same effect as:

<meta http-equiv="Cache-Control" content="no-cache"/>

Note that the actual effect of the above WML code is device-dependent. Some WAP
browsers do not use the above ways for cache control. Besides, some WAP browsers do
not have cache. However, as stated earlier, if a WAP browser does not understand the
metadata's meaning, it will simply ignore it.

Another note is that although some WAP browsers do not support the use of the <meta/>
tag for cache control, they do understand the HTTP header line "Cache-Control: no-
cache". The solution for such cases is to set the Cache-Control HTTP header in the
HTTP response at the server-side. Server-side technologies such as ASP, JSP, PHP, Perl,
etc, can be used to do that. This method can also be used for image cache control.

Comments in WML

Comments are placed inside <!-- --> in WML. This is the same as HTML. For example,
the following lines are comments. WAP browsers ignore all comments.

<!-- This is a comment in WML -->

<!-- This is a multi-line
comment -->

Line Breaking in WML

<br/> is the line breaking tag in WML, which is the same as that in HTML. The
following WML example demonstrates the usage of line breaks:

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

<wml>
<card id="card1" title="Line Break">
 <p>
Before br<br/>After br
</p>
</card>
</wml>

The screenshots below show the result of the above WML example in some mobile
phone browsers. As you can see, the text after the <br/> tag starts on a new line.

Sony Ericsson T610 Sony Ericsson T68i Nokia Mobile Browser 4.0

Font Size and Style in WML

WML includes a number of tags that can be used to change the font size and style of the
text. However, some older WAP browsers do not support these tags or only support a
subset of these tags, even though these tags are defined by the WML specification.
Unsupported WML tags will be ignored by WAP browsers but will not cause any error.

Let's first have a look at the following WML example. We will then describe the font
size and font style tags one by one.

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

<wml>
<card id="card1" title="Font Style">
<p>
<b>Bold</b><br/>
<i>Italic</i><br/>
<u>Underline</u><br/>
<small>Small</small><br/>
<big>Big</big><br/>
<em>Emphasis</em><br/>
<strong>Strong</strong>
</p>
</card>
</wml>

The <b>, <i> and <u> tags mean bold, italic and underline respectively.

The <small> and <big> tags are used to reduce and increase the text size respectively.

The emphasis (<em>) and strong emphasis (<strong>) styles are similar. A WAP
browser will display text with the emphasis or strong emphasis style in some way that
makes it more noticeable. The actual effect depends on the mobile device.
The following screenshots show you the effect of the above font size and font style tags
in some mobile phone browsers. The result will be somewhat different in other mobile
phone models.

Sony Ericsson T610

Nokia Mobile Browser 4.0
Sony Ericsson T68i

WML Preformatted Text: <pre>

The <pre> tag is used to specify preformatted text in WML. Preformatted text is text of
which the format follows the way it is typed in the WML document.

In WML, leading and trailing whitespaces (i.e. spaces, tabs and newlines) of a
paragraph are not displayed. Furthermore, two or more whitespaces in a paragraph are
shown as one whitespace on the screen of mobile devices. Such behavior is
demonstrated in the following WML example.

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

<wml>
<card id="card1" title="WML Tutorial">
<p> Hello, welcome
to
our
WML tutorial .</p>
</card>
</wml>

Sony Ericsson T610 Sony Ericsson T68i Nokia Mobile Browser 4.0

To preserve the formatting of the text, you have to use the <pre> element. WAP
browsers treat the content enclosed in the <pre></pre> tag pair as preformatted and
whitespaces are left intact.

The following WML example illustrates how to use the <pre> element:

<?xml version="1.0"?>
<!DOCTYPE wml PUBLIC "-//WAPFORUM//DTD WML 1.3//EN"
"http://www.wapforum.org/DTD/wml13.dtd">
<wml>
<card id="card1" title="WML Tutorial">
<pre> Hello, welcome
to
our
WML tutorial .</pre>
</card>
</wml>

The result of the above WML example in WAP browsers is shown below (the screenshot
for Sony Ericsson T68i is not shown since the <pre> element does not work in the
emulator):

Sony Ericsson T610

Nokia Mobile
Browser 4.0

WML Images

Wireless Bitmap (WBMP)

WML cards can contain images. In the early days, WAP-enabled wireless devices only
supported the Wireless Bitmap (WBMP) image format. WBMP images can only contain
two colors: black and white. Also, WBMP is not a compressible format, since the
processor of wireless devices in the old days did not have enough computation power
and decompression would result in a long delay. The file extension and the MIME type
of WBMP are ".wbmp" and "image/vnd.wap.wbmp" respectively.

To draw WBMP images, a WBMP image editor is needed. The Nokia Mobile Internet
Toolkit comes with a WBMP image editor that you can use. Besides drawing WBMP
images, you can use it to convert other image formats to WBMP. Just open a GIF or
JPG image file with the editor and it will be converted automatically. Free tools such as
ImageMagick can also do such kind of thing. However, remember that WBMP images
can only contain black and white colors, which means there will have detail loss during
the conversion of a colorful image to the WBMP format.

A colorful picture before conversion to The picture after conversion to WBMP.

WBMP.
Can a WML Browser Display Color Images?

A WML browser can display color images if the image format used is supported by the
wireless device. Currently, most mobile phone models on the market have color screens
and support color images. Commonly supported image formats are GIF 87a, GIF 89a
(animated GIF), JPG and PNG. Note that the image formats supported are device-
specific. Some wireless devices can only support a subset of the above image formats.

One simple way to find out whether a particular image format can be displayed on a
WML browser is to check the accept HTTP header, like what we have done in the
"Choosing MIME Types Dynamically" section of our XHTML MP tutorial. For
example, if "image/gif", "image/jpg" and "image/png" are found in the accept HTTP
header, it means the WML browser can display the GIF, JPG and PNG image formats.

Displaying an Image in WML: <img>

The <img> tag is used to add an image to a WML card. This is the same as in HTML.
WAP browsers will display the text assigned to the alt attribute of the <img> tag if it
cannot display the image for reasons such as file not found or image format not
supported. The URL of the image file is specified with the src attribute.

The height and width attributes of the <img> tag, as their names suggested, are used to
specify the height and width of an image's display area. WAP browsers may reserve
some space on the screen according to the values of these two attributes when the image
is still downloading, so that users can know the layout of the card. Also, WAP browsers
may scale up or down the size of an image if the height and width attribute values are
not the same as the image's real size.

Older WAP-enabled wireless devices can only display WBMP images. Newer ones
support image formats commonly used on the web such as GIF, JPG and PNG.

This example demonstrates how to display an image in WML using the <img> tag:

(imageEg1.wml)

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

<wml>
<card id="card1" title="Image in WML">
<p>
<img src="smile.gif" alt="Smile" height="62" width="60" /><br/>
Welcome to our WML tutorial.
</p>
</card>
</wml>
The result of the above WML markup code in WAP browsers is shown below:

Sony Ericsson T610

Nokia Mobile Browser 4.0
Sony Ericsson T68i

If the image file does not exist, the result will become:

Sony Ericsson T610 Sony Ericsson T68i Nokia Mobile Browser 4.0

Issues Concerning Large Images in WML

Many WAP browsers do not have the horizontal scrolling functionality. So, they will
crop off an image if its width is larger than that of the wireless device's screen, which
means your mobile Internet site may not look nice and professional to your users.
Besides, you have to remember wireless devices have limited memory. A WAP browser
may not be able to display the image if its size is too large.

The following WML example shows how a large image will look on some mobile
phone browsers:

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

<wml>
<card id="card1" title="Image in WML">
<p>
<img src="smileBig.gif" alt="Smile" /><br/>
Welcome to our WML tutorial.
</p>
</card>
</wml>
 Sony Ericsson T610

Sony Nokia Mobile Browser

Ericsson 4.0
T68i

As you can see in the above screenshots, the Sony Ericsson T610 and T68i mobile
phone browsers crop off the sides of a large image while the Nokia mobile browser
allows users to scroll to the right to see the section off the screen.

Another issue that you have to concern is that the image size will affect your mobile
Internet site's performance. Also, a larger image will result in a higher WAP connection
cost for those who visit your mobile Internet site. For example, cellular network
operators charge their GPRS service subscribers by the amount of data transmitted
through their cellular network. The larger the file size, the higher the service fee.

It is essential to optimize the images in your WML documents so as to keep the image
size small. Using the <img> tag's height and width attributes to scale down an image
does not help since the actual file size of the image is still the same. Here are some
techniques and suggestions for optimizing images:

1. Using an image manipulation program like GIMP and Photoshop to scale down
the images, instead of using the height and width attributes of the <img> tag.
2. If the images are GIF files, you should use a small palette. A smaller palette can
mean lower image quality, so you have to take a balance between quality and
file size.
 3. If the images are JPG files, you should save them in a suitable compression
ratio. A higher compression ratio will result in a smaller file size but a lower
quality. So, you have to take a balance between quality and file size.

WML Tables

To create tables and place some data in them, you need the <table>, <tr> and <td>
WML tags. A table (<table>) has a number of rows (<tr>) and each row has a number of
cells (<td>). Data is placed in table cells. The markup structure should be like this:

<table>
<tr>
<td>Data is placed here</td>
</tr>
</table>

The columns attribute of the <table> tag specifies the number of columns of a table. It is
a mandatory attribute. The columns attribute value must match the number of <td></td>
tag pairs in a row. For example, if the columns attribute value is 3, then each <tr></tr>
must contain three <td></td> tag pairs.

The following WML example demonstrates how to create tables and place data in table
cells:

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

<wml>
<card id="page1" title="Table in WML">
<p>
<table columns="3">
<tr>
<td>Cell A</td>
<td>Cell B</td>
<td>Cell C</td>
</tr>

<tr>
<td>Cell D</td>
<td>Cell E</td>
<td>Cell F</td>
</tr>
</table>
</p>
</card>
</wml>

The result of the above WML example in some mobile phone emulators is shown
below:
 Sony Ericsson T610 Sony Ericsson T68i Nokia Mobile Browser 4.0

WML allows you to set the horizontal text alignment of a column in a table. The align
attribute of the <table> tag is used for such purpose.

Now let's say your table has three columns. To specify the horizontal text alignment of
the columns, you need to assign three letters to the align attribute. Each letter represents
the horizontal text alignment of a column. The letter can be L, C, or R. Their meanings
are shown in the following table:

Letter Meaning

L Left alignment

C Center alignment

R Right alignment

If you want the following settings to be applied to your table:

First table column -- Left-aligned

Second table column -- Center-aligned

Third table column -- Right-aligned

Then you should set the value of the align attribute to LCR.

The following example can help you understand better what we are talking about:

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

<wml>
<card id="page1" title="Table in WML">
<p>
<table columns="3" align="LCR">
<tr>
<td>Col 1</td>
<td>Col 2</td>
<td>Col 3</td>
</tr>

<tr>
 <td>A</td>
<td>B</td>
<td>C</td>
</tr>

<tr>
<td>D</td>
<td>E</td>
<td>F</td>
</tr>
</table>
</p>
</card>
</wml>

The result of the above WML example in mobile phone emulators is shown below. As
you can see, the first table column is left-aligned, the second table column is center-
aligned and the third table column is right-aligned.

Sony Ericsson T610 Sony Ericsson T68i Nokia Mobile Browser 4.0

Note that WML does not allow the nesting of tables, which means the following
example markup is invalid in WML:

<table columns="1">
<tr>
<td>
<table columns="1">
<tr>
<td>Hello, welcome to our WML tutorial.</td>
</tr>
</table>
</td>
</tr>
</table>

WML Anchor Links

Anchor links enable the navigation between different WML cards. If you select an
anchor link, you will be brought to another WML card in the current deck or in another
deck.

The <anchor></anchor> tag pair is used to create an anchor link. It is used together with
tags such as <go/> and <prev/>, which tell WAP browsers what to do when a user
selects the anchor link. <go/> and <prev/> should be enclosed within the
<anchor></anchor> tags, like this:
<anchor>
<go href="..." ... />
</anchor>

<anchor>
<prev/>
</anchor>

Like HTML, WML uses a URL (Uniform Resource Locator) to refer to the location of a
WML file or a card in a deck. The href attribute of the <go/> tag is used to specify the
URL. Both absolute and relative URLs are accepted. URLs in WML have the same
form as those in HTML. Here is the general form of an absolute URL in WML:

http://host_name/path/file_name#offset?parameter1=value1&parameter2=value2...

The protocol used in WML URLs is HTTP. The reason is that WAP gateways request
WML files from ordinary web servers using the HTTP protocol, although wireless
devices communicate with WAP gateways using WAP protocols.

Going to a Card in Another Deck

The offset of a URL informs the WAP browser which card of a certain deck should be
shown. An offset begins with the # character. A card in a deck is identified by the id
attribute value of the <card> tag. The offset of a URL should be the ID of the target
card.

The following WML example illustrates how to go to a card in another deck. The WML
document below contains the cards of the first deck.

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

<wml>
<card id="tutorial_tc" title="WML Tutorial">
<p>
Hello, welcome to our WML tutorial.<br/><br/>
Table of Contents:<br/>

<anchor>
<go href="linksEg2.wml#tutorial_ch1"/>
Chapter 1: WML Introduction
</anchor><br/>

<anchor>
<go href="linksEg2.wml#tutorial_ch2"/>
Chapter 2: WML Deck and Card
</anchor><br/>

<anchor>
 <go href="linksEg2.wml#tutorial_ch3"/>
Chapter 3: WML Document Structure
</anchor><br/>

<anchor>
<go href="linksEg2.wml#tutorial_ch4"/>
Chapter 4: WML Generic Metadata
</anchor><br/>
</p>
</card>
</wml>

The following WML document contains the cards of the second deck:

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

<wml>
<card id="tutorial_ch1" title="WML Tutorial Ch1">
<p>
<em>Chapter 1: WML Introduction</em><br/><br/>
...
</p>
</card>

<card id="tutorial_ch2" title="WML Tutorial Ch2">

<p>
<em>Chapter 2: WML Deck and Card</em><br/><br/>
...
</p>
</card>

<card id="tutorial_ch3" title="WML Tutorial Ch3">

<p>
<em>Chapter 3: WML Document Structure</em><br/><br/>
...
</p>
</card>

<card id="tutorial_ch4" title="WML Tutorial Ch4">

<p>
<em>Chapter 4: WML Generic Metadata</em><br/><br/>
...
</p>
</card>
</wml>

If you view the first WML document in a WAP browser, you should see something like
this:
 Sony Ericsson T610
Nokia Mobile Browser
4.0

Sony Ericsson T68i

If you select an anchor link in the above card, the WAP browser will show a card of
another deck. For example, if you select the "Chapter 2: WML Deck and Card" anchor
link, the WAP browser will display the card of which the ID is "tutorial_ch2" in the
linksEg2.wml file, and you will see something like this:

Sony Ericsson T610 Sony Ericsson T68i Nokia Mobile Browser 4.0

If an anchor link's URL does not have the offset, WAP browsers will display the first
card of the deck. For example, let's say you create an anchor link using the WML
markup below:

<anchor>
<go href="linksEg2.wml"/>
Chapter 1: WML Introduction
</anchor>

If you select the above anchor link, the WAP browser will display the first card
contained in the linksEg2.wml file, that is the card with "tutorial_ch1" as its ID.