Managing widgets on mobile devices

Managing widgets on a mobile device is very straightforward, as most of the management is performed automatically by the S60 platform and the Web Runtime (WRT) environment. Managing a widget means handling its general cooperation with the platform and other applications on the device, including:

Launching a widget
Moving a widget to the background or foreground
Exiting a widget
Creating a self-updating widget

Launching a widget

When you implement the widget deployment correctly, a widget can be installed successfully on a mobile device. Once installed, the widget is treated in many ways the same as any mobile application. First of all, it is automatically added to the S60 application menu. Users can launch the widget by navigating to it and opening it, or possibly by pressing a softkey. In addition to creating all the mandatory widget component files, with all the mandatory properties defined, no special registering is required to enable launching.

For more information on launching widgets, see section Introduction to widgets.

Moving a widget to the background/foreground

When a widget is running, it is automatically moved to the background if there is an incoming call, for example. If you launch an S60 mobile application from your widget, it appears in the foreground and the widget is moved to the background. When the application is closed, the widget returns to the foreground. The same happens when you launch a Web page from your widget. The Web page is accessed using the Web Browser for S60.

For more information on launching an application from a widget, see the openApplication() method in the Web Runtime API reference. For more information on launching a Web page, see the openURL() method.

You can make your widget react in a certain way when it is moved to the foreground or to the background by using the onshow and onhide properties.

Exiting a widget

Users can exit a widget in several ways:

Right softkey
The right softkey is, by default, assigned to the "Exit" function, which terminates a running widget. So if you have not associated a new operation with the right softkey, your widget exits when the user presses this softkey.
Note: The control pane that shows the softkey labels is hidden by default in widgets. To have the softkey labels visible, use the showSoftkeys() method. To hide the softkey labels again, call hideSoftkeys().
Options menu
There is also an Exit option in the Options menu of every widget. This requires no implementation in the widget code. For more information on the Options menu, see section Using softkeys and the JavaScript menu object in the Web Runtime API reference.
Figure: Exiting a widget using the Options menu
Call termination key
If users press the call termination key, the widget automatically exits. This functionality requires no implementation in the widget code.
Figure: Call termination key

Creating self-updating widgets

In the JavaScript code of your widget, you can implement functionality that enables the widget to update itself without user action. Updates require a Web service or server from which the widget can query information on possible new widget versions.

To enable self-updating in a widget:

Use a variable for indicating the current version of the widget.
Send XMLHttpRequest to the Web server to query whether there is a new version of the widget available.
The reply sent by the Web server should include a URL for the widget update.
Compare the server answer to the value of the current version variable.
If there is a newer version of the widget available on the server, launch the browser using the URL of the new widget version.
When the new version of the widget has been downloaded to the mobile device, the S60 Software Installer receives the widget and installs it on top of the old version.

For an example of how to create a self-updating widget, see How to create self-updating WRT widgets available at Forum Nokia.