Nokia Web Runtime Web Widget Development Presentation for Mobile Widget Camp Austin (Delivered 7 September 2008)

1. Web RunTime and Widget Development
Phong Vu – Forum Nokia
Senior Architect – Emerging Technology
Austin - 07.09.2008

2. Discussion Topics
• Web RunTime for S60 Platform
• What is inside a S60 Web Widget
• S60 Web Widget Development
• WRT APIs Introduction

3. Web RunTime for S60 Platform

4. 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.

5. Web Browser for S60
Flexible for plug-ins &
extensions
Traditional Web pages Widgets
Browser control
S60 Browser UI Web Runtime
clients
S60 plug-ins, Netscape
plug-in Browser control API
incl. Flash Lite,
SVG, and audio. API
S60 WebCore JavaScript
Browser plugins Core
Nokia WebKit KHTML
UI KJS
features
OS adaptations Memory manager
Symbian OS Symbian HTTP framework

6. Break out the Web Browser Sandbox
Implements application
specific native
Extensions via functionality
Netscape plug-in
Web pages/apps Widgets
S60 Browser UI BCTR clients WRT
Netscape
S60 plug-ins, plug-in Browser Control
API
incl. Flash (NPL)
Lite, SVG, and JavaScript
audio. S60 WebCore
Nokia Core
WebKit KHTML SAPI
UI KJS
features
OS adaptations Memory manager
Symbian OS Symbian HTTP framework
Extensions thru
SAPI Framework

7. 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

8. 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

9. Web RunTime – Widget
• Widget is a standalone Web application
• Runs, feels & acts like a native application Web page without a browser UI
• 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 …)

10. Web RunTime – Web Application Vs. Widget
Browser view on N95 Widget view
• One click access to your favourite services
• Less scrolling and typing
• Optimized web experience

11. 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

12. What is Inside a S60 Web Widget?

13. 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.

14. Info.plist – Property of a Widget
•A manifest file in XML format, containing the property and
configuration information of a widget.
<?xml version=quot;1.0quot; encoding=quot;UTF-8quot;?>
<!DOCTYPE plist PUBLIC quot;-//Nokia//DTD PLIST 1.0//ENquot;
quot;http://www.nokia.com/NOKIA_COM_1/DTDs/plist-1.0.dtdquot;>
<plist version=quot;1.0quot;>
<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>

15. WRT Supported Property
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

16. 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.

17. 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

18. S60 Web Widget Installation Package
Symbian App Code Widget UI
Contents: HTML, JavaScript, CSS, images, etc.
Symbian DLL Widget-enabled browser control
• Widget installation file format
• Compressed with any ZIP application
• Widget installation file extension
• WidgetName.wgz
• Widget installation MIME type
• application/x-nokia-widget

19. S60 Web Widget Development

20. 4 Steps in 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 1
C:helloworld
info.plist
3. Create and implement the HTML file, with the file name as
predefined in the info.plist at the MainHTML tag
C:helloworld
info.plist
Helloworld.html
4. Create and implement any other optional files. E.g.:
C:helloworld
info.plist
Helloworld.html
helloworld.css
helloworld.js

21. 3 Steps in S60 Web Widget Deployment
1. Use WinZip to archive the widget’s directory into a zip file
C:helloworld C:helloworld.zip
info.plist
helloworld.html
helloworld.css
helloworld.js
2. Change the file name extension from .zip to .wgz
C: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

22. 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.
epoc32winscwcDatainstalls
• Use the emulator’s File menu

23. 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

24. Running Web Widgets on the S60 Emulator

25. Using Tools on the S60 Emulator

26. Developing Web Widget In S60 Emulator
S60/devices/S60_3rd_FP2_SDK_v1.1/epoc32/winscw/c/

27. WRT APIs Introduction

28. Widget Object
• Widget object is a build-in module of the widget engine
widget or window.widget
• Widget object provides basic utility functions to manipulate widget’s
properties

29. 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]

30. Widget Object
window.onresize = handleOrientation;
• Widget methods
• openURL(String:url)
function handleOrientation() {
• setPreferenceForKey(String:preference, String:key)
if (window.screen.height < window.screen.width)
• preferenceForKey(String:key)
widget.setDisplayLandscape();
• else
prepareForTransition (String:transitionState)
• widget.setDisplayPortrait();
performTransition(void)
• setNavigationEnabled(Boolean:flag)
• openApplication(Uid, param)
• setDisplayLandscape(void)
• setDisplayPortrait (void)
widget.onhide = pause;
• Widget properties
widget.onshow = restore;
• identifier [readonly, String]
• function pause(){
onshow [assigned callback function]
• onhide [assigned// free resources
callback function]
• }
isRotationSupported [readonly, Booloean]
function restore() {
// resume
}

31. Widget Object
• Widget methods This breaks the
• openURL(String:url)widget framework!
• setPreferenceForKey(String:preference, String:key)
• preferenceForKey(String:key)
<a href=quot;www.nokia.comquot;>Click here</a>
• prepareForTransition (String:transitionState)
<!-- performTransition(void)
• Replace with this -->
• setNavigationEnabled(Boolean:flag)
<a onclick=quot;javascript:widget.openURL(‘www.nokia.com’);quot;>Click
• openApplication(Uid, param)
here</a>
• setDisplayLandscape(void)
• setDisplayPortrait (void) This breaks the
• Widget properties widget framework!
• identifier [readonly, String]
<form• action=quot;http://www.abc.net/echo.phpquot; method=quot;getquot;>
onshow [assigned callback function]
• onhide [assigned callback function]
<input id=quot;testquot; name=quot;contentquot; type=quot;textquot; />
<input type=quot;submitquot; />Booloean]
• isRotationSupported [readonly,
</form>

32. Menu Object
• Menu object is an extension from the widget object
menu or window.menu
• Menu object provides interfaces to manipulate the options menu and
softkeys of a widget

33. 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]

