Learning WML – Building Gadgets

It is easy to fall into the trap of looking only for killer
applications to deploy via mobile devices. Integration with other services,
online databases, etc. are all worthy applications to code and offer via
wireless connections. However, you shouldn’t overlook the smaller,
single-function applications that users might find useful or even

necessary.

From Merriam-Webster’s
Online Collegiate. Dictionary (
http://www.webster.com/):

Gadget – an often small mechanical or electronic device with
a practical use but often thought of as a novelty

My current phone has several gadgets—a calculator, a
calendar, etc. Each of these makes the phone a bit more useful since I carry

it with me all the time. True, it doesn’t replace a PDA or other device loaded

with such functionality and utility, but I find having these features a great
addition to the phone.

However, not all phones have these gadgets built in. This article will

create one such gadget: a tip calculator. Along the way we will explore

different ways to accept user input as well as some variable-type artifacts of

WMLScript.

Note: Creating online gadgets presents a tradeoff for users; although they

gain the utility of the gadget, they must use airtime/online time to use it.

Keep this in mind when creating such applications and strive to keep their

uses simple and short.

Building a Tip Calculator

A few people I know carry a "tip card" with them to easily

compute the correct amount of their tip to leave at a restaurant. This card

gives whole dollar amounts and the representative percentage thereof, in 10%,

15%, and 20% values. A quick-and-dirty gadget can be implemented via WML and

WMLScript to accomplish the same thing.

Description of Project

This project is very straightforward-—accept a dollar amount and

display 10, 15, and 20 percent of the value entered. As an added benefit,
the application should display the total of the dollar amount and tip

amount.

Data Entry

To enter the amount, we can simply use a WML INPUT tag. For example, the

following code snippet would do:

<card>
  <p>
  <input
name="amount"/>
  </p>
</card>

To make the data input easier for the user, we could add a format parameter

to the INPUT tag to specify that the input should be numeric:

  <input name="amount" format="*N">

However, this format specification doesn’t allow for symbols, namely a

decimal point. The available format codes for the format parameters do not

include a format with both numbers and symbols, but without letters. So we can

choose from several options for getting the dollar amount from the user:

1. We can leave out the format, leaving the user to utilize
   the device’s options for changing to number/symbol input as required.
2. We can have the user round to the nearest dollar and
   enter only whole numbers.
3. We can preformat the data entry, specifying that one of
   the characters is a decimal point. For example:

   format="NNN.NN".

4. We can have the user enter the whole number and decimal
   amounts separately.

Each of these options has a downside:

1. If the amount isn’t easy to enter, the user won’t be apt
   to use the gadget. (Also consider the online time for using the gadget.) Most
   devices don’t exactly make it easy to switch between numbers and symbols.
2. Rounding to the nearest dollar won’t be exact and won’t
   allow us to display a total (amount + tip).
3. Specifying an exact mask requires the user to follow the
   mask exactly, entering more data than sometimes required. For example, in our
   example mask ("NNN.NN"), the user must preface any amount under $100
   with a zero (e.g., "090.00") to fit the mask.
4. Entering two separate amounts, one for the whole number
   portion and the other for the decimal, isn’t intuitive.

For this example, we will use the fourth option, entering
two numbers-one for the whole portion and one for the decimal:

  <p>
    <!-- Get whole and decimal amounts separately
      to aid user input -->
    Enter amount:<br/>
    <input name="checkamt" format="*N"/><br/>
    .<br/>
    <input name="checkdec" format="*N"/>
  </p>

With the code above, the user enters the whole amount,
presses ACCEPT, enters the decimal amount, and presses ACCEPT again. Although
not intuitive, the data input process is very streamlined.

The input screen. Note how the decimal is displayed (on the
left side, between the two text boxes) to help the user understand the

screen.

Image is courtesy Openwave Systems Inc. (Openwave, the
Openwave logo, Openwave SDK, Openwave SDK Universal Edition, Openwave SDK WAP
Edition are trademarks of Openwave Systems Inc. All rights
reserved.)

Combining the Input

Consider the following:

WML

<?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="input">
    <do type="accept">
      <go href="test.wmls#calc()"/>
    </do>
    <p>
    Enter amount of check in dollars and cents:<br/>
    <input name="num" format="*N"/><br/>
    .<br/>
    <input name="dec" format="*N"/>
    </p>
  </card>
 
  <card id="result">
    <p>
    Result is: $(result)
    </p>
  </card>
  
</wml>

WMLScript

extern function calc() {
  
var num = WMLBrowser.getVar("num");
var dec = WMLBrowser.getVar("dec");
var result;
  
dec = dec / Float.pow(10,String.length(dec));
result = num + dec;
  
WMLBrowser.setVar("result",result);
WMLBrowser.go("junk.wml#result");
}

We can reduce the amount of computation necessary to derive
the total by using the dynamic nature of variable typing in WMLScript.
Essentially, if we force WMLScript to treat the variables as strings, creating
the total is as easy as this:

result = num + "." + dec;

Note: If no decimal amount was entered (variable
"dec" is empty), the result variable will have a trailing period

(.).

Displaying the Results

Now that we have the amount, a handful of additional
computations will give us the results to display for the user. We need to
figure 10%, 15%, and 20% of the amount and total each percentage with the
amount:

// Add whole and decimal to get check amount
check = check + "." + dec;
  
// Calculate tip at 10%, 15%, 20% and totals for each amt
tip10 = check * .1;
tip15 = check * .15;
tip20 = check * .20;
amt10 = Lang.parseFloat(check) + Lang.parseFloat(tip10);
amt15 = Lang.parseFloat(check) + Lang.parseFloat(tip15);
amt20 = Lang.parseFloat(check) + Lang.parseFloat(tip20);

Note: I’ve replaced the generic variable name "num"
with the variable name "check" above.

Notice the use of the Lang.parseFloat function. This helps
ensure that WMLScript treats the amounts as floating-point numbers instead of
strings. Otherwise, given these two numbers:

  check = 17.35
  tip10 = 1.735

we end up with this:

  amt10 = 17.351.735

which is the concatenation of the variables as strings,
instead of their addition as floating points.

Finally, the WMLScript needs to push the variable values to
WML and call a display card:

// Push values to WML
WMLBrowser.setVar("check",check);
WMLBrowser.setVar("tip10",tip10);
WMLBrowser.setVar("amt10",amt10);
WMLBrowser.setVar("tip15",tip15);
WMLBrowser.setVar("amt15",amt15);
WMLBrowser.setVar("tip20",tip20);
WMLBrowser.setVar("amt20",amt20);
  
// Call total card
WMLBrowser.go("tipchart.wml#tipamount");
}

