Web Runtime (WRT) Quick Start
From Symbian Developer Community
Web Runtime consists of several components that allow installation and execution of Widgets. Widgets are essentially applications written in HTML/JavaScript/CSS, with JavaScript based access to some device APIs. Widgets execute inside the web browser and are very similar to web/AJAX applications we see on the web.
The really cool bit is that Widgets appear as native applications on Symbian phones during installation and at runtime (they're intuitive to install, find and use). On S60 5th edition phones (starting with N97), Widgets can also have a "home screen" representation - a mini view of the widget with active content can be shown on the phone's home screen. With an increasing number of easy-to-use APIs, widgets can access location services, messaging, address book, media files etc. making for an ideal platform for rapid development.
Widget development is supported by an excellent and growing set of plugins for major development environments - Eclipse-based Aptana Studio, Microsoft Visual Studio and Adobe DreamWeaver.
This quick start guide is targetted at developers already familiar with HTML, JavaScript and CSS. To learn about Web technologies first, and to find links to JavaScript, HTML and CSS tutorials, go to the Web Technologies Technical Overview.
Contents |
What is Web Runtime?
Web Runtime is the WebKit web browser along with a set of components that allow widget installation, app management and access to device features via a JavaScript API. Widget development using Web Runtime allows you to package up web pages, install them on the phone and run them as a standalone application using the underlying WebKit engine to render the pages.
Standards support
WebKit - and consequently Web Runtime 1.1 - currently offers support for:
- HTML 4.01
- XHTML mobile profile
- CSS 2.1
- JavaScript 1.5
Availability
Web Runtime 1.1 is available on Symbian^1 devices (S60 5th Edition) such as the Nokia N97. Web Runtime 1.0 is available on following phones:
- All S60 3rd Edition FP2 and later phones
- Samsung S60 3rd Edition FP1
- Nokia S60 3rd Edition FP1 phones with latest firmware update
More information about Web Runtime versions can be found here.
Setting up the development environment
Because Aptana Studio development environment is free, we'll use it for our quick start guide.
First, go to the Aptana Download page and download and install the latest version. After installation, you must install the Nokia Web Runtime Plugin. Start Aptana Studio and open "My Aptana" (Window->My Aptana). Open the "Plugins" section, locate the Nokia WRT plugin, click get it and follow the on-screen instructions.
More details on plugin versions can be found here.
Hello World
Let's now create a simple project with Aptana. On the File menu select New->Project.
Follow through with the Wizard as follows.
 Wizard step 1 |
 Wizard step 2 |
 Wizard step 3 |
Note the project type options in step two above. Normally, you will be choosing between "Basic Widget project" and "Basic Widget project with WRTKit". The difference between the two is that the former leaves it to the developer to choose how they are building the user interface - manually via HTML/CSS/JavaScript or by including third party libraries (such as YUI). The latter option includes WRTKit, a small and fairly simple JavaScript library of user interface components (ListView, Label, TextField etc.) that can be used to build your application.
For now, let's follow through with the basic project as above. In the final step, click Finish to complete the wizard.
Once project is created, double click on index.html in the Project view to open the file. Let's modify the code as follows:
<body onLoad="javascript:init();">
Your name:
<input id="namebox"><br>
<input type=submit value="Say hello"
onclick="document.getElementById('output').innerHTML = 'Hello ' + document.getElementById('namebox').value;">
<div id="output">
</div>
</body>
To view our widget in action, we can now switch to preview tab.
To run the widget on a phone, we first need to produce installable widget archive file. Aptana provides an option for automatic package creation as below.
This produces the widget archive (extension .WGZ), which is in fact a zip file containing project files. The WGZ file can now be transferred to the phone and installed. See How to get an app to the phone if you need help with transferring the file and installation.
 | Note WGZ is a plain zip containing all our project files. Consequently, end users can see the widget source if they open it with a standard zip file utility. While this is great for learning, some developers may want to protect their widget code. This can be achieved by adding JavaScript obfuscation before packaging. |
Advanced Hello World
The previous example shows just how easy it is to create widgets. Aptana deals with meta data (info.plist) and packaging and we can create a widget by just adding some static html to index.html.
However, any good widget will require more programmatic control. Using JavaScript we can produce proper applications with natively integrated menus, AJAX server interactions and access to device features such as GPS, contacts etc.
To simplify development of the user interface we'll use WRTKit. As before, we initiate the new project wizard by selecting New->Project on the File menu.
Follow through with the Wizard as follows.
Wizard step 1 |
 Wizard step 2 |
Wizard step 3 |
Note that we have now selected Basic Widget with WRTKit.
Finally, click Finish.
The project is now created and we can see our demo widget in action. In the project view, locate index.html and double click to open it. Open the "Nokia Web Runtime" tab (shown in the pic above) to start preview.
Preview options such as screen size and orientation can be set in the "Settings" dialog.
The code for the widget is in basic.js (unless you have selected a different name in the wizard). Thanks to the following code in index.html
<body onload="init()">
the init() function will be first called when the widget is loaded. Let's examine the initialisation code:
This first section creates the About menu item and sets up navigation and menu modes. What is more interesting is the if statement surrounding this code. This essentially checks if the widget is running in an environment that supports WRT extensions such as on device, emulator or in preview pane. If however, the code is running in different environment (such as a regular web browser), the guarded code would cause an error, which is a common source of problems when debugging with Firebug and Firefox. So, in order to allow debugging, always guard WRT specific code with
// set tab-navigation mode and show softkeys
// (only if we are in the WRT environment)
if (window.widget) {
//create about menu
var aboutMenuItem = new MenuItem("About", MENU_ITEM_ABOUT);
aboutMenuItem.onSelect = menuItemSelected;
menu.append(aboutMenuItem);
widget.setNavigationEnabled(false);
menu.showSoftkeys();
}
// create UI manager
uiManager = new UIManager();
if(window.widget){...}
The final step initialises the UIManager class used for WRTKit control management.
Further, the code initialises GUI components. This should be familiar ground and WRTKit is extremely simple and intuitive.
// create main view
mainView = new ListView(null, "Hello World");
//Create about view
aboutView = new ListView(null, "Hello World");
// add a text field to the view
nameField = new TextField(null, "Enter your name");
mainView.addControl(nameField);
// add a button to the view
helloButton = new FormButton(null, "Say Hello!");
helloButton.addEventListener("ActionPerformed", helloButtonClicked);
mainView.addControl(helloButton);
// About lable control
aboutLabel = new Label();
aboutView.addControl(aboutLabel);
Finally, we set the current view using the UIManager.
// display the main view
uiManager.setView(mainView);
Debugging
Aptana Studio can also be used for debugging widget projects. In order for this to work, you will need to install:
Once installation is complete, go back to Aptana and create a new debug configuration for Firefox:
- From the Debug menu, select "Debug..." to open the debug window.
- Click the New Launch Configuration button to create a new configuration.
- Type a name for your new configuration (e.g. "Hello Widget").
- Under Start Action, choose the option for the start page for the debugger.
Once Aptana, Firefox and Firebug are ready, a shorter route to kick-off debugging is using the toolbar 
button. You can also right click on index.html in your project and select "Debug As" then "JavaScript Web Application".
Next steps
Now you've got the right setup you can start experimenting. Of course, we've just scratched the surface here. For more information, here are the best WRT resources:
- Web Technologies category on developer.symbian.org
- Web Developers Library on Forum Nokia
- Web Runtime Articles on Forum Nokia
Sign in to comment…
If a proxy configuration is missing when installing plug-in, Aptana announces it as "one or more required items not found".
--Pp7 14:25, 26 November 2009 (UTC)