34. Menu Object
• Menu methods
• append(MenuItem menuItem)
• remove(MenuItem menuItem)
• getMenuItemById(Integer:id)
• getMenuItemByName(String:label)
function setting(){
...
• setRightSoftKeyLabel(String:label, the right SK label
if (window.menu) // change
function:callbackfunction)
menu.setRightSoftkeyLabel(‘Back’, toMainView);
}
• showSoftkeys(void)
• hideSoftkeys(void)
function toMainView(){
...
• clear(void)
if (window.menu) // restore the right SK label
• Menu properties
}
menu.setRightSoftkeyLabel(‘’, null);
• onShow [assigned callback function]

35. MenuItem Object
• MenuItem is a build-in object of the widget engine
var menuItem = new MenuItem(...);
• MenuItem provides interfaces to create menu items and submenus
(cascading) for the options menu

36. 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]

37. Menu Item Object
• Menu Item methods
• new MenuItem(String:label, Integer:id)
• append(MenuItem:childMenuItem)
• remove(MenuItem:childMenuItem)
• function createMenu
setDimmed(Boolean:flag)
{
• Menu var settings = new MenuItem(‘Settings’, 10);
Item properties
• onSelect [assigned callback function]
settings.onSelect = showSettings;
window.menu.append(settings);
}
function showSettings(id)
{
widget.prepareForTransition(quot;fadequot;);
document.getElementById(‘main’).style.display = ‘none’;
document.getElementById(‘setting’).style.display = ‘block’;
setTimeout(quot;widget.performTransition();quot;, 0);
}

38. 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=quot;application/x-systeminfo-widgetquot; hidden=quot;yesquot;></embed>
• System info service plug-in module is not loaded in Browser context

39. 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]

40. System Info Service API
• Power properties
• chargelevel [readonly, int]
var sysInfo = null;
• chargerconnected [readonly, int]
• function init()
onchargelevel [writeonly, function]
{
• onchargerconnectedhandle to function]
// get the [writeonly, the system info object
• Network properties document.embeds[0];
sysInfo =
var battLevel = sysInfo.chargelevel;
• signalbars [readonly, int]
sysInfo.onchargelevel = quot;batteryStatusCallback()quot;;
• networkname [readonly, string]
sysInfo.onchargerconnected = quot;chargerStatusCallback()quot;;
• registrationstatus [readonly, int]
}
function batteryStatusCallback() {
var battLevel = sysInfo.chargelevel;
}
function batteryStatusCallback() {
var chargerStatus = sysInfo.chargerconnected;
}

41. 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]

42. 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]

43. 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]

44. 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 quot;localizedStyle.cssquot;
• 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=quot;localizedImage.gifquot; />

45. 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 directory
C:helloworld
en.lproj
fi.lproj

46. Localization cont.
• Localizing widget’s name
• Widget’s name is localized at installation time
• Name in a local language is defined in the infoplist.strings
DisplayName = quot;Localized namequot;;
• Default name must be defined in the Info.plist!

47. 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(); en.lproj
localizedText[‘info1’] = quot;Helloquot;;
localizedSctipt.js
localizedText[‘info2’] = quot;Goodbyequot;;
var localizedText = new Array(); es.lproj
localizedText[‘info1’] = quot;Holaquot;;
localizedSctipt.js
localizedText[‘info2’] = quot;Adiosquot;;
var localizedText = new Array(); fi.lproj
localizedText[‘info1’] = quot;Moiquot;;
localizedText[‘info2’] = quot;Hei heiquot;;
localizedSctipt.js
• Name of the Javascript file should be identical for all supported languages
<script type=quot;text/javascriptquot; src=quot;localizedScript.jsquot;></script>

48. Localization cont.
• Localizing widget’s layout
• Localized layout are defined in external .CSS resource file
Specified in the main HTML document
<style type=quot;text/cssquot;>
@import quot;localizedLayout.cssquot;;
</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

49. Localization cont.
• Localizing widget’s image resource
• Localized image resources are stored in language project directory
Finnish 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’);

50. JavaScript Library for WRT
• ListBox
http://wiki.forum.nokia.com/index.php/CS000941_-_WRT_Listbox_Widget
• GridBox
http://wiki.forum.nokia.com/index.php/CS000940_-_WRT_Gridbox_Widget

51. JavaScript Library for WRT cont.
• Calendar
http://wiki.forum.nokia.com/index.php/CS000942_-_WRT_Calendar_Widget
• KeyEvent
http://wiki.forum.nokia.com/index.php/CS000943_-_WRT_NumKeyTranslator_Widget

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

53. Thank you!