NET World

Richard Goodwin on WML.

Advanced HTML - Journey into WML

Only three issues in and already I'm dropping HTML for something newer and cooler; but as part of working with the Internet is making sure you keep up with new ideas and standards I hope you'll forgive this brief hiatus into the unknown, the language known as WML.

Intro into WML

WML - Wireless Markup Language - is a fairly new language, loosely based on HTML but designed, as you might have guessed, for the mobile computing industry. Mobile phones are just starting to come out that have wireless Internet capability - for instance, the Nokia 7110, the Ericsson R320 and the Siemens C-35i - but as they can't access regular HTML content, new content has to be provided. However, as there are few tools and even fewer designers that can design for WML this is not exactly easy.

Which is where this article comes in. RISC OS might not have many WML tools available, but then neither does any other platform; and if designers are in short supply, here's where you can make a fast buck or two. For all the apparent difficulties in getting content written in WML, in actual fact there are way fewer tags to remember compared with HTML, and you're basically designing mostly plain text, black and white, extremely simple sites. If you offer your services professionally, rarity value means you should be getting paid more than as an ordinary Web monkey; or if it's a personal site you get instant cool points by being able to show off your website to your mates down the pub by whipping out your mobile, even if it only took you a few seconds to knock up a single page. It's like the early days of the Web all over again, only cooler.

Configuring a server for WML

So, enough background, down to the nitty-gritty. Before you even start creating WML pages, you need to know that you can upload them to somewhere that will be able to handle them; your ISP's web server needs to be WML ready. WML and WAP (the Wireless Application Protocol, the basic framework on which wireless networking is dependent) in general has had enough publicity recently that this is already happening in a lot of cases. ArgoNet's main server, Golden, has been able to serve WML content for some time, and I think Demon and Freeserve have also started doing WML. If not, then many ISPs will be fairly eager to jump on the latest craze's bandwagon, so you should only have to ask. If they don't know how to do this, and they're using the Apache web server (most ISPs do) then the following lines added to httpd.conf should do the trick:

AddType text/vnd.wap.wml .wml
AddType image/vnd.wap.wbmp .wbmp .wbm

The first line tells it to accept files ending in the extension .wml (or /wml under RISC OS) as WML files; the second line that .wbmp and .wbm files are wireless bitmap images (more of which later). You might also ask them to find the line which contains something like the following:

DirectoryIndex index.html index.htm

and add index.wml at the end to be one of the default files that Apache looks for when someone just specifies a directory name in a URL. Apache will need to be restarted to get this to work, so don't hassle them too much if they don't get on to it right away.

If you can't get your ISP to provide a WAP service, there are a couple of options you can explore. The first is that if you have access to a CGI directory you could get a program to add the necessary information. Where you would usually have something in a PERL program like:

print "Content-type: text/html\n\n";

...before outputting HTML, you can simply switch to:

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

...and output WML this way. As a lot of ISPs will only allow you to introduce programs to their servers which have been checked over by their staff, it could get very tedious trying to maintain a site where someone has to check every update you make so I suggest making your program simply slurp in WML files and spit them back out with the correct MIME type. That way all you have to do to update your site is upload WML files and use the program as a sort of controller. I'll include an example script along with the resources for this article.

If all this sounds way too technical, never fear. Firstly, depending on the WAP gateway your phone is using (you'll often find an IP address of a server in your phone's setup which converts the plain text of a WML file into a sort of compressed version), your phone might be able to handle files that have been incorrectly labelled as HTML, so long as they don't contain any HTML; try it and see. Secondly, the IconBar (http://www.iconbar.com) has WML enabled webspace and have kindly offered to donate a little space to anyone wanting to experiment. Contact details are at the bottom of this article.

Writing WML

Another thing you should be aware of is that WML is, unlike most versions of HTML, perfectly formed - that is, for every opening tag you must have a closing tag, for instance must have a matching or your 'phone will generate an error. Some of you might be wondering at this point how things like images are handled, which don't have or need a closing tag. This is catered for by having a closing tag inside the opening tag - that is, the tag is finished off with a slash just before the final triangular bracket, as in . There are very few tags which allow this though, and I'll mention it when a tag is in this format, so don't go trying to close all tags in this manner just for the sake of it! You may have noticed that these tag examples are in lower case, not capitals; in HTML you may have become used to using either case, or even a mixture of the two; WML tags and attributes are all lower case.

Another thing to be aware of when designing for mobile phones may seem obvious, right up until you come to upload your first page - phone displays are small, so keep it simple. Quite apart from the fact that 'phones have a limited memory to store a page - your limit is effectively 1.4KB (yes, less than one and a half K!) because that's how much the most popular WAP phone, the Nokia 7110, can take before breaking - if your display is only twenty characters across and three or four lines down you don't want to be having to scroll through reams of text. Keep it down to a paragraph or two, and if you really need to impart a lot of information it's better to have it broken on to several pages with an easy to use index page.

