21.4 Using WMLScript with WML pages

21.4 Using WMLScript with WML pages

21.4.1 What is WMLScript and how does it work?

Basically, WMLScript is a client-side script language based on ECMAScript and dedicated for low-bandwidth devices such as a mobile phone. Many people may refer to WMLScript as the ECMAScript dialect for wireless applications. Unlike ECMAScript, WMLScript functions or statements are not defined inside a WML page. Instead, all WMLScript language or statements are stored in another file with file extension .wmls (Wireless Markup Language Script).

When your WML page calls a WMLScript function, you call the reference of the function by URL. When a function of WMLScript is called, the script is compiled into byte code by the WAP gateway and then sent to the micro-browser for interpretation.

Apart from the difference above, WMLScript shares the same structure and style of ECMAScript including variables, function declarations, and many standard library functions. In fact, the programming techniques of the two are basically the same and interchangeable.

First, consider the simple WML page below:

Example: ex21-16.wml - My First WMLScript

 1: <?xml version="1.0"?>
 2: <!DOCTYPE wml PUBLIC "-//WAPFORUM//DTD WML 1.3//EN"
 3: "http://www.wapforum.org/DTD/wml_1.3.xml">
 4: <wml>
 5: <card id="Line" title="First WMLScript">
 6:  <onevent type="onenterforward">
 7:      <go href="ex21-16.wmls#hello()" />
 8:  </onevent>
 9:      <p> $message </p>
10:  </card>
11: </wml>

This is a WML page (not WMLScript) containing only one card. Inside this card, an event with type onenterforward (lines 68) is defined so that when the card is loaded, the following action is activated:

<go href="ex21-16.wmls#hello()" />

This go represents the calling format for WMLScript and its function. In this case, the go action will jump to the WMLScript file ex21-16.wmls and execute the function hello(). As you might expect, the hello() function is used to construct a string and store it in the variable $message. When this WML page is refreshed, the statement in line 9 displays the message on the screen.

The details of the WMLScript and hello() function are listed below:

Example: ex21-16.wmls - WMLScript File For ex21-16.wml

1: extern function hello()
2: {
3:   WMLBrowser.setVar( "message",
4:      "Hello World! \n I know WMLScript now." );
5:   WMLBrowser.refresh();
6: }

This WMLScript contains one function called hello(). The function is declared as extern (external) so that it can be called by other cards and applications. The first statement inside the hello() function is

WMLBrowser.setVar( "message",
     "Hello World! \n I know WMLScript now." );

In fact, this is a function called setVar() from the WMLBrowser object. The purpose of this function is to set a value to a variable. In this case, the entire string in line 4 is stored in the variable message. Therefore, the statement in line 9 of ex21-16.wml can be used to print out the "Hello World!…" message. The new line symbol "\n" in line 4 is to generate a line break so that multiple lines can be generated in one string.

Another statement in the hello() function is

WMLBrowser.refresh();

This refresh() function from the WMLBrowser object is to refresh the WML page ex21-16.wml so that the message is displayed. A screen shot is shown in Fig. 21.41.

This example demonstrates two important points. First, apart from the user-defined function hello(), standard WMLScript functions are methods of objects. In this case, the two functions

WMLBrowser.setVar()
WMLBrowser.refresh()

are methods of the standard WMLBrowser object.The second important point is that the main purpose of WMLScript is to perform computations and process the data for the main page. Soon after the computations, control is usually transferred back to the main page. Now let's consider some more WMLScript and functions.

21.4.2 The standard WMLScript libraries and functions

Compared to ECMAScript, WMLScript is smaller. The main components of the entire WMLScript are implemented as six standard objects (or libraries):

• WMLBrowser Contains functions that can be used to access browser variables.

• Dialogs Provides functions to display alert, confirm, and prompt dialog windows.

• Lang Contains a set of functions that are closely related to the WMLScript core such as parsing a string to integer etc.

• Float Contains a set of mathematical functions, mostly about rounding of numbers.

