Using WMLScript Libraries

WMLScript libraries are stored in the WAP browser, which is resident in the WAP-compliant device. In this section we will review a number of sample applications designed to help you solve common application goals. The purpose of presenting the various library functions this way is to give you a hands-on explanation of what the different libraries are capable of. For detailed information and syntax samples of all the WMLScript functions, see Appendix B, "WMLScript Library Reference".

There are currently six libraries available to use via WMLScript: Lang, Float, String, URL, WMLBrowser, and Dialogs. For the most part, it shouldn't be too difficult to guess what purpose each library serves. The Lang library contains a series of math functions. The Float library also has functions for dealing with arithmetic, but focuses on handling floating points. The String library is the largest library and contains numerous functions for handling and manipulating strings. The URL library gives you access to various components of the URL the script is loaded from, information about the host, the port number of the host, and so on. The WMLBrowser library lets you access and manipulate variables within the calling WML deck. You can also use it to invoke URLs. Finally, the Dialogs library (which is also the smallest) lets you display some data on the device from within the WMLScript. There is a further library, Console, that is available within the Phone.com UP.Simulator that allows you to print information to the console window of the UP.Simulator. This library, while not relevant for real devices, can serve as an aide in debugging your WMLScript code.

In the next few sections, I will review a number of sample applications designed to help you learn more about available WMLScript functions, as well as how you might use functions together to create powerful WAP applications and/or enhance your existing applications.

Validating User Input

In the first example, we will determine whether or not a user has entered an integer. First, we'll create a WML deck to capture the input. Second, we'll use WMLScript to determine the type of the input. The WMLScript function that we create will make use of the following WMLScript library functions:

Lang.isInt(value)

If value can be converted into an integer, this function returns true. Otherwise, the result is false.

WMLBrowser.go(url)

This performs the same task as the <go> element in WML. It is executed only after WMLScript rendering is complete. You can have multiple calls to go(), but each additional instance will override the previous one.

Save the code in Listing 9.5 as integer.wml to a directory on your Web server.

Listing 9.5 Testing the Existence of an Integer in a Variable

<?xml version="1.0"?>
<!DOCTYPE wml PUBLIC "-//WAPFORUM//DTD WML 1.2//EN"
"http://www.wapforum.org/DTD/wml12.dtd">
<wml>
    <card id="enter">
    <p>
    Enter an Integer
    <do type="accept">
        <go href="integer.wmls#testinput('$integer')"/>
    </do>
    <input name="integer"/>
    </p>
    </card>
    <card id="yes">
    <p>
    $(integer) is an integer.
    </p>
    </card>
    <card id="no">
    <p>
    $(integer) is not an integer.
    </p>
    </card>
</wml>

You'll also need to save the following code as integer.wmls in the same directory as integer.wml:

extern function testinput(testval) {
    if (Lang.isIng(testval)) {
        WMLBrowser.go("integer.wml#yes");
    }
    else {
        WMLBrowser.go("integer.wml#no");
    }
}

The enter card in integer.wml prompts the user for input and passes that value as integer to the function testinput(testval) contained in integer.wmls. The value of the variable inte ger is passed into the testinput function as a parameter, and assigned to a local variable testval. The isInt() function contained in the Lang library is then used to determine whether or not testval is of type integer. If result is true, the WMLScript returns the user to the yes card in integer.wml. Otherwise, the user is returned to the no card in the deck.

This sample application demonstrates two WMLScript library functions found in two libraries: Lang.isInt(), and WMLBrowser.go().

Validating an Email Address

Building on the preceding example, let's look at a more detailed form of content validation. Suppose you required users to input their email address. Instead of validating the format of the address in a language like JSP or PERL, you can limit the need to hit your application server by validating the format of the input in WMLScript.

In the following example, we will use some of the same library functions in valid_email.wmls as we did in integer.wmls. In this example, however, we introduce the find() function found in the String library, as well as the getVar function of the WMLBrowser library.

string.find(string,subString)

This searches string for the first instance of subString. If subString is found in string, the result is the index value of the first character of subString. If there is no occurrence of subString within string, the result is -1.

WMLBrowser.getVar(name)

This accesses the value of the variable specified by name from the browser. This function will load the value of the variable name from the WAP Browser variable space.

Save the code in Listing 9.6 as valid_email.wml in a directory on your server.

Listing 9.6 Validating Input with WMLScript

<?xml version="1.0"?>
<!DOCTYPE wml PUBLIC "-//WAPFORUM//DTD WML 1.2//EN"
"http://www.wapforum.org/DTD/wml12.dtd">
<wml>
    <card id="enter">
    <p>
    EMAIL ADDRESS
    <do type="accept">
        <go href="valid_email.wmls#testinput()"/>
    </do>
    <input name="email"/>
    </p>
    </card>
    <card id="yes">
    <p>
    $(email) is formatted correctly.
    </p>
    </card>
    <card id="no">
    <p>
    $(email) is not formatted correctly.
    </p>
    </card>
</wml>

The WML deck looks similar to the deck in the previous example except for changes to variable names. This time there are no parameters being passed into the testinput function.

Save the following code as valid_email.wmls in the same directory as valid_email.wml on your server:

extern function testinput(teststring) {
    var teststring = WMLBrowser.getVar("email");
    var atsymbol = String.find(teststring, "@");
    var period = String.find(teststring, ".");
    if (atsymbol < 0) {
        WMLBrowser.go("valid_email.wml#no");
    }
    else {
        if (period < 0) {
            WMLBrowser.go("valid_email.wml#no");
        }
        else {
            WMLBrowser.go("valid_email.wml#yes");
        }
    }
}