Programming the Mobile Web : Widgets and Offline Webapps - Platforms (part 1) - Symbian/Nokia

2/12/2011 3:43:12 PM
Widgets come in a lot of different varieties, as the technology has emerged from different vendors and organizations at different times.

1. Symbian/Nokia

We will start with Nokia and Symbian Foundation devices, because they are the ones with the oldest mobile widget platform and the most experience in this field. Since Series 60 3rd edition Feature Pack 2 (and for some FP1 devices with a firmware update), every Nokia device supports a version of the Web Runtime (WRT) engine. These devices hit the market starting in 2007.

WRT is a first-class citizen mobile widget engine. When a WRT widget is installed it appears like any other Symbian or Java ME installed application, and might look like Figure 1. From the user’s perspective, there is no difference between widgets and native installed applications. And, of course, the widgets are created entirely using web technologies.

Figure 1. A WRT widget looks like any other application. It even has native menu support created using JavaScript.

As a Symbian technology, WRT is also available in non-Nokia devices, such as Samsung and Sony Ericsson devices.

At the time of this writing, the platform is divided into the following versions:

  • WRT 1.0 for Series 60 3rd

  • WRT 1.1 for Series 60 5th

  • WRT 7.1 with optional home screen support (Nokia N97, N97 Mini)

  • WRT 7.2 with optional multipage home screen support (Nokia N8)

Home screen support (also known as MiniView) refers to the ability of a widget to stay on the device’s home screen all the time, with visual updates possible. This is an excellent solution for applications related to social media, news, or any other information that can benefit from being regularly updated on the user’s home screen.

The 7.1 and 7.2 numbers come from the version of the browser that is installed on those devices.

The platform access JavaScript API does not follow any of the standards we have seen so far, but it has many similarities to Apple’s Dashboard Widget API.

WRT Using Another JavaScript API

As JavaScript is a dynamic language, it is easy (almost magical) to create JavaScript wrappers to translate some other API into a WRT one. That is why we can find many wrappers for WRT for compatibility with other technologies. To use them, you have to include a script that will create all the global wrapper objects:

  • For BONDI on WRT, you can use the BONDI JavaScript standard API (not the package standard) inside a Symbian widget.

  • For PhoneGap on Symbian, there is a PhoneGap API for WRT 1.1.

  • For Nokia Platform Services 2.0 for WRT 1.X, there is an optional library for WRT that simplifies the usage of the platform’s JavaScript API.

You can find all these libraries for WRT at

1.1. Package

A WRT widget is a ZIP file with a .wgz extension, served as application/x-nokia-widget. The configuration file follows the Apple Dashboard standard, so it is a property list (info.plist) with some mandatory information:


Widget Name


The DisplayName is the name that the user will see on the screen; the Identifier is an inverse-URL mechanism to identify an application inside the device; the MainHTML is the first HTML file that will be opened with the application; the Version is used by the Application Manager when the user is downloading the application again; and if we define AllowNetworkAccess as false, we will not have any access to the Web (Ajax or resource loading). MiniViewEnabled is for compatible devices only.

The icon must be in PNG format (the recommended size for the best compatibility is 88×88 pixels), must be named icon.png, and must be located in the root folder of the package.


Nokia also offers a map widgets platform called App on Maps. App on Maps widgets are small web applications that can be installed in OVI Maps (the map solution from Nokia) and can interact with a map. More information can be found at Features