• String Contains functions quite similar to the ones found in the JavaScript string object.

• URL Contains a set of functions for handling relative and absolute URLs.

For obvious reasons, only the first three objects are discussed here. The first three libraries and functions should provide a good foundation for us to start WMLScript programming.

The first important library in WMLScript is the WMLBrowser library (or object). It provides an essential set of functions to navigate among cards and set global variables for them. A summary of the frequently used functions in the WMLBrowser object is listed in Table 21.5.

Table 21.5. Frequently used functions in the WMLBrowser object

Function name	Description and example
getCurrentCard()	Returns the (relative) URL of the current card, e.g., var k = WMLBrowser.getCurrentCard();
getVar()	Returns the value of a variable, e.g., var k = WMLBrowser.getVar("DVDPrice");
go()	Goes to a new card, specified by the new URL, e.g., var k = WMLBrowser.go(card4);
newContext()	Clears all variables, e.g., var k = WMLBrowser.newContext();
prev()	The browser goes back to the previous card, e.g., var k = WMLBrowser.prev();
refresh()	Refreshes the current card, e.g., var k = WMLBrowser.refresh();
setvar()	Sets the value of a variable, e.g., var k = WMLBrowser.setVar("DVDPrice", 104);

As your Mobile Internet experience grows, you will find that the functions in this object are the most often used. Consider an example to use getCurrentCard(), setVar(), and go() as follows:

Example: ex21-17.wml - Using The Functions In WMLBrowser Object

 1: <?xml version="1.0"?>
 2: <!DOCTYPE wml PUBLIC "-//WAPFORUM//DTD WML 1.3//EN"
 3: "http://www.wapforum.org/DTD/wml_1.3.xml">
 4: <wml>
 5:  <card id="card1" title="WMLScript">
 6:  <p>
 7:    Run WMLScript to get the name of this card. <br />
 8:    <anchor><go href="ex21-17.wmls#getCard()" />Run</anchor>
 9:  </p>
10:
11:  </card>
12:  <card id="card2" title="WMLScript">
13:  <p>
14:    The Current Card is ex21-17.wml#card2 and the previous card is
15:    $curCard
16:  </p>
17:  </card>
18: </wml>

This example will return the identity (or name) of a card. When the action text "Run" defined in line 8 is clicked, the user-defined function getCard() in ex21-17.wmls is called. This function will use the standard function WMLBrowser.getCard() to find the identity of the current card and return the identity as variable %curCard in another card with id="card2".

The WMLScript source file ex21-17.wmls is listed below:

Example: ex21-17.wmls - WMLScript File For ex2117.wml

1: extern function getCard()
2: {
3:   var temp0 = WMLBrowser.getCurrentCard();
4:   var temp1 = WMLBrowser.setVar("curCard",temp0);
5:   var temp2 = WMLBrowser.go("#card2");
6: }
7:

This file contains three statements only. The first statement in line 3 is to get the identity of the card and store it in variable temp0. The second statement (line 4) is to set up a variable curCard to carry the identity of the card. The final statement is to go back to card2 so that the value in variable curCard is displayed. Some screen shots are shown in Figs 21.42 and 21.43.

The next library is the Dialogs object. This object provides a valuable set of functions to generate dialog boxes on the mobile screen. They are valuable tools to get user input. Basically, there are three dialog boxes defined in this object and listed in Table 21.6.

Table 21.6. Frequently used functions in the Dialogs objects

Function name	Description and examples
alert()	Displays a message and waits for a confirmation, e.g., var k = Dialogs.alert("The input must be numeric!");
confirm()	Displays a message, waits for an answer, and returns a Boolean value depending on the input, e.g., var k = Dialogs.confirm("Exit?","Yes","No");
prompt()	Displays a question, waits for an input, and then returns the user's answer, e.g., var k = Dialogs.prompt("Enter a number:","0"); k = "7" (if you entered the value 7) k = "0" (if you did not enter a value)

