Phong Vu – Forum NokiaSenior Architect – Emerging TechnologyAustin - 07.09.2008

Web RunTime and Widget Development

Discussion Topics

• Web RunTime for S60 Platform

• What is inside a S60 Web Widget

• S60 Web Widget Development

• WRT APIs Introduction

Web RunTime for S60 Platform

Web RunTime for S60 Platform

• A technology that enables Web applications alike called widgets to run independently from the Web browser for S60

• Supports standard-based Internet technologies• HTML 4.01, XHTML 1.0 (basic and mobile profile)• CSS 2.1• JavaScript 1.5 (standard ECMA-262)• XMLHttpRequest (AJAX)• DOM Level 2

• Includes built-in JavaScript extension libraries supporting widget’s specific features (widget, menu, system info)

• Integrated to S60 3rd Edition, Feature Pack 2 and onward

• Provides new opportunity for Web application developers to enter mobile application business.

Web Browser for S60

Browser plugins

Symbian OS

NokiaUI

features

S60 plug-ins, incl. Flash Lite, SVG, and audio.

Symbian HTTP framework

Netscapeplug-in

API

WebCore

KHTML

JavaScriptCore

KJS

Browser control API

S60 WebKit

OS adaptations Memory manager

S60 Browser UIBrowser control

clients Web Runtime

Traditional Web pages Widgets

Flexible for plug-ins & extensions

Symbian OS

NokiaUI

features

S60 plug-ins, incl. Flash Lite, SVG, and audio.

Symbian HTTP framework

Netscapeplug-in

API(NPL)

WebCoreKHTML

JavaScriptCore

KJS

Browser Control

S60 WebKit

OS adaptations Memory manager

Extensions via Netscape plug-in

Break out the Web Browser Sandbox

S60 Browser UI BCTR clients WRT

Web pages/apps Widgets

SAPI

Implements application specific native functionality

Extensions thru SAPI Framework

Web RunTime - Current Goal

• Widgets leverage the Web• use internet services and Web APIs to access information• use XMLHttpRequest and AJAX techniques• provide basic widget’s specifics features• secured behide the browser “sandbox”

• Widgets integrated into S60 user experience• managed the same as existing S60 applications• download and install like applications• can be assigned to Idle screen soft keys and shortcuts• appear in the Active Applications list• are registered as installed software in the Application Manager• display the icon in the Application Menu• are uninstalled from Application Menu and Application Manager

Web RunTime - Future Goal (beyond S60 3rd Ed. FP2)

• Widgets leverage the smart phone platform• combine information from Web with platform services

• improves user experience

• location information

• integrate widgets into Active Idle

• additional UI enhancements and features

• Widgets evolve as a development platform• integrate S60 platform services in a safely / securely

• access platform services via S60 LIW / SAPI

• provide security and signing model for widgets

Web RunTime – Widget

Web page without a browser UI• Widget is a standalone Web application

• Runs, feels & acts like a native application

• Local on the handset & distributed like any other application

• Widget at its core is a Web page designed for a specific purpose

• Widgets use same technologies, HTML, CSS, JavaScript, AJAX, as Web pages &

• Developed in days - not months or years

• Development to Deployment in “clicks”

• Types of Widget• Accessory widgets (clock, calendar …)

• Application widgets (games, address book …)

• Information widgets (weather, stocks …)

Web RunTime – Web Application Vs. Widget

• One click access to your favourite services• Less scrolling and typing

• Optimized web experience

Browser view on N95 Widget view

S60 Web Widget Designs Paradigms

• Design for small screen devices• Break down a large page into logical multiple views

• Hide elements when they are not needed to be visible

• Use widget menu to replace buttons to save screen space

• Scroll the contents rather than scrolling the screen

• Design for different screen resolutions• Detect screen size then dynamically calculate “absolute” positions

• Design for using with a keypad• Use cursor and tabbed browsing mode wisely

• Make use of the right soft-key and the options menu

• Design to save device’s resources• Reset objects (set null) as soon as they are no longer needed

• Create HTML elements dynamically and remove them as soon as they are no longer needed

• Minimize operations when a widget is in the background

What is Inside a S60 Web Widget?

S60 Web Widget Component File

• A widget is constructed by a bundle of files.info.plist (required)

[name].html (required)

icon.png (optional)

[name].css (optional)

[name].js (optional)

resources (optional)

• A widget project is a file-system directory, in which widget’s component files are stored.

• Widget’s required components and the icon.png (if included) MUST be located at the root directory of a widget project.

Info.plist – Property of a Widget

•A manifest file in XML format, containing the property and configuration information of a widget.

