wap_tut

A WAP Tutorial. Make Your Web Pages Available To Mobile Phones!
By Sean B. Palmer, chief wml site architect for http://www.wapdesign.org.uk/.

Introduction
As mobile phones become increasingly popular, you can be sure that one of the greatest innovations in the upcoming decade will be the introduction of WAP - Wireless Application Protocol. This allows you to write pages that will be visible by mobile phones and other small devices such as PDAs. In fact, there are already WAP enabled mobile phones out there, for example the Nokia 7110 and the Ericsson R380.

To write a WAP enabled page, you need to be able to write a wml document, and have a wml enabled server (such as http://redrival.com). You may wish to read our tutorial on serving WAP documents at http://www.wapdesign.org.uk/server.html. The tutorial you are reading now will tell you how to write your basic WAP pages.

Basics
A wml page is basically to a mobile phone what an HTML page is to an internet browser - it contains the code that lets the browser know what you want displayed on the screen

If you are already proficient, or even know just a little about HTML, then you will find making WAP pages a piece of cake! All you need to know is that wml pages are quite a bit stricter than HTML pages - they have to have perfect coding to enable them to work.

Getting Started
First, open up your favorite text editor (preferably one that you would usually write HTML pages in), for example, I use Notepad or Wordpad.

Secondly, you need to type in this bit of code as standard:

<?xml version="1.0"?>
<!DOCTYPE wml PUBLIC "-//WAPFORUM//DTD WML 1.1//EN"
"http://www.wapforum.org/DTD/wml_1.1.xml">
<wml>
Write your code here!!!
</wml>

This just tells the browser that it is a wml document that it is receiving. Where I have written " Write your code here!!!", is where the code for the document will go.

Decks & Cards
Because mobile phones are not as powerful as computers, and certainly do not have as large screens, the code has to take on a special reduced form - a 'deck'. A deck is comprised of a series of 'cards'. Because mobile phones have very little memory, you have to display all of your information as little chunks. These are cards. A group of these chunks (cards) is called a deck. A WAP enabled browser will deduce that the wml document is a deck, so all you have to do is tell it where the cards start and finish. Usually you would have between one and three cards.

To implement a card, you need to use the card tag:

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

   <card id="card1" title="My Wap Page">
     <p>
      Hello world - welcome to my WAP page!
     </p>
   </card>

</wml>

The id attribute gives the card a name, in this case "card1". This is so you can provide a link to other cards in your deck - much like the <a name="name1"> attribute in HTML. As the mobile phone browsers are only able to read one card at a time, you will have to provide links to enable your reader to find the other cards!

The title attribute just gives a title that is usually displayed in the top of the browser.
VERY IMPORTANT:-
N.B. Each card must have at least one p element in it (<p>, the paragraph element specifies a new paragraph.) All elements and attributes must be in lower case. All tags must have a closing tag or be self closed.

Here is an example of a multi-carded deck, and how you can link between the two:

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

    <card id="card1" title="My Wap Page">
      <p>
       Hello world - welcome to my first wap card!
      </p>
      <p>
       <a href="#card2">Go to the second card</a>
      </p>
    </card>

    <card id="card2" title="Second Card">
      <p>
       Welcome to my second wap card!
      </p>
      <p>
       <a href="#card1">Go back to the first card</a>
      </p>
    </card>

</wml>

The 'a' element is just the same as in HTML - a link to another document or card. e.g.

<a href="index.wml">Index</a>

All paths must be relative.

A small feature that is usually put on EVERY wml page is a back button. Most mobile phones don't have one for some odd reason, and so it is quite useful:

<?xml version="1.0"?>
     <!DOCTYPE wml PUBLIC "-//WAPFORUM//DTD WML 1.1//EN"
       "http://www.wapforum.org/DTD/wml_1.1.xml">
<wml>
    <template>
       <do type="accept" label="Back">
         <prev/>
       </do>
    </template>
    <card id="card1" title="My Wap Page">
      <p>
       Hello world - welcome to my first wap card!
      </p>
    </card>
</wml>

Putting the section in blue at the top of your wml document (only once) will put a back button at the of all of your cards! Putting it at the top of the card will place it in that card only.

Along with the <b> (bold) element and <!• --> (comment) element, this is all you really need to create a simple WAP site. One last thing for novices, don't forget to save your pages as *.wml !!!

Other Features
So, the impatient of you will be wanting to know ALL the features of wml - 'we want the good stuff'. The only problem is the small compatibility problems with using anything too advanced. You must remember that WAP technology is very new, and most browsers have yet to settle before an acceptable default becomes available. However, if you really are impatient, or just want to experiment (as I do), you'll be wanting to try some of these features:

Timers
<card id="card1" ontimer="#card2" title="My Wap Page">
<timer value="150"/>
<p>
Hello world - welcome to my first wap card!
</p>
</card>

Adding the sections in green to a card will cause the card to redirect to a different URI in a given time. In this case, after 1.5 (or 15) seconds, depending on the browser, it will direct to 'card2'.

Note that the timer attribute is self closed.

Images
Yes - you can add images to wap pages, but they are 1 bit (black and white) only, and can only be seen by some browsers. They also have to be of the type *.wbmp - you will need to convert existing images or create new ones.

Here are some links to help you do this:

http://www.gingco.de/wap/content/download.html The The pic2wbmp converter. Converts images into WBMP files.
http://www.teraflops.com/wbmp Teraflops Converts picture files to WBMP files online!
http://www.phnet.fi/public/jiikoo/ WBMP Draw A brilliant WBMP drawing program! Recommended.
http://www.creationflux.com/laurent/wbmp.html#2 Plugin A plugin for creating WBMP files with adobe photoshop.

When you have made a *.wbmp file, this is the code that you will need to put it on your wml page:

The alt attribute is very important as a lot of browsers will display this instead of your image.

Forms
Forms are quite complicated things (compared to the rest of the code) in HTML, and i'm afraid the same is true of wml pages.
It is basically a do/go function, and is so contained in a go tag:

<do type="accept" label="Next">
   <go method="post" href="http://mydomain.com/mycgiscript.cgi">
    <postfield name="searchvalue" value="$(search)"/>
    <postfield name="type" value="general"/>
   </go>
</do>
<p>
Search for:
<input type="text" name="search"/>
</p>

The dollar sign $ means a variable. In this case it returns the variable 'search' which is returned by the the input field below it.

Select Boxes
Much like the drop down boxes of HTML, these allow the user to select an operation (usually a link) from a drop down box:

<select ivalue="0">
<option onpick="http://www.wapdesign.org.uk/">WapDesign UK</option>
<option onpick="http://www.wapholesun.com/">WapHoleSun</option>
<option onpick="http://www.wapforum.org/">WAPForum</option>
</select>

ivalue means initial value. If you do not want anything to be initially selected (as in this case) set it to 0. If you want, say the second link selected, set it to 2.

More 'Advanced' Features
It's all very well writing a simple WAP page, but say you wanted to run WAP applications, or even have a simple e-mail form - what would you do then?

The main helpful feature in 'advanced' wml design is the variable.

Variables
A variable is a 'thing' that can have a string (alphanumeric) stored within it. It is called a variable because you can store anything in it, going as far as storing many different strings all in the space of one program.
A variable in wml takes on the form of $variable - where variable is the name of the variable. However, it is standard practise to put the variable name in brackets to avoid confusion when the browser reads it.
These are valid variables:

$(variable)
$(a)
$(averylongvariable)
$(ggeagibberishhe)
$(firstname)

Please note, variables can only be stored for use in one whole deck. The varialbes are lost when you move on to another deck (unless it is as part of a form function).

Use Of Variables
Of course the major use of variables is for forms. For example, from our previous page:

But there are other ways of using variables.....

Imagine you wanted to have a long list of URI's to one of your subdirectories on a page. The first thing that you should be thinking is that this requires a selection box. Of course, this would still mean writing out a very long list of URI's - especially if your subdirectory is very long (/firstdirectory/second/a/page1.wml). Well, if the only part of this URI that is going to vary (vary - variable, got it?) is going to be the 'page1' bit, then why not store this in a variable?

For example, look at the following:

<select name="page">
   <option value="index">Index</option>
   <option value="main">Our Main Page</option>
   <option value="home">Homepage</option>
</select>
<do type="accept" label="Go to page..">
<go href="/firstdirectory/second/a/$(page).wml"/>
</do>

This works because the value="" attribute simply stores the selected value into name="", which in this case is the variable $(page).

Now, what happens if for some reason you wish to set a variable? Well, lucky for you there is an element which lets you do that; the setvar element:

In this case the string 'mystring' will be stored in variable '$(variable)'.

Useful Things To Know...
The following are the ONLY non numeric entities supported by wml:

" (") quotation mark: "
& (&) ampersand: &
' (') apostrophe: '
< (<) less than: <
> (>) greater than: >
  ( ) non-breaking space: [ ]
 () soft hyphen:

