Intro to HDML

by Paul Adams Updated 09 May 2001

Paul Adams is Webmonkey's resident acronympho, covering the likes of PHP, DNS,
and SOAP with startling aplomb.

Page 1

No, that's not a typo. HDML is the so-called handheld device

markup language that allows you to make your website
portable: People can view it on their mobile phones, pagers,
and other tiny devices. Needless to say, the average person is
not going to want to research her dissertation on Keatsean
animal imagery on a 4-by-12-character screen as she walks to
her car, so the language and browser specifications focus on
small-scale transactions: stocks, sports scores — you know the
type. And now that compliant wireless phones are becoming
more widespread, you can use HDML to propagate your tidbits
of information to the world.

What Is What?

Back in 1997, a company called Unwired Planet invented HDML

and the browser that reads it, called the UP.Browser. At the
time, it was the great hope of the so-called "third-generation,"
Web-enabled browser. But a lack of support on both ends left
HDML temporarily high and dry. Recently, though, the WAP
Forum, founded by Unwired Planet (since evolved into
Phone.com and most recently Openwave) and such industry
movers as Nokia and Motorola, unveiled WAP, the wireless
application protocol, which — in conjunction with this year's
smaller, cheaper phones with greater screen real estate —
allows much more robust and widespread phone surfing.

WML (wireless markup language, not to be confused with

Website Meta Language), a fully XML-compliant descendant of
HDML, is part of the WAP standard. Because WML was
developed after HDML, it's a bit more graceful and is supported
by all new wireless phones. (Here is our intro course on WML.)
Still, HDML is the only language that older phones understand.
Here's a brief introduction to it; but beware that it's on its way
to obsolescence. If you don't have a device on which you can
view HDML pages, you can download a simulator for your PC,
so you can follow along at home.

A list of phones that ship with the UP.Browser, including

availability and version information, can be found here. Only
some of these can handle WML, but they can all handle HDML.

Intro to HDML
Page 2 — Getting Ready for HDML
To get started, you need to have a Web server that's set up to
serve these kinds of files. If you or your host use Apache or
another NCSA-based server, you simply need to create a file
called .htaccess (don't forget the initial dot) in your top-level
HTML directory containing the lines shown below. The second
statement column (after "addtype") is the mime type, the last
part is the file extension:

addtype text/x-hdml hdml

addtype text/vnd.wap.wml wml

addtype image/bmp bmp

With other servers, you just need to add the equivalent lines to
your mime configuration in the appropriate way.
Once you're ready to roll, the next step is to build an HDML
deck.
Intro to HDML
Page 3 — Writing HDML

As with HTML, every deck starts with <HDML> and ends with
</HDML>. It is mandatory, though, to specify the language
version number in the opening statement, so it should actually
look like this: <HDML VERSION=3.0>.

The hardest-working statement in HDML is the <DISPLAY> tag,

which contains a single display card. Cards can contain just
text or text and actions. Actions are implemented with
<ACTION> statements, each of which assigns an action to a
key on the phone. Each key (they're called "softkeys" because
they're reprogrammable, even if the plastic's hard) has a
default action until it is assigned an action for a particular card
with an <ACTION> statement. For instance, the OK or Accept
key's default action is to go back one card (for more details,
check out the HDML 3.0 language reference). Sans further ado,
here's a brief example deck.

<HDML VERSION=3.0>
<DISPLAY NAME=jan>
<ACTION TYPE=ACCEPT LABEL=Feb TASK=GO DEST=#feb>
January rainfall
<BR>1998: 19
<BR>1997: 15
</DISPLAY>
<DISPLAY NAME=feb>
<ACTION TYPE=ACCEPT LABEL=Mar TASK=GO DEST=#mar>
February rainfall
<BR>1998: 14
<BR>1997: 10
</DISPLAY>
<DISPLAY NAME=mar>
March rainfall
<BR>1998: 18
<BR>1997: 19
</DISPLAY>
</HDML>
The output of this code looks like this:

So the <DISPLAY> tag's NAME attribute gives each card a