I brushed upon the fact that the Nokia 7110 is the most popular phone of this type; this is based not only on the fact that it was the first in the UK marketplace and so was taken up in the first rush of enthusiasm for WAP, but also on a little research I did recently. I wrote a little program that took data from The IconBar website and made it suitable for mobile phones. This was announced on the main site about a month before I wrote this article, and I've just taken a look at the logs - out of around 350 hits, two thirds were by Nokia 7110 users. It's not a bad 'phone, it's fairly easy to get to your address book, the scrolling wheel makes navigation quite easy, and it has that cool sliding cover just like in The Matrix, but its browser is not exactly bursting with features. It doesn't support any text effects - like bold or italic - and doesn't support paragraph alignment. So, while I can give you the commands that should work on most 'phones, at the end of the day you're going to have to do some testing to make sure what you see on the screen is passable. I'll give some information and resources to make this easier at the end of the article.

Coding WML

On to the code then. Here's an example WML file for you to cut out and keep - apart from the text you need the following for every file you create, but as it's always the same I'll only show it the once and leave it out of future examples.

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

A "hello world" WML deck

Apart from the Hello world! part, everything you see is mandatory; the first line tells us this is an XML document - eXtensible Markup Language, a group of HTML-like languages of which WML is part - the second line is where to find the specifications for this particular variety of XML (wml_1.1, stored on the Wap Forum website). Notice how the DOCTYPE line is mostly in capitals to start with, but there's wml in lower case? All this has to be exactly as shown, case and all.

Then we have the <wml> and <card> tags, which is the start of some actual WML, and so are closed again at the bottom of the deck. You may have noticed that card and deck sound a lot like a pack of cards that you might play poker with; this is intentional, as you can have more than one card (area of WML) within a deck (WML file). You can give these cards titles and ids, then have links or other controls to jump from one id to another; it uses the same syntax as the <a name="thing">...<a href="#thing">, but using the id of different cards (or pages in the same file) instead of a name; but we'll stick to just the one. And finally you'll see there's paragraph tags - ... - around the text; there always has to be at least one set, and you can't have any content outside of them.

Paragraph attributes

align = left , center , right
mode = wrap , nowrap

As there are no other alignment tags - no <center>...</center> - you'll need to use paragraph alignment to centre text. To stop centering you'll need to close the paragraph and open a new one, as in the second example:

<p align="center">
Welcome!
</p>
<p align="left">
Hello and welcome to my website!
</p>

Simple paragraph alignment

As you can see I've removed all the header and footer stuff to keep things simple, but you'll need to add them back in or the example won't work. A couple of things to note about the example - I've explicitly set alignment back to "left", but this is implied if you open a new paragraph and don't specify any alignment; I just did it for completeness. Be warned that the Nokia 7110 doesn't support any alignment, but most other devices do; don't be afraid to try though because even if a particular phone can't use a tag or attribute, it won't generate any errors - it'll just ignore it so long as you stick to official tags, it'll only cause an error if you use something that isn't official. And don't worry about leaving lots of blank lines by having new paragraphs all over the place - WML paragraphs don't have spaces between them, in fact if you want spaces between lines you'll have to use the linefeed tag - - to force them.

The mode attribute has two possible values, wrap and nowrap. wrap is, as you might expect, just the standard way that text will go to the end of the line and then drop down to carry on at the beginning of the next line. nowrap however allows you to only take up one line; it'll show a line's worth of text, and when you move down so that the line has "focus" then it'll do a strange jump to the next line's worth of text, and then the next line's worth, and then the next in a kind of strange scroll text effect (although a scroll text usually scrolls a pixel or a character at a time, not whole words). This could be useful for a list of links, for example, so that you can show a concise list on screen, but as the user scrolls down it they get a longer description.

Effects

bold
italic
underlined
emphasised
strongly emphasised
<big></big> big
small

As you may have noticed all the effects are exactly the same as in HTML. However, support is not quite so widespread; the Nokia 7110 has no effects support, but most other devices support at least bold text - in fact they usually map some if not all other effects to be bold. You might also get away with underlined, and possibly even <big>, but I've yet to see a device that supports italic, even on the Palm V (the little handheld computer). As stated above though they won't spit out errors just because a particular 'phone doesn't have an italic font for instance, so because there's no other tags like headlines or blockquotes I suggest you try something like the following:

<p align="center">
<big><b>Welcome!</b></big>
</p>
<p align="left">
Hello and welcome to my website!
</p>