The Completed Code

tipchart.wml

<?xml version="1.0"?>
<!DOCTYPE wml PUBLIC "-//WAPFORUM//DTD WML 1.1//EN"
"http://www.wapforum.org/DTD/wml_1.1.xml">
  
<wml>
  
  <!-- Get amount of check and pass to calculator -->
  <card id="checkamount" title="TipCalculator">
  <onevent type="onenterforward">
    <!-- Clear previous values -->
    <refresh>
      <setvar name="checkamt" value=""/>
      <setvar name="checkdec" value=""/>
    </refresh>
  </onevent>
  
  <!-- Call calculator when amounts have been entered -->
  <do type="accept">
    <go ref="tipchart.wmls#calctip()"/>
  </do>
  <p>
    <!-- Get whole and decimal amounts separately
      to aid user input -->

    Enter amount of check in dollars and cents:<br/>
    <input name="checkamt" format="*N"/><br/>
    .<br/>
    <input name="checkdec" format="*N"/>
  </p>
  </card>
  
  <!-- Display tip amounts and totals -->
  <card id="tipamount">
  <do type="accept">
    <go href="#checkamount"/>
  </do>
  <p> 
    Check Amount: $(check)<br/>
    10% -$(tip10)<br/>
&nbsp;&nbsp;= $(amt10)<br/>
    15% -$(tip15)<br/>
&nbsp;&nbsp;= $(amt15)<br/>
    20% -$(tip20)<br/>
&nbsp;&nbsp;= $(amt20)<br/>
  </p>
  </card>
  
</wml>

tipchart.wmls

// Tip Calculator script
  
// calctip - calculate tip amount from values entered
extern function calctip() {
  
// Get check amount (and decimal portion) from WML
var check = WMLBrowser.getVar("checkamt");
var dec = WMLBrowser.getVar("checkdec");
  
// Init tip and total vars
var tip10, tip15, tip20, amt10, amt15, amt20 = 0;
  
// Add whole and decimal to get check amount
check = check + "." + dec;
  
// Calculate tip at 10%, 15%, 20% and totals for each amt
tip10 = check * .1;
tip15 = check * .15;
tip20 = check * .20;
amt10 = Lang.parseFloat(check) + Lang.parseFloat(tip10);
amt15 = Lang.parseFloat(check) + Lang.parseFloat(tip15);
amt20 = Lang.parseFloat(check) + Lang.parseFloat(tip20);
  
// Push values to WML
WMLBrowser.setVar("check",check);
WMLBrowser.setVar("tip10",tip10);
WMLBrowser.setVar("amt10",amt10);
WMLBrowser.setVar("tip15",tip15);
WMLBrowser.setVar("amt15",amt15);
WMLBrowser.setVar("tip20",tip20);
WMLBrowser.setVar("amt20",amt20);
  
// Call total card
WMLBrowser.go("tipchart.wml#tipamount");
}

The user enters the amount of the check. . .

And receives three escalating tip amounts and related
totals.

Images are courtesy Openwave Systems Inc. (Openwave, the

Openwave logo, Openwave SDK, Openwave SDK Universal Edition, Openwave SDK WAP

Edition are trademarks of Openwave Systems Inc. All rights

reserved.)

Note the addition of an initialization <REFRESH> event
on the "checkamount" card. This ensures that the variables are
cleared whenever this card is called, whether the first time through the code
or via the "results" card.

Room for Improvement

Of course, there’s always room for improvement. In this
case, rounding the tip amounts to the nearest cent would be handy. This can’t
be accomplished directly with the Float.round WMLScript function, which only
rounds to the nearest integer. The round function can be used if the decimal

is moved, round is used, and then the decimal is moved back. (multiply the

amount by 100, add .5, round to nearest integer, divide by 100)

What Do You Want from WML?

I’m interested in hearing what you need/want to do with WML.
I’ll use some of the more challenging or common ideas in upcoming articles.
Send your ideas to the address below.

About the Author

Steve Schafer is chief operating officer of Progeny Linux Systems, a

Linux-based consulting company in Indianapolis, Indiana. He has written

several technical books and articles and can be reached at sschafer@synergy-tech.com.

# # #