relative URL, which is then used by the <ACTION> tag to find
the next card. The <ACTION> tags seen here make the Accept
key go to a specific card when pressed. The TYPE attribute
specifies which key to use; LABEL sets the name of the key,
typically displayed at the bottom of the screen as a prompt;
TASK tells the key what to do (GO is the most common task
assignment by far); and DEST specifies where to go (this can
be an absolute or a relative URL, just like you're used to). The
syntax for referring to cards is just like that for named anchors
in HTML. If a deck is loaded with no card specified, the browser
automatically displays the first card in the deck.
Linking in HDML
Of course, HDML is not without that building block of modern
society, the hyperlink. It is, in fact, supplied in the form of the
oh-so-familiar warm-'n'-fuzzy <A> tag (no <HREF>, alas). The
syntax is as follows:
<HDML VERSION=3.0>
<DISPLAY>
Contents:<BR>
Intro <A TASK=GO DEST=intro.hdml LABEL=Intro
ACCESSKEY=1>About me</A><BR>
Diary <A TASK=GO DEST=diary.hdml LABEL=Diary
ACCESSKEY=2>My diary</A><BR>
Elsewhere <A TASK=GO DEST=links.hdml LABEL=Leave
ACCESSKEY=3>My links</A>
</DISPLAY>
</HDML>
And here's what that looks like:

Links are chosen by scrolling down the card — the LABEL

attribute specifies what is displayed at the bottom of the screen
when each link is highlighted — and pressing the Accept key,
which in turn loads a new deck. Alternately, you can press the
numbered key corresponding to the link, as specified in the
ACCESSKEY attribute.
And, as with HTML, you can also use HDML to get interactive
with your users.
Intro to HDML
Page 4 — Processing User Input

There are two ways to receive user input in HDML: Entry cards
allow users to (laboriously) key in information, and choice
cards allow them to choose from a list. Here is a sample entry
card:

<HDML VERSION=3.0>
<ENTRY KEY=name FORMAT=A*a>
<ACTION TYPE=ACCEPT TASK=GO DEST=#ssn>
What's your name?
</ENTRY>
<ENTRY NAME=ssn KEY=socsec FORMAT="NNN\-NN\-NNNN">
<ACTION TYPE=ACCEPT TASK=GO DEST=#show>
What's your Social Security number?
</ENTRY>
<DISPLAY NAME=show>
Hello, $name! I bet $socsec isn't your REAL Social Security
number.
</DISPLAY>
</HDML>

It produces something like this:

Each entry is stored in a variable defined by the KEY attribute,

which can be called by prefixing that variable's name with a
dollar sign as shown. The FORMAT option allows you to limit
the types of entries possible in a particular field. The Social
Security field in this example will accept only numerical input
("N" means one digit), and a hyphen is automatically inserted
after the first three digits and again after two more, Social
Security style. A slash before a character automatically places
that character in the field regardless of the user's input.
The name field seen here allows one uppercase letter followed
by any number of lowercase letters. That's what "A*a" means
— an asterisk preceding a character type allows any number of
that particular character. Here are some other options:
Specifier Meaning
A An uppercase letter
a A lowercase letter
N A number
X A number, symbol, or uppercase letter
x A number, symbol, or lowercase letter
M Any character
* Any number of the type of character following the *
For example, exactly three of the type of character
3
following the specifier

Now let's give our users a multiple-choice option. Here is a

sample choice card:
<HDML VERSION=3.0>
<CHOICE KEY=flav>
<ACTION TYPE=ACCEPT TASK=GO DEST=#show>
What is your favorite kind of ice cream?
<CE VALUE="chocolate">Chocolate
<CE VALUE="strawberry">Strawberry
<CE VALUE="peach">Peach
</CHOICE>
<DISPLAY NAME=show>
Really? You like $flav? Whatever.
</DISPLAY>
</HDML>
It will look like this:

Here's what's happening. As before, the variable specified in

the KEY attribute receives the value string assigned (in the CE
statement) to the item the user chooses. After the choice is
made, the user is taken to the "show" card, which displays the
value of that variable.
And that's not all! HDML can even deal with images ... well,
certain images.
Intro to HDML
Page 5 — Tiny Images

HDML can be used to display small one-bit bitmap images (BMP

files only), which ain't much, but it's something. Since many
phones are not image-enabled, however, it is a very, very good
idea to provide descriptive ALT text. Different phones handle
image sizing differently: Some shrink an image that's too large,
others crop it, and still others refuse to render it at all. So keep
those pixel counts down: 120 by 120 is pretty safe; more
might be pushing it. The syntax for images is pretty
straightforward if you know HTML:

<HDML VERSION=3.0>
<DISPLAY>
<IMG SRC="images/kitty1" ALT="My kitty!">
</DISPLAY>
</HDML>
Your users will get this:

And that's about it. While there is a bit more to HDML (not to
mention WML and WAP), that's enough to get you started.
When you're ready to start building huge e-commerce sites in
HDML, you may want to check out the HDML Developer's Guide
and the HDML 3.0 Language Reference to learn about things
like advanced variable handling, using images in links,
bookmarks, hardware sniffing, nested activities, caching,
security, push, dynamic pages, etc.
The wireless industry continues to embrace WAP, but it's hard
to predict how soon and how widely the advanced features will
catch on. Keep an eye on that phone availability page to see
which devices are shipping with UP.Browser 4.0, which older
ones support HDML only or 3.1, which devices can shake hands
with WML and HDML, and which ones are compatible with later
releases of the version 4.0 browser. In fact, the 4.0 version
adds support for WMLScript, the scripting language of the
wireless world's miniature Web.
Now get coding! The mobile surfers are dying for juicy content.