Although these three dialog functions are simple, they provide an important tool to get user input. For example, if you want a simple solution to get a number from the user and perform some calculation, you may have no choice but to use the prompt() function. The examples provided in the table show you how to use them.

The third library we would like to introduce is the Lang object. This object provides some simple, yet important functions dedicated to the WMLScript language and is therefore called the Lang (language) object.

For example, when you ask your mobile user to input a value, the value is usually represented as a string. Before any calculation can be performed, this string may need to be converted into a number (an integer or a floating point number). Also, if you want to terminate the WMLScript, you may want to use the abort() or exit() function inside this Lang object.

Some frequently used functions in the Lang object are listed in Table 21.7.

Table 21.7. Frequently used functions in the Lang objects

Function name	Description and examples
abort()	Aborts WMLScript and returns a message to the caller of the script, e.g., Lang.abort("Error.. Program Abort.. ");
exit()	Exits WMLScript and returns a message to the caller of the script, e.g., Lang.exit("Done !");
isFloat()	Returns true if a specified value can be converted into a floating point number and false if not, e.g., var a = Lang.isFloat("6.5"); -- true var b = Lang.isFloat(" -9.45e2"); -- true var c = Lang.isFloat("@432"); -- false var c = Lang.isFloat("hello"); -- false
isInt()	Returns true if a specified value can be converted into an integer and false if not, e.g., var a = Lang.isInt("-576"); -- true var b = Lang.isInt("6.5"); -- false
parseFloat()	Returns a floating-point value defined by a string, e.g., var a = Lang.parseFloat("99.99"); -- (a=99.99) var b = Lang.parseFloat("-.3 C"); -- (b=-0.3) var c = Lang.parseFloat("100 pt"); -- (c=100)
parseInt()	Returns an integer defined by a string, e.g., var a = Lang.parseInt("2345"); -- (a=2345) var b = Lang.parseInt("200 dollar"); -- (b=200)

These functions are simple to use and the examples in the table provide a good starting point. From the selection of functions, we can see that the WAP Forum has done a good job in providing a fundamental programming framework for mobile devices.

Now let's consider some applications of WMLScript in m-business.

21.4.3 My first WMLScript on m-business

Many people regard business on mobile devices (m-business), including shopping and trading, as the next generation for business in parallel with or even replacing e-commerce in the Web sense. Whether m-business will merge with e-commerce or not, m-business is certainly an attractive subject. We can see that more and more funds are being pumped into research and development by the big mobile companies driven by customer demand.

Compared to e-commerce, m-business is relatively simple, but more precise, focussed, and decision driven. According to some successful m-business companies and agents, m-business is huge by any standards. Imagine how many people around the world would say yes to the following message on their mobile phones:

Send 12 beautiful roses
and a box of chocolates
to your mother on
mother's day (next week)
for xx dollars?

If you can make an agreement with the mobile company to charge the customer's account for this service, you will be in business even better if all you need from your customer is the telephone number of his or her mother instead of the address.

Whether we are in business or not, to write a WML page to display the above message on a mobile phone should not be a problem. To write WMLScript to get the telephone input is also not difficult. Consider the following example:

Example: ex21-18.wml - Using WMLScript On M-Business

 1: <?xml version="1.0"?>
 2: <!DOCTYPE wml PUBLIC "-//WAPFORUM//DTD WML 1.3//EN"
 3: "http://www.wapforum.org/DTD/wml_1.3.xml">
 4: <wml>
 5:  <card id="index" title="Mother's Day Offer" newcontext = "true">
 6:   <p>
 7:     12 Roses + A box of chocolates to your mum for xx dollars?
 8:     <anchor><go href="ex21-18.wmls#phone()" />YES</anchor>
 9:   </p>
10:  </card>
11:  <card id="card2" title="Thankyou">
12:   <p>12 Roses + A box of chocolates will arrive
13:     address (Tel: $phone) on mother's day.<br />
14:     XX will be charged to your account.
15:   </p>
16:   </card>
17: </wml>