Using text effects for a more effective headline

The bold and big tags together with the centering will make the headline - "Welcome!" - stand out more; even if the big tag isn't supported at least there's the boldness to fall back on, and if for some reason this doesn't work it should be centered. The 7110 doesn't support any of this, so maybe it's time to try...

Images

<img... /> attributes:

src* = filename
alt* = alternative text in case image can't be shown
height = height in pixels of image
width = width in pixels of image
hspace = horizontal border width
vspace = vertical border width

Attributes marked with a * are mandatory.

As you can see, there's no real surprises with the image tag - apart from that closing slash at the end of the tag it's pretty much identical to HTML. You can even have an alignment tag to align the image to the top, middle or bottom of the text it's in, but as some 'phones put images centered on a new line I haven't listed it above. In fact it's probably best to have all images surrounded by a center-aligned paragraph just so that they appear the same on all 'phones. One thing to watch out for though is that, apart from the src attribute which you obviously need to tell the browser where to load the image from, you must have an alt attribute - even if it's empty, as in alt="" - otherwise some phones will throw up an error.

Alas there is one problem with images, and that's the format you have to use. You can only use the proprietary WBMP - wireless bitmap - format, which is only available in black and white. You're also going to have to keep the image down to about 96x40 pixels in size - the usable space on the "large" display on the Ericsson R320 is only 100x50, most other phones are smaller - which goes against the grain a little. Eventually I ended up writing a converter for this format, which I've included along with the other resources for this article. It'll take a Sprite and convert it into WBMP, and vice versa; the Sprite doesn't even have to be black and white, although it'd help if you used ChangeFSI to convert the image to black and white so you can see what you're getting before you commit it to WBMP format.

One other piece of advice I feel I should mention is that an image might seem fine when you're designing on your 1024x768 desktop in 32 thousand colours, but you'll probably find it looks stupidly large when you see it on the phone. Before converting to WBMP you might want to load the image into Paint and zoom it to 2:1 to get a better feel for how the image will look on the phone.

<p align="center">
<img src="4.wbmp" alt="Welcome!"/>
</p>
<p align="left">
Hello and welcome to my website!
</p>

An image for a headline

Linking

A hypertext document wouldn't be complete without hyperlinking, and you'll be glad to know that a WML link is exactly the same as a simple HTML link - for example:

<a href="destination.file">Some text</a>

It's even possible to have images in links, as in this example:

<a href="index2.wml"><img src="banner.wbmp" alt="click to enter"/></a>

However, you cannot have other tags inside links, for example the following will generate an error:

<a href="index2.wml"><big><b>This will fail!</b></big></a>