<?xml version="1.0" encoding="UTF-8"?><!DOCTYPE plist PUBLIC "-//Nokia//DTD PLIST 1.0//EN" "http://www.nokia.com/NOKIA_COM_1/DTDs/plist-1.0.dtd">

<plist version="1.0">

<dict><key>DisplayName</key><string>WidgetName</string><key>Identifier</key><string>com.company.widget.project</string<key>MainHTML</key>

<string>Main.html</string></dict>

</plist>

Name Type Status Description

DisplayName String Required Specify the actual name of the widget listed on the Installed application bar

Identifier String Required Specify unique string identifier for the widget in reverse domain format

MainHTML String Required Specify the name of the main HTML page that points to the widget

AllowNetworkAccess Boolean Optional Specify access to the network based resources from the widget

ShortVersionString String Optional Specify release version of the widget bundle

Version Number Optional Specify build version of the widget bundle

WRT Supported Property

Icon.png

• The icon of a widget is an image saved in Portable Network Graphics (.png) format

• The recommended size of the icon is 88x88 pixels

• If the icon.png is omitted from the widget installation package, the widget will appear with a default S60 application icon.

Inside a S60 WRT Widget

If you know how to create a Web page, then you know how to create a Widget.Existing Web based tools can be used to create Widgets

S60 Web Widget Installation Package

• Widget installation file format• Compressed with any ZIP application

• Widget installation file extension• WidgetName.wgz

• Widget installation MIME type• application/x-nokia-widget

Symbian App Code

Symbian DLL

Widget UI

Contents: HTML, JavaScript, CSS, images, etc.

Widget-enabled browser control

S60 Web Widget Development

1. Create a file-system directory on your PC. E.g.:C:\helloworld

2. Create and implement the info.plist file then save it under the root directory created in step 1C:\helloworld

info.plist3. Create and implement the HTML file, with the file name as

predefined in the info.plist at the MainHTML tagC:\helloworld

info.plistHelloworld.html

4. Create and implement any other optional files. E.g.:C:\helloworld

info.plistHelloworld.htmlhelloworld.csshelloworld.js

4 Steps in S60 Web Widget Development

1. Use WinZip to archive the widget’s directory into a zip file

2. Change the file name extension from .zip to .wgzC:\helloworld.zip C:\helloworld.wgz

3. Send the helloworld.wgz file to a device via Bluetooth. Or open the helloworld.wgz file by the File open tool in the S60 emulator

C:\helloworldinfo.plisthelloworld.htmlhelloworld.csshelloworld.js

C:\helloworld.zip

3 Steps in S60 Web Widget Deployment

S60 Web Widget Deployment

•To S60 target devices• Via Bluetooth and Infrared to the Messaging Inbox

• Via MMC card or USB port to phone memory

• Via the Web browser

•To S60 emulator• Copy to simulated phone memory under any folder where the File

manager can access. E.g.\\epoc32\winscw\c\Data\installs\

• Use the emulator’s File menu

What You Need?

• For implementing widget’s code:• Any text editor program that allows you to save the text in ANSI?

• For debugging a running widget• On Firefox

- Firebug

- JavaScript debugger plug-in

- Implement S60 Web widget’s specific object stubs!

• On S60 emulator

- Use alert() method

- Send log data to a server

- Enable Java/ECMA Script Error from the browser settings (S60 3rd Ed. FP2 v1.1)

• For testing a widget:• S60 3.2 SDK emulator, or

• Nokia devices, which support WRT

Running Web Widgets on the S60 Emulator

Using Tools on the S60 Emulator

Developing Web Widget In S60 Emulator

S60/devices/S60_3rd_FP2_SDK_v1.1/epoc32/winscw/c/

WRT APIs Introduction

Widget Object

• Widget object is a build-in module of the widget enginewidget or window.widget

• Widget object provides basic utility functions to manipulate widget’s properties

Widget Object

• Widget methods• openURL(String:url)• setPreferenceForKey(String:preference, String:key)• preferenceForKey(String:key)• prepareForTransition (String:transitionState)• performTransition(void)• setNavigationEnabled(Boolean:flag)• openApplication(Hex:Uid, String:param)• setDisplayLandscape(void)• setDisplayPortrait (void)

• Widget properties• identifier [readonly, String]• onshow [assigned callback function]• onhide [assigned callback function]• isrotationsupported [readonly, Booloean]

Widget Object

• Widget methods• openURL(String:url)• setPreferenceForKey(String:preference, String:key)• preferenceForKey(String:key)• prepareForTransition (String:transitionState)• performTransition(void)• setNavigationEnabled(Boolean:flag)• openApplication(Uid, param)• setDisplayLandscape(void)• setDisplayPortrait (void)