The Forum Nokia Library ( has great documentation on WRT, in the section Web Developer’s LibraryWeb Runtime widgets. WRT creates three new global objects: widget, device, and menu.


WRT allows you to define multilanguage applications; the version corresponding to the user’s defined language will automatically be selected.

In WRT 1.0 we also have a sysinfo object to access the System Information API, which allows us to access properties from battery, network information, lights, vibration, beep tone, memory, and filesystem information and system language information services. WRT 1.0 doesn’t have access to other APIs.


Platform Services 2.0 supports was added as a firmware update for Nokia N97 and Nokia N97 Mini and is included in newer devices. For other devices, we can add support by including the library.

The device object allows us to use the Platform Services API library in WRT 1.1. The standard version of Platform Services is 1.0; if we are using Platform Services 2.0, we can use some new APIs. Table 1 lists the available APIs.

Table 1. Nokia Platform Services APIs
APIAllows us to…
AppManagerList applications and launch a specific application or the default handler for a document type.
CalendarCreate, access, and manage Calendar entries.
ContactCreate, access, and manage Contact entries. In Platform Services 2.0, you can also access Contact Groups.
LandmarksCreate, access, and manage Landmark entries that are used by many map applications inside the device.
LocationRetrieve information about the user’s location.
LoggingRetrieve information about call, messaging, and data logs.
Media ManagementRetrieve information about media files stored on the device.
MessagingSend and receive messages.
SensorsAccess physical sensors on the device (like the accelerometer)
System InformationRetrieve system information (similar to WRT 1.0’s System Information API).
Camera (2.0)Launch the camera application and retrieve information on pictures taken (Platform Services 2.0 only).
Landmarks (2.0)Access to the Landmarks local database.

In Platform Services 1.0, you have access to an API using the device.getServiceObject method. It receives the API name and an interface that every API defines in the documentation. For example:

var so = device.getServiceObject("Service.Messaging", "IMessaging");

// Get all messages from the Inbox
var criteria = new Object();
criteria.Type = 'Inbox';
criteria.Filter = new Object();
criteria.Filter.MessageTypeList = new Array();
criteria.Filter.MessageTypeList[0] = 'MMS';
criteria.Filter.MessageTypeList[1] = 'SMS';

var result = so.IMessaging.GetList(criteria);

var iterator = result.returnValue;
var item;
while ((item = iterator.getNext()) != undefined){
// Access every message's properties using item

As you can see, it is a bit hard to implement simple actions. That is why Platform Services 2.0 was developed.


Every Platform Services 1.0 API call should be enclosed in a try/catch expression to handle error situations.

If you are targeting devices with WRT 1.X, you can add support for Platform Services 2.0. To do that, download the API and include a platformservices.js file in your package and code. You will then be able to access any API using the shortcut nokia.device.load(interface_name).


You can create hybrid applications for Symbian and Maemo devices using the QtWebKit project. You can find information about porting WRT widgets to QtWebKit at

For example:

var calendar = nokia.device.load("calendar");

The same SMS list sample is much simpler in 2.0:

var so = nokia.device.load("messaging");
transactionid = so.getList(listHandler, {type: "sms"},
so.SORT_BY_DATE, so.SORT_ASCENDING, errorHandler);

function listHandler(iterator) {
while (var sms = iterator.getNext() )
var message = sms.message;
var sender = sms.sender;

1.3. JavaScript API

The widget object has the following methods and properties:

Table 2. Methods and properties of the native widget object
openURL(url)Opens the specified URL in a browser window, leaving our widget in the background.
setPreferenceForKey(value, key)Stores a persistent object (the value) for a specific key that can be read by the same widget anytime. Note that the parameter order is value, key.
preferenceForKey(key)Retrieves a stored preference for a key, or returns undefined if the key doesn’t exist.
prepareForTransition("fade")Blocks any update on the UI until performTransition is invoked. This is useful if we are going to change the UI for some controls and we don’t want a flick effect.
performTransition()Updates the UI with the changes made since the prepareForTransition call.
setNavigationEnabled (Boolean)Toggles the navigation mode between the default (cursor-based with a pointer on the screen) and focus (tabbed) navigation.
setNavigationType(mode)Changes the navigation mode (you can select cursor, tabbed, or none). If none is selected, all the key events can be handled by our code. Available since WRT 7.1.
openApplication(uid, param)Launches an S60 application, identified by its hexadecimal number. There is a list of common UIDs in the documentation.
setDisplayLandscape()Changes the UI to the landscape orientation.
setDisplayPortrait()Changes the UI to the portrait orientation.
onshowFired when the application comes to the foreground.
onhideFired when the application goes to the background.
onexitFired when the user presses Exit.
isrotationsupportedBoolean indicating whether we can change the orientation on this device.

With the menu object and the MenuItem class we can create native menus, and we can define the label and handler for the left soft key with menu.setLeftSoftkeyLabel(label, handler). The right soft key is by default handled by the platform with an “Exit” label, but after WRT 7.1 you can override it using menu.setRightSoftkeyLabel(label, handler). You can also hide and show the soft key labels using showSoftkeys() and hideSoftkeys().


It is expected that WRT will support HTML 5 in the future, and that MeeGo/Maemo devices will support WRT widgets.

The onShow event of the menu object will fire when the user opens the menu.

If you don’t define a left soft key, by default it will be an “Options” submenu displaying the native menu you created. A MenuItem can have a label, an id for finding the element, an onSelect event, and optionally child MenuItem objects for submenus. For example:

// We define a label and a menu ID
var option1 = new MenuItem("Refresh", 2);
var option2 = new MenuItem("New item", 3);

// We can use the same handler and use the ID to know
// which one was pressed
option1.onSelect = menuSelected;
option2.onSelect = menuSelected;

// We append the first option

// We create a third option with a submenu
menu.append(new MenuItem("Submenu", 4));
// We can search for a MenuItem using the ID

function menuSelected(id) {
switch (id) {
// We can query the id to decide what to do


After WRT 1.1, the widget object has a wrt property that we can query for getting information about the current device and platform, including widget.wrt.version, widget.wrt.platform.model and widget.wrt.platform.romVersion.

1.4. MiniView

The MiniView, or home screen widget, allows us to display a widget’s content (continuously updated) on the user’s device home screen, as shown in Figure 2. On compatible devices (Nokia N97, N97 Mini and N8 at the time of this writing), the widget is installed as normal, but if the MiniViewEnabled property is defined as true in the info.plist file the user can opt to add it to the home screen.

Figure 2. With the MiniView, users can add our mobile web content to their home screens. Using JavaScript, the information displayed in the widget can be updated on a regular basis.

When a widget is displayed on the home screen, it shows the same HTML file it would if it were being viewed as a full-screen application. It is up to us to detect the window size change and maybe show and hide a div depending on the situation. At the time of this writing, the MiniView size is 312×82 pixels, so we can use a div with those proportions when we detect that our widget is being displayed on the home screen. When the user clicks on the widget in the home screen it will change to a full-screen display, and when the user exits the widget it will again become small (without actually exiting). The script will be running all the time, so to save the device’s battery we should keep our background code to the minimum.


When the user adds a widget to the home screen, he will receive a confirmation dialog that will allow the widget to make any API call at any time in the future without new confirmation dialogs. So, we can safely use any API (with care, please) in the background.

To update the home screen UI, we can have a timer defined in JavaScript that updates the UI by querying a server via Ajax, or we can use any other API available on the device (like Location).

You can use the onshow, onhide, and onresize events to detect whether the widget is in full or MiniView mode.


Some devices, like the Nokia N8, allow multipage home screen support, so the user has more space to add widgets to the home screen.

1.5. Tools and libraries

We can use any tools to create WRT widgets, starting with any text editor and a ZIP packager. However, Nokia offers free plug-ins for the most used IDEs in the web world that will help us with JavaScript API code hinting, emulation, and widget packaging.


Keep in mind that the emulation environments provided for widgets are really just Safari or Firefox modified to work with the APIs. The rendering engine and the JavaScript runtime are not exactly the same, and you should expect differences on real devices. You can use any S60 emulator in Windows environments for widget testing, too.

Plug-ins are available for:

  • Aptana Studio

  • Adobe Dreamweaver

  • Visual Studio

Symbian Foundation also released an Eclipse-based IDE called WRT Tools available for free for Windows, Linux and Mac.

All of these can be found at

From Aptana Studio you can use the Install Additional Features dialog, selecting the Nokia WRT plug-in.

We’ve already discussed the usage of Ajax UI libraries, and their shortcomings. For example, jQuery effects don’t have smooth results on the WRT engine. For that purpose, Nokia has developed two libraries: WRTKit and Guarana UI.


WRT supports widget localization to provide content in different languages, switching automatically to the right language. To take advantage of this you should provide image and string alternatives in a xx.lproj folder, with xx being the language code (for example, pt.lproj for Portuguese). You can find more information at

WRTKit is the most suitable for WRT 1.0 devices (non-touch), and it allows us to avoid using HTML and CSS for the application design. We can instead use a library of controls that we create and define in JavaScript, like a Java SE application.


The wiki from Forum Nokia ( has several articles about porting different widget technologies to WRT, with samples.

For newer devices, Guarana UI is a better solution. It is a jQuery UI–based solution that works perfectly with WRT widgets and also has support for creating nice home screen widgets.

Both libraries are available for free at (you can find direct links at

1.6. The APIBridge runtime

Nokia guys don’t rest when it comes to widget runtime evolution. They have recently developed APIBridge (, a Symbian native application that opens an HTTP server locally that we can contact using Ajax from our widget code. They also provide a JavaScript API file that does that work for us and have added the following widget capabilities (valid in all versions of WRT):

  • File upload support

  • Enhanced file service

  • File reading

  • Image resizing

  • Image thumbnail creation

  • Logging service

  • Location service

  • Media management

The only disadvantage is that a widget created with APIBridge needs to be packed as a native SIS file that will include the server required for this API to work. A SIS file must be signed before it can be installed on the device, and this requires a bit of Symbian knowledge.

1.7. Widget distribution

A WRT widget can be distributed in many ways, including OTA installation from your own server, offline installation from a desktop, and distribution for free or as a premium application in the Ovi Store.

The Ovi Store is the official Nokia distribution channel, where any registered developer can sell and promote applications in different formats: Symbian, Java ME, Flash Lite, Maemo, and WRT widgets. Once you’ve published a widget to the store you can select which markets you want to distribute it in, the price (can be free), and the compatible devices, and after a short QA revision period your widget will be available to anyone who visits or uses the Ovi Store application that comes with all new Nokia devices.


Nokia Series 40 devices do not currently support any widget technologies, unless you consider the Nokia Flash Lite (NFL) packages, which also use web technologies (Flash), as a kind of widget. You will need to use Java ME to develop shortcuts or little widget applications for these devices. You can also use my free service, Widgen (, for creating small applications.

If you want to publish your widgets to the Ovi Store, you should get a Publisher account at The initial fee at the time of this writing is 50 euros. Users can pay for premium content by credit card or, in some countries, via their operators’ billing systems. You will receive 70% of the revenue if the user pays with a credit card and about 40-50% of the revenue if the user pays with operator billing.

Widgets available through the Ovi Store have the potential to reach a large audience. As an example, without any promotion or marketing budget I’ve received more than 60,000 downloads in a couple of months for Widgen, a dynamic widget generation engine that I developed and have made available for free through the store.
  •  Programming the Mobile Web : Widgets and Offline Webapps - Standards
  •  Mobile Application Security : BlackBerry Security - Networking
  •  Mobile Application Security : BlackBerry Security - Local Data Storage
  •  Themes on Windows Phone 7 Devices (part 2) - Changing the Theme & Detecting the Currently Selected Theme
  •  Themes on Windows Phone 7 Devices (part 1) - Applying a Theme
  •  Programming the Mobile Web : Mobile Widget Platforms
  •  Programming the Mobile Web : Geolocation and Maps - Showing a Map
  •  Mobile Application Security - BlackBerry Security - Permissions and User Controls (part 2)
  •  Mobile Application Security - BlackBerry Security - Permissions and User Controls (part 1) - RIM Controlled APIs
  •  Windows Phone 7 Development : Working with Controls and Themes - Introducing the Metro Design System
  •  Windows Phone 7 Development : WebBrowser Control - Saving Web Pages Locally
  •  Programming the Mobile Web : Geolocation and Maps - Detecting the Location (part 3)
  •  Programming the Mobile Web : Geolocation and Maps - Detecting the Location (part 2) - Google Gears
  •  Programming the Mobile Web : Geolocation and Maps - Detecting the Location (part 1) - W3C Geolocation API
  •  Programming the Mobile Web : Geolocation and Maps - Location Techniques
  •  iPhone Programming : Table-View-Based Applications - Connecting the Controller to the Model
  •  Programming the Mobile Web : Mobilizing WordPress and Other CMSs
  •  Programming the Mobile Web : Server-Side Browser Detection and Content Delivery - Content Adaptation
  •  Programming the Mobile Web : Multimedia and Streaming
  •  Mobile Application Security : BlackBerry Security - Development and Security Testing
    Top 10
    Windows Server 2003 : Domain Name System - Command-Line Utilities
    Microsoft .NET : Design Principles and Patterns - From Principles to Patterns (part 2)
    Microsoft .NET : Design Principles and Patterns - From Principles to Patterns (part 1)
    Brother MFC-J4510DW - An Innovative All-In-One A3 Printer
    Computer Planet I7 Extreme Gaming PC
    All We Need To Know About Green Computing (Part 4)
    All We Need To Know About Green Computing (Part 3)
    All We Need To Know About Green Computing (Part 2)
    All We Need To Know About Green Computing (Part 1)
    Master Black-White Copying
    Most View
    Collaborating Within an Exchange Server Environment Using Microsoft Office SharePoint Server 2007 : Exploring Basic MOSS Features
    Get A Faster, Safer PC (Part 3) - Make text easier to read, Disable a laptop touchpad
    Algorithms for Compiler Design: THE MACHINE MODEL
    iPhone, iPad touch and iPad : Realikety
    Storage, Screens And Sounds (Part 1)
    Audio Cleaning Lab MX - makes some sounds sound better
    SQL Server 2008 : Using Remote Stored Procedures
    Sony Xperia Go
    Web Security Testing : Manipulating Sessions - Analyzing Session Randomness with WebScarab
    Understanding the Basics of Collaboration in SharePoint 2010 : Microsoft Office Integration
    Buyer’s Guide - Keyboard and mice (Part 2) - Gigabyte Multimedia Ultra-slim Profile Keyboard GK-K6150, Microsoft Natural Ergonomic Keyboard 40000
    How To Store Your Files In The Ether
    Expert advice: Printer & Scanner (Part 2) - Samsung ML-2955DW
    SharePoint 2010 : PerformancePoint Services (part 2) - Using PerformancePoint
    SQL Server System and Database Administration : System Databases
    Is The Personal Blog Dead? (Part 2) - Going Mainstream
    Choosing The Right Gear For The Right Job
    Panasonic KX-MB1530CX Multi-Function Printer : A small workhorse for document printing
    Master Black-White Copying
    Windows 7 : Installing and Running Your Software (part 1)