15.5 Refreshing the Current Card on the WML Browser: refresh() Function

The refresh() function, as suggested by its function name, is used to refresh the current card on the WML browser. It does not take any arguments:

WMLBrowser.refresh();

An empty string is returned if the function call succeeds. If any error occurs, a non-empty string is returned. What it contains depends on the WML browser you use. It should be a message explaining why the function call fails. If immediate refresh is not supported, invalid is returned and the refresh operation will be done after the WMLScript interpreter gives back control to the WML browser. The following example illustrates this. Here is the script of the example. It assigns some values to two WML variables message and message1 and performs a refresh operation.

(refreshEg1.wmls)

extern function refresh_test()
{
  WMLBrowser.setVar("message", "Hello");
  var returnMsg = WMLBrowser.refresh();
  WMLBrowser.setVar("message", "Welcome to our WMLScript tutorial");

  WMLBrowser.setVar("message1", "The result of 'isvalid returnMsg' is " + isvalid returnMsg);
}

Here is the WML document of the example. It is used to display the value of the WML variables message and message1. It also contains an anchor link that is used to execute the WMLScript function refresh_test().

(refreshEg1.wml)

<?xml version="1.0"?>
<!DOCTYPE wml PUBLIC "-//WAPFORUM//DTD WML 1.3//EN" "http://www.wapforum.org/DTD/wml13.dtd">

<wml>
  <card id="card1" title="Refresh Example">
    <p>
      <a href="refreshEg1.wmls#refresh_test()">Run WMLScript</a><br/>
      Value of 'message': $(message)<br/><br/>

      <a href="#card2">Next Card</a>
    </p>
  </card>

  <card id="card2" title="Refresh Example">
    <p>
      Value of 'message1': $(message1)
    </p>
  </card>
</wml>

Now let's open the WML document in a mobile phone browser and you will see something like this:

Sony Ericsson T68i	Nokia Mobile Browser 4.0

Click the anchor link "Run WMLScript" and the script inside the refresh_test() function will be executed. This is the result:

Sony Ericsson T68i	Nokia Mobile Browser 4.0

Notice that the result produced by the Nokia Mobile Browser and the Sony Ericsson T68i emulator is different. This is because Nokia Mobile Browser 4.0 does not support immediate refresh whereas the Sony Ericsson T68i emulator does support. The steps gone through by the Nokia Mobile Browser are:

• Assign "Hello" to the WML variable message

• Assign "Welcome to our WMLScript tutorial" to the WML variable message

• ...

• WAP browser resumes control

• Refresh the current card

Hence, you see the text "Welcome to our WMLScript tutorial" on the screen, which is the last value assigned to message.

The steps gone through by the Sony Ericsson T68i mobile browser are:

• Assign "Hello" to the WML variable message

• Refresh the current card immediately

• Assign "Welcome to our WMLScript tutorial" to the WML variable message

• ...

• WAP browser resumes control

Hence, you see the text "Hello" on the screen, which is the last value assigned to message before refreshing.

If you click the anchor link "Next Card", the value of the WML variable message1 will be shown on the mobile phone browser. It tells you that the refresh() function returns an invalid value on Nokia Mobile Browser 4.0:

Sony Ericsson T68i	Nokia Mobile Browser 4.0

Previous Page

Page 35 of 71

Next Page