CGI / PL Generated wml Pages
Yes, you can generate wml pages with CGI. The main thing you have to remember is to change the header of the document to text/vnd.wap.wml as long as you do that, the browser will recognise the fact that it is a wml file. Then you are free to print the contents of the wml page that you want. Here are a couple of ways you can do this:

First way:

#!/usr/bin/perl

print "Content-Type: text/vnd.wap.wml\n";
print "\n";

print "<?xml version=\"1.0\"?>\n"
print "<!DOCTYPE wml PUBLIC \"-//WAPFORUM//DTD WML 1.1//EN\" \n"
print "\"http://www.wapforum.org/DTD/wml_1.1.xml\">\n"
print "<wml>\n<card id=\"index\" title=\"index\">\n"
print "<p>Hello everyone</p>\n"
print "</card>\n</wml>"

Second way:

#!/usr/bin/perl

print "Content-Type: text/vnd.wap.wml\n";
print "\n";

qq{<?xml version="1.0"?>
<!DOCTYPE wml PUBLIC "-//WAPFORUM//DTD WML 1.1//EN"
"http://www.wapforum.org/DTD/wml1_1.1.xml">
<wml>
<card id="index" title="index">
<p>Hello everyone</p>
</card>
</wml>
};

Personally I prefer the second way, it's a bit quicker if you are writing long pages.