Using WMLScript Functions

There are three types of WMLScript functions: local functions, external functions, and library functions. Which one you use will depend upon the requirement(s) of your particular WAP application. When creating WMLScript functions, bear the following in mind:

• You cannot nest functions.

• Each function name must be unique within each file.

• Make sure you pass the exact number of arguments into the function that it expects.

• Variables can only be accessed in the same WMLScript function in which they are declared. (There are no global variables within a WMLScript file.)

Local Functions

If you reference a function from within another function that is defined in the same WMLScript file, the referenced function is a local function. To help clarify that definition, take a look at the following code:

function foo (param1 , param 2, ... param n) {
    return bar(parameters);
}
function bar(param1 , param 2, ... param n) {
    return 2+2;
}

The function foo() refers to the function bar(), which is defined in the same file. In this instance, bar() is the local function.

External Functions

Any function that exists in an external file relative to the function that calls it is an external function. Observe the following example:

use url ScriptLocation "http://www.domain.com/folder";
function foo(parameters) {
    return ScriptLocation#bar(param1 , param 2, ... param n);
}

In this example, the function bar() is contained in the script found at the URL http://www.foo.com/bar. We used the URL pragma to specify the location. We assigned ScriptLocation to the URL, and then appended bar as the fragment of that URL to specify the bar() function in that WMLScript file.

We'll define and review pragmas immediately after we define the different types of functions.

Library Functions

There are a number of functions contained within WMLScript libraries. The libraries reside in the WAP browser. We will go into more detail and examples of these libraries in the next section. For now, here's an example of a library function:

function foo(param1 , param 2, ... param n) {
    return String.find("helpful","help");
}

The function foo() utilizes the find() function within the String library.

Pragmas

Pragmas are statements that allow you to add certain characteristics to your WMLScript files. There are three different pragmas available: url, access, and meta.

url Pragma

Using the url pragma allows you to use functions stored in files on remote servers. We referred to the url pragma earlier when we defined external functions. Let's look at the example again.

use url ScriptLocation "http://www.domain.com/folder";
function foo(parameters) {
    return ScriptLocation#bar(param1 , param 2, ... param n);
}

You can specify multiple URLs using multiple instances of the url pragma. If you do, they must all be placed at the top of the WMLScript file.

access Pragma

The access pragma is particularly useful for making sure others can't use your scripts. You can specify the domain and/or path of files that have permission to call the WMLScript file. Here's the syntax:

use access domain "foobar.com"
function foo(parameters) {
    return ScriptLocation#bar(param1 , param 2, ... param n);
}

This would allow the WMLScript file to be called only from files originating from the http://foobar.com domain. You could also specify

use access domain "foobar.com" path "/wml"
function foo(parameters) {
    return ScriptLocation#bar(param1 , param 2, ... param n);
}

By further specifying the path option of the access pragma, only files existing in or under the foobar.com/wml path can call your WMLScript files.