There might be some oddities in the way that 'phones will handle links, especially linked images. The Siemens C35 for instance puts square brackets around links - [linked] - and will also do this for linked images, which might be odd if you've created your image to be the same width as the screen (you'll end up with a bracket floating above and below your image). The Nokia 7110 won't show the image, just the linked alt text. Basically it's probably best if you don't link to images; just show the image and have a text link underneath, or use a timed jump. With regular linked text, some phones will put a linefeed before and/or after the link, so you can't expect to have a linked bit of text with plain text before and after it on the same line; in reality though lines are so short anyway that it's not that big a deal.

Strangely (given the lack of support for things like italic text), all 'phones that I've tested will allow you to jump to another deck or card using a timer. All you have to do is add an ontimer attribute pointing to the url you want to jump to in the <card> tag, and then set the timer:

<wml><card title="Test 5" ontimer="http://wap.iconbar.com/home.wml">
<timer value="50"/>
<p>
Please wait five seconds, or
<a href="http://wap.iconbar.com/home.wml">click here</a>
to go to the <b>IconBar</b> WAP service
</p>
</card></wml>

Automatically jumping to a new location

Notice that the timer is set for 50, but the text says that the jump will occur in five seconds; this is because the timer is set in tenths of a second, so setting the timer to 5 would only be half a second.

There's one other navigation link that you might want to add to your card, which goes just outside the closing right near the end - you can add a back button to either one of the phone's keys, and/or the navigation menu. It's good to do this as some 'phones have no method of going back through the history without this tag.

...
</p>
<do type="accept" label="Back">
<prev/>
</do>
</card></wml>

Code snippet for adding a Back button

For those of you with a serious technical bent, all the phones I've played with also support proper http 1.1 requests, so not only can you run WAP sites on virtual domains (where one machine can host the webpages for many domains, not just one), they'll also be able to handle redirections. For instance, visiting the IconBar WAP site with a regular browser will result in you getting redirected to the main IconBar site; you can only get to the WML pages if you're using a WML browser. This is because I've got a program called index.cgi which checks what device you're using and sends back a Location: header to switch the browser to the correct site for the browser's capabilities. I've used the same technique for my own website; at the time of writing I've only done one directory - http://houseofmabel.com/programs/html3/ - where you can visit with either type of browser and you'll automatically be sent to content suitable for your browser.

Characters

A brief mention about special characters in WML. There are only seven named character entities in WML, which should be pretty easy to remember:

WML Special characters

If it's not on this list, it doesn't have a named entity attached to it - for instance, if you want to print an acute "e" (as in café, élite etc.), in HTML you may have become used to using é but in WML it'll have to be é. Luckily these numbers directly relate to RISC�OS ASCII numbers, so if you know that you can press the ALT key and type, for example, 201 for a capital e acute, then the numeric character entity is É. It's unlikely that the WML browser that someone's going to be using to view your site will be able to do anything fancy, so always encode the characters in the table above using the commands given, and always encode "special" characters (those outside the normal plain text range) as numbers, don't just leave them as plain text and hope for the best.

There are two more things that you should know about characters in WML - dollars and ampersands are special. As mentioned above ampersands should be encoded, but what might catch you out is that this has to happen even in URLs - for instance,

<a href="/cgi-bin/program?action=run&value=now">

will fail. You should instead use

<a href="/cgi-bin/program?action=run&amp;value=now">.

Dollars are even more tricky; as in many other computer languages the dollar sign is used to denote a variable, so you can never have a dollar on its own. In a URL you might see something like the following:

<a href="/cgi-bin/program?action=$(action)">

Notice how the variable name is surrounded by brackets? This does not, however, mean that dollars that aren't next to brackets are fine - they have to be doubled up to print properly, for instance "$50,000" will cause an error, you must write "$$50,000". As my first experience with WML was taking HTML content and making it work on WML browsers, I could never figure out why some pages were fine and some failed for no apparent reason. Only later did I notice it was always the financial reports that failed, because they contained dollar signs and pound signs, and "$", "£" and "£" all break WML browsers!

Resources

Site development

http://www.wapsilon.com/ (aka http://wappy.to/) - displays WML in a regular browser by converting it to HTML.
http://www.ericsson.com/developerszone/- Ericsson developer's area
http://www.forum.nokia.com - Nokia developer's site
http://www.wapforum.org/ - official home of WAP and WML.
http://www.phone.com/ - one of the leading lights in the wireless internet field.
http://www.anywhereyougo.com/ - AnywhereYouGo.com, an excellent wireless developer's reference.
http://wap.colorline.no/wap-faq/ - The Independent Official WAP/WML FAQ
http://www.hicon.nl/cgi-bin/library/clipart/clipart.pl - clipart images in WBMP format.

RISC OS resources

http://wap.iconbar.com/ - The IconBar's WAP service; get the latest news and software updates on your WAP phone
http://houseofmabel.com/programs/html3/ - information on my HTML/WML development tool; these pages will work on both HTML and WML browsers.
http://www.iconbar.com/comms/wml/ - the main IconBar site's WML resources, which will have copies of all of the resources for this article online; any software updates will be posted here.

General

http://www.unmissabletv.com/txw/wap.wml - mobile TV guide covering all UK channels (including digital services)
http://www.blackstar.co.uk/ - this is the HTML site, where you can set up a WAP-based cinema guide.
http://www.railtrack.co.uk/ - another useful HTML site from which you can set up a WAP service; you can set up things like commonly-used locations, a calendar of where you are and when, and even how long it takes you to get to the nearest railway station, then on the phone you can have shortcuts like "Next train home" because it knows where you are and how far away from the station you are.

RISC OS Resources:

I've tried to put together enough tools to make WML development as painless as possible. The filetypes &F8E and &F8F have been officially registered as WML and WBMP files respectively.

Included on this month's CD

HTML3 - my HTML macro inserter, which can now be switched into WML mode.
WBMP - convert Sprites to WBMPs (and back again)
LinkSure - checks links. Updated to accept WML, SSI and PHP files, and check for WBMP images.
Filer icons (RISC OS 4 style)
Filetypes (RISC OS filestypes and DOS mappings)
LanMan98 extended mappings file
MimeMap file additions
StrongEd WML mode - StrongEd 4.63 and above should contain a WML mode, which has all WML 1.1 commands in its context sensitive colouring routine to make writing and debugging easier. It also has some useful functions on its icon bar and mode menu, such as making marked areas bold, italic, bigger and smaller; inserting standard headers and footers and so on.

StrongEd can be downloaded from http://stronged.iconbar.com/ (and was supplied with issue 4 of RISC World - Ed)

Copies of all of these resources, and any updates or additions, will be posted up at http://www.iconbar.com/comms/wml/

Richard Goodwin