• Widget properties• identifier [readonly, String]• onshow [assigned callback function]• onhide [assigned callback function]• isRotationSupported [readonly, Booloean]

window.onresize = handleOrientation;

function handleOrientation() {if (window.screen.height < window.screen.width)

widget.setDisplayLandscape();else

widget.setDisplayPortrait();

widget.onhide = pause;widget.onshow = restore;

function pause(){// free resources

}function restore() {

// resume}

Widget Object

• Widget methods• openURL(String:url)• setPreferenceForKey(String:preference, String:key)• preferenceForKey(String:key)• prepareForTransition (String:transitionState)• performTransition(void)• setNavigationEnabled(Boolean:flag)• openApplication(Uid, param)• setDisplayLandscape(void)• setDisplayPortrait (void)

• Widget properties• identifier [readonly, String]• onshow [assigned callback function]• onhide [assigned callback function]• isRotationSupported [readonly, Booloean]

<a href="www.nokia.com">Click here</a>

<!-- Replace with this --><a onclick="javascript:widget.openURL(‘www.nokia.com’);">Click here</a>

This breaks the widget framework!

<form action="http://www.abc.net/echo.php" method="get"><input id="test" name="content" type="text" /><input type="submit" />

</form>

This breaks the widget framework!

Menu Object

• Menu object is an extension from the widget objectmenu or window.menu

• Menu object provides interfaces to manipulate the options menu and softkeys of a widget

Menu Object

• Menu methods• append(MenuItem menuItem)• remove(MenuItem menuItem)• getMenuItemById(Integer:id)• getMenuItemByName(String:label)• setRightSoftkeyLabel(String:label, function:callbackfunction)• showSoftkeys(void)• hideSoftkeys(void)• clear(void)

• Menu properties• onShow [assigned callback function]

Menu Object

• Menu methods• append(MenuItem menuItem)• remove(MenuItem menuItem)• getMenuItemById(Integer:id)• getMenuItemByName(String:label)• setRightSoftKeyLabel(String:label,

function:callbackfunction)• showSoftkeys(void)• hideSoftkeys(void)• clear(void)

• Menu properties• onShow [assigned callback function]

function setting(){...if (window.menu) // change the right SK label

menu.setRightSoftkeyLabel(‘Back’, toMainView);}

function toMainView(){...if (window.menu) // restore the right SK label

menu.setRightSoftkeyLabel(‘’, null);}

MenuItem Object

• MenuItem is a build-in object of the widget enginevar menuItem = new MenuItem(...);

• MenuItem provides interfaces to create menu items and submenus (cascading) for the options menu

Menu Item Object

• Menu Item methods• new MenuItem(String:label, Integer:id)• append(MenuItem:childMenuItem)• remove(MenuItem:childMenuItem)• setDimmed(Boolean:flag)

• Menu Item properties• onSelect [assigned callback function]

Menu Item Object

• Menu Item methods• new MenuItem(String:label, Integer:id)• append(MenuItem:childMenuItem)• remove(MenuItem:childMenuItem)• setDimmed(Boolean:flag)

• Menu Item properties• onSelect [assigned callback function]

function createMenu{var settings = new MenuItem(‘Settings’, 10);settings.onSelect = showSettings;window.menu.append(settings);

}

function showSettings(id){widget.prepareForTransition("fade");document.getElementById(‘main’).style.display = ‘none’;document.getElementById(‘setting’).style.display = ‘block’;setTimeout("widget.performTransition();", 0);

}

System Info Service API

• System info service API is provided thru a scriptable NetScape plug-in module.

• System info service object provides interfaces to access to limited system properties such as memory, network strength etc.

• System info service plug-in module is loaded via an HTML <embed>element

<embed type="application/x-systeminfo-widget" hidden="yes"></embed>

• System info service plug-in module is not loaded in Browser context

System Info Service API

• Power properties• chargelevel [readonly, int]• chargerconnected [readonly, int]• onchargelevel [writeonly, function]• onchargerconnected [writeonly, function]

• Network properties• signalbars [readonly, int]• networkname [readonly, string]• registrationstatus [readonly, int]

System Info Service API

• Power properties• chargelevel [readonly, int]• chargerconnected [readonly, int]• onchargelevel [writeonly, function]• onchargerconnected [writeonly, function]

• Network properties• signalbars [readonly, int]• networkname [readonly, string]• registrationstatus [readonly, int]

var sysInfo = null;

function init(){// get the handle to the system info objectsysInfo = document.embeds[0];var battLevel = sysInfo.chargelevel;sysInfo.onchargelevel = "batteryStatusCallback()";sysInfo.onchargerconnected = "chargerStatusCallback()";

}

function batteryStatusCallback() {var battLevel = sysInfo.chargelevel;

}

function batteryStatusCallback() {var chargerStatus = sysInfo.chargerconnected;

}

System Info Service API cont.

• Light methods• lighton(Int:lighttarget, Int:duration, Int:intensity, Int:fadein)• lightblink(Int:lighttarget, Int:duration, Int:onduration, Int:offduration, Int:intensity) • lightoff(Int:lighttarget, Int:duration, Int:fadeout)

• Light properties• lightminintensity [readonly, Int]• lightmaxintensity [readonly, Int]• lightdefaultintensity [readonly, Int]• lightinfiniteduration [readonly, Int]• lightmaxduration [readonly, Int]• lightdefaultcycletime [readonly, Int]• lighttargetprimarydisplayandkeyboard [readonly, Int]• lighttargetsystem [readonly, Int]

System Info Service API cont.

• Vibra methods• startvibra(Integer:duration, Integer:intensity) • stopvibra(void)

• Vibra properties• vibraminintensity [readonly, Integer]• vibramaxintensity [readonly, Integer]• vibramaxintensity [readonly, Integer]• vibrasettings [readonly, Integer]

• Beep methods• beep(Integer:frequency, Integer:duration)

• Memory properties• totalram [readonly, Integer]• freeram [readonly, Integer]

System Info Service API cont.

• File system methods• drivesize(String:drive) • drivefree(String:drive)

• File system properties• drivelist [readonly, String]

• Language properties• language [readonly, String]

Localization

• Localized resources• Widget’s name, text strings, images, stylish information (CSS) and even

JavaScript functions

• Localized resource loading contexts• When the @import directive is used in the widget’s main HTML document

@import "localizedStyle.css"

• When a resource is loaded dynamically using JavaScript code

var image document.getElementById(‘image’);

image.setAttribute(‘src’, ‘image.jpg’);

• When the ‘src’ attribute of an HTML tag is used

<script src='localizedScript.js' />

<img src="localizedImage.gif" />

Localization cont.

• Language project directory• Localized resources are stored under local language

project directory• Directory naming convention

xx.lproj

where xx is the language code e.g. “en” for English and “fi”for Finnish

• Is a direct subdirectory of a widget’s root directoryC:\helloworld

en.lproj\

fi.lproj\

Localization cont.

• Localizing widget’s name• Widget’s name is localized at installation time• Name in a local language is defined in the infoplist.stringsDisplayName = "Localized name";

• Default name must be defined in the Info.plist!

Localization cont.

• Localizing widget’s text content• Localized text strings are defined in a JavaScript file for each supported local

language

var localizedText = new Array();

localizedText[‘info1’] = "Hello";

localizedText[‘info2’] = "Goodbye";

var localizedText = new Array();

localizedText[‘info1’] = "Hola";

localizedText[‘info2’] = "Adios";

var localizedText = new Array();

localizedText[‘info1’] = "Moi";

localizedText[‘info2’] = "Hei hei";

• Name of the Javascript file should be identical for all supported languages<script type="text/javascript" src="localizedScript.js"></script>

en.lproj\

localizedSctipt.js

es.lproj\

localizedSctipt.js

fi.lproj\

localizedSctipt.js

Localization cont.

• Localizing widget’s layout• Localized layout are defined in external .CSS resource fileSpecified in the main HTML document<style type="text/css">

@import "localizedLayout.css";

</style>

Localized resource location[root]\ar.lproj\

localizedLayout.css // layout for text flow from RTL

[root]\es.lproj\

localizedLayout.css // layout for text flow from LTR

Default resource location[root]\

localizedLayout.css

Localization cont.

• Localizing widget’s image resource• Localized image resources are stored in language project directoryFinnish flag for the Finnish system language

[root]\fi.lproj\

flag.png // finnish flag

English flag for the English system language

[root]\en.lproj\

flag.png // english flag

UN flag for any other system language

[root]\

flag.png // UN flag

Load and show the flag dynamically

var flag = document.createElement(‘img’);

flag.setAttribute(‘src’, ‘flag.png’);

• ListBoxhttp://wiki.forum.nokia.com/index.php/CS000941_-_WRT_Listbox_Widget

• GridBox

http://wiki.forum.nokia.com/index.php/CS000940_-_WRT_Gridbox_Widget

JavaScript Library for WRT

• Calendarhttp://wiki.forum.nokia.com/index.php/CS000942_-_WRT_Calendar_Widget

• KeyEvent

http://wiki.forum.nokia.com/index.php/CS000943_-_WRT_NumKeyTranslator_Widget

JavaScript Library for WRT cont.

More Information

• www.forum.nokia.com/main/resources/technologies/browsing/widgets.html

Thank you!