This m-business page displays an attractive text on the mobile screen. While many people are still searching the Internet for a perfect gift for Mother's Day, this text will arrive on your phone to provide convenience. A brief, focussed message will trigger the action. When the user presses the "YES" text, the WMLScript function phone() will be activated to get the telephone number so that delivery can be made. The telephone number is sent back to card2 for confirmation.

The details of the WMLScript are listed below:

Example: ex21-18.wmls - WMLScript File For ex2118.wml

1: extern function phone()
2: {
3:   var temp0=Dialogs.prompt("Your Mother's Phone No.:","");
4:   WMLBrowser.setVar("phone",temp0);
5:   WMLBrowser.go( "#card2" );
6: }

In this WMLScript, three standard functions are used:

• Dialogs.prompt()

• WMLBrowser.setVar()

• WMLBrowser.go()

The process again is simple. First, get the user input by a dialog prompt; perform some calculations on the data if you want, then create a variable to be sent back to the main page.

Some screen shots of this example are shown in Figs 21.4421.46.

For a more general framework for m-business, we will develop an interface for m-business using WMLScript.

21.4.4 Using WMLScript for m-business

For a more general page or interface for m-business, the page should have the capability to perform some calculations. For example, suppose you are offering a special purchase to your mobile users; you would certainly like each of your customers to buy more than one. In this case, to calculate the total charges is essential for the business. Consider the example below:

Example: ex21-19.wml - M-Business Page With Calculation

 1: <?xml version="1.0"?>
 2: <!DOCTYPE wml PUBLIC "-//WAPFORUM//DTD WML 1.3//EN"
 3: "http://www.wapforum.org/DTD/wml_1.3.xml">
 4: <wml>
 5: <card id="index" title="Special Offer" newcontext = "true">
 6:   <p>
 7:    MA288: A color screen smart phone
 8:    (Only <b>120</b>)<br /><br />
 9:    <anchor><go href="ex21-19.wmls#qty()" />Buy</anchor>
10:   </p>
11:  </card>
12:
13:  <card id="card2" title="Thank you">
14:   <p><b>$count</b>x MA288 ordered <br />
15:      Total: <b> $total </b> will be charged to your account.
16:   </p>
17:   </card>
18: </wml>

This example offers a color screen smart phone called MA288. When the user clicks the Buy button (or action text), the statement in line 9 is activated to call the WMLScript function qty() in ex21-19.wmls. This qty() function uses the function Dialogs.prompt() to get the user input. The input is a value to represent the quantity he or she wants to buy. The quantity and the total price are then returned to the second card (card2) to confirm the purchase. Also, charges will be made from the mobile account.

The details of the WMLScript function qty() are listed below:

Example: ex21-19.wmls - WMLScript File For ex2119.wml

 1: extern function qty()
 2: {
 3:   var temp0=Dialogs.prompt("How many MA288 do you want?","");
 4:
 5:   var temp1 = Lang.parseInt(temp0);
 6:   WMLBrowser.setVar("count",temp1);
 7:
 8:   var temp2 = temp1 * 120;
 9:   WMLBrowser.setVar("total",temp2);
10:
11:   WMLBrowser.go( "#card2" );
12: }

Line 3 is to get the user input. The input result is stored in the variable temp0. By default, temp0 is a variable of string type. The statement in line 5 is used to convert the string into an integer and store it in temp1. This temp1 variable is then assigned to a variable called count by

WMLBrowser.setVar("count",temp1);

Therefore the variable count can carry the value back to the main page. Lines 89 are used to calculate the total cost for the ordering and assign it to a variable called total. At the end, the function

WMLBrowser.go( "#card2" );

will pass control back to card2 of the main page. A combination of this process can be used to form a effective interface for m-business. Some screen shots of this example are shown in Figs 21.4721.49.

Now, let's ask the big question: "Can we use CGI and database techniques on WML pages?" The answer to this question is "Yes."