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.
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.
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 http://www.mobilexweb.com/go/wrt. |
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:
"http://www.nokia.com/NOKIA_COM_1/DTDs/plist-1.0.dtd">
DisplayName
Widget Name
Identifier
com.mobilexweb.widget_unique_id
MainHTML
Main.html
Version
1.0
AllowNetworkAccess
MiniViewEnabled
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.
Note:
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 http://forum.nokia.com/ovi.
12.3.1.2. Features
The Forum Nokia Library (http://library.forum.nokia.com) has great documentation
on WRT, in the section Web Developer’s Library→Web Runtime widgets. WRT creates three new
global objects: widget, device, and menu.
Note:
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.
Note:
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
| API | Allows us
to… |
|---|
| AppManager | List applications and
launch a specific application or the default handler for a
document type. |
| Calendar | Create, access, and
manage Calendar entries. |
| Contact | Create, access, and
manage Contact entries. In Platform Services 2.0, you can also
access Contact Groups. |
| Landmarks | Create, access, and
manage Landmark entries that are used by many map applications
inside the device. |
| Location | Retrieve information
about the user’s location. |
| Logging | Retrieve information
about call, messaging, and data logs. |
| Media
Management | Retrieve information
about media files stored on the device. |
| Messaging | Send and receive
messages. |
| Sensors | Access physical sensors
on the device (like the accelerometer) |
| System
Information | Retrieve 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;
iterator.reset();
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.
Warning:
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).
Note:
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 http://wiki.forum.nokia.com.
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
| Method/property | Description |
|---|
| 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. |
| onshow | Fired when the
application comes to the foreground. |
| onhide | Fired when the
application goes to the background. |
| onexit | Fired when the user
presses Exit. |
| isrotationsupported | Boolean 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().
Note:
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
menu.append(option1);
// We create a third option with a submenu
menu.append(new MenuItem("Submenu", 4));
// We can search for a MenuItem using the ID
menu.getMenuItemById(4).append(option2);
function menuSelected(id) {
switch (id) {
// We can query the id to decide what to do
}
}
Note:
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.
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.
Note:
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.
Note:
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.
Warning:
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 http://www.mobilexweb.com/go/widgets.
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.
Note:
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 http://wiki.forum.nokia.com.
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.
Note:
The wiki from Forum Nokia (http://wiki.forum.nokia.com) 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 http://wiki.forum.nokia.com (you can find direct links
at http://www.mobilexweb.com/go/widgets).
1.6. The APIBridge runtime
Nokia guys don’t rest when it comes to widget runtime evolution.
They have recently developed APIBridge (http://wiki.forum.nokia.com/index.php/APIBridge_Web_Runtime_API),
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 http://store.ovi.com or uses the Ovi Store application
that comes with all new Nokia devices.
Note:
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 (http://www.widgen.com), for
creating small applications.
If you want to publish your widgets to the Ovi Store, you should
get a Publisher account at http://publish.ovi.com. 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.
