Views

SDK/Docs/1.1/Web SDK with WRT

From MeeGo wiki

< SDK | Docs | 1.1(Difference between revisions)

Latest revision as of 06:59, 31 January 2011

Web Runtime and the Web SDK are provided as preview/beta technology.

The final role, or lack thereof, of WRT in MeeGo should be explained here --Vivainio 06:59, 31 January 2011 (UTC)

The Web SDK enables Web Runtime (WRT) development for MeeGo. The following is a simple guide to get you going with this exciting, flexible, and highly portable development environment.

1 What is Web Runtime?
2 What do I need to get started?
3 First WRT project
- 3.1 Running the simulator
- 3.2 Adding JavaScript
4 Debugging
5 Packaging
6 Deploying
7 Installing and running example Web Apps

What is Web Runtime?

The MeeGo Web Runtime engine allows Web Apps to run outside of the browser. A Web App is a small application built using web technologies such as Javascript, HTML, and CSS. These are often run inside a browser as add-ons. With MeeGo WRT these Web Apps can be installed and behave as stand-alone applications.

What do I need to get started?

Web Runtime engine

MeeGo already comes with the web runtime engine installed. You just need to install your WRT application (.wgt file)

Web Runtime IDE

The Web SDK provides a full development environment with support for creating MeeGo WRT apps.
It includes:

the Web Developer Environment: an Eclipse-based integrated development environment (code editor, debugger, packager etc.)
the Web SDK Simulator: runs applications in WebKit-based simulator

Download the Web SDK Technology Preview

Platform	Size	Location
Windows	188MB	http://tools.nokia.com/wrt/install/1.0/Nokia_Web_SDK_1.0.1.exe
Linux (debian)	191MB	http://tools.nokia.com/wrt/install/1.0/NokiaWebSDK_1.0.1.deb
Linux (rpm*)	192MB	http://wiki.meego.com/SDK/Docs/1.1/Web_Runtime_RPM_for_MeeGo
OSX (pkg)	222MB	http://tools.nokia.com/wrt/install/1.0/NokiaWebSDK_1.0.1.pkg

You can probably do the majority of your development using the included simulator. Eventually you'll also need a MeeGo device to deploy to, either emulated or real. See these instructions.

Documentation / APIs

The majority of the Web Runtime documentation is located on Forum Nokia and includes tutorials about developing Web Apps. The reason for this page is to briefly highlight the differences when developing Web Runtime Apps for MeeGo.

First WRT project

For the first project, we'll write a very simple "hello world" application which displays a form for a user to enter their name. JavaScript responds to the user's input and displays a personalised greeting, including the user's name.

Start WDE.
From the File menu, select New > Nokia web app (wgt).
Choose Basic web app project and click Next >.
Enter the project name and choose a directory to create the project in.
Enter the display name (how it will be listed on the device).
Enter a unique identifier for your Web App; if possible, use your own company or personal domain, with the name of the project appended. For example, I used http://developer.meego.com/elliot/helloworld.
Enter 0.0.1 for the version.
Click Next >.
Enter names for the three files which will form the basis of the Web App (the defaults are fine for now).
Click Finish.

Your project should now be visible in the File view, under Projects.

Expand the project and double-click on the index.html page. You should see the source of the HTML file in the main panel.

Add a paragraph inside the <body> tag, for example:

<p>Hello world</p>

Save it.

Running the simulator

To preview the Web App in the simulator:

Right-click on the project name in the Project Explorer.
Select Preview Web app from the context menu.
The simulator should start and display your Web App, for example:

Adding JavaScript

Interactivity is added to Web Apps by writing JavaScript functions and hooking them to the interface. You can add your own functions to the basic.js JavaScript file, automatically created for your project by WDE.

Start by editing the index.html and adding a form with a text entry box and button (NB this is HTML5):

<!DOCTYPE html>
<html>
  <head>
    <title>Greet</title>
    <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
    <script language="javascript" type="text/javascript" src="basic.js"></script>
    <link rel="stylesheet" href="basic.css" type="text/css"/>
  </head>
  <body onload="init();">

    <!-- form to enter a name -->
    <form method="post" action="index.html">
      <p><label for="name">Name</label>: <input type="text" name="name" id="name"/></p>
      <p><input type="button" value="Greet" onclick="greet();"/></p>
    </form>

    <!-- greeting will be displayed inside this paragraph -->
    <p id="greetings"/>

  </body>
</html>

The button's onclick attribute is set to the greet() callback, which we add to basic.js (note I've left the default init() function, which doesn't do anything at present):

function init() {
}

/* get the value from the name input element and display it in a greeting */
function greet() {
  var name = document.getElementById('name').value;

  if (name != '')
    document.getElementById('greetings').innerHTML = "Hello " + name;
}

Open index.html in the simulator tab again. Enter something in the text box and click on the Greet button to call the JavaScript function and display a greeting.

You should see something like this:

Note: you may occasionally need to click on the Reload button in the simulator to load your changes, as it doesn't always pick up when you save a file.

Developing client-side JavaScript applications is beyond the scope of this tutorial, but good places to find out more are:

JavaScript and HTML DOM reference
Introduction to CSS
CSS 2 specification (very readable and useful)

Debugging

WebSDK provides debugging for Web Apps running inside the simulator.

Add a breakpoint to the basic.js file by double-clicking in the margin next to a line of code. Notice in the screenshot below how a small blue circle is displayed next to the line:
In the Project Explorer, inside the expanded project content, right-click on the index.html file and select Debug As > Web Application. This starts the application in the simulator, and switches WDE into debugging perspective.
If the perspective doesn't change, go to the Window menu and select Open Perspective > Debug.
Use the Web App in the simulator.
When you perform an action which will cause the code at the breakpoint to be executed (in this case, clicking the button), the simulator pauses and passes focus back to WDE. WDE may prompt you to confirm the switch to the Debug perspective: tick the Remember my decision box and click Yes, so that the perspective automatically switches in future.
You should now see the Debug perspective, with a cursor at the breakpoint, like this:
When you've finished examining the state of the application, adding expressions etc. (all the usual Eclipse debugging functionality), use the buttons along the top of the Debug view to continue, step etc. through the program.

Packaging

Web Runtime on MeeGo uses the wgt packaging format: it's a zip file with configuration metadata in a config.xml file. The configuration follows the W3C Widget Packaging and Configuration specification.

The WDE makes it very simple to create a wgt package from a project:

Right-click on the name of your project in the Project Explorer and select Package Web app.
The output file is called <your project name>.wgt; in the case of my example project, helloworld.wgt.

Deploying

Once you have created a wgt package, transfer it to your device and run it.

Getting the package to the device

The manual approach is to copy the wgt file to the device. If you have network access to the device, you could push it to the device using ssh or similar; or log in to the device and pull the file over, using a network share, a website, Woof etc.

For example, if you have an emulated MeeGo image, you could push the file to it with:

$ scp -p 6666 <path to .wgt> meego@127.0.0.1:/<path on target image>

WDE also has a Deploy Web app option, but this requires a bluetooth connection to the target device from the host.

Installing the Web App

Install the qt-web-runtime packages on the target MeeGo device (real or emulated):

$ zypper install qt-web-runtime

See #Installing and running example Web Apps for more about running the WRT examples.

Once the Web Runtime components are installed, you are ready to install your new Web App:

$ sudo widgetinstaller <path to .wgt file>

This creates a new .desktop file in /usr/share/applications/ for your Web App. Your Web App will now appear with other applications.

Running the Web App

Run your Web App by clicking on its icon in the Applications zone; or, run it from the command line with:

$ webwidgetrunner <path to .desktop file created in previous step>

Installing and running example Web Apps

The qt-web-runtime-examples package for MeeGo includes a set of example Web Apps you can run to get an idea of WRT's capabilities. The package places them in /usr/lib/wrt/examples/demowidgets/, but they must be installed before they can be used.

For example, to install the bouncing ball Web App:

$ widgetinstaller /usr/lib/wrt/examples/demowidgets/Bouncingball.wgt

You can then run it from the Applications zone (there should be an icon for it) or the command line with:

$ webwidgetrunner /usr/share/applications/CSSBouncingBall.desktop

(The exact location of the .desktop file might require you to do some digging; ls -tlr /usr/share/applications/ can help identify the most recently added desktop file.)

Retrieved from "http://wiki.meego.com/SDK/Docs/1.1/Web_SDK_with_WRT"

Category: Meego-1.1

@@ Line 1: / Line 1: @@
 [[category:Meego-1.1]]
-'''WebSDK is currently only officially supported on Windows, so these instructions are only applicable for that OS right now (2010-10-18). WRT itself should be considered preview/beta technology.'''
+'''Web Runtime and the Web SDK are provided as preview/beta technology.'''
-The MeeGo SDK enables Web Runtime (WRT) development for MeeGo. The following is a simple guide to get you going with this exciting, flexible, and highly portable development environment.
+''The final role, or lack thereof, of WRT in MeeGo should be explained here --[[User:Vivainio|Vivainio]] 06:59, 31 January 2011 (UTC)''
+The Web SDK enables Web Runtime (WRT) development for MeeGo. The following is a simple guide to get you going with this exciting, flexible, and highly portable development environment.
 == What is Web Runtime? ==
-The MeeGo Web Runtime engine allows web "widgets" to run outside of the browser. A widget is a small application, or applet, that is built using web technologies such as Javascript, HTML, and CSS. These are often run inside a browser as add-ons. With MeeGo WRT these widgets can be installed and behave as stand-alone applications.
+The MeeGo Web Runtime engine allows Web Apps to run outside of the browser. A Web App is a small application built using web technologies such as Javascript, HTML, and CSS. These are often run inside a browser as add-ons. With MeeGo WRT these Web Apps can be installed and behave as stand-alone applications.
 == What do I need to get started? ==
-The best option for Web Runtime development at the moment is the WebSDK, maintained by Nokia. It is available from http://www.forum.nokia.com/Develop/Web/9hy25fa/ (you'll need to register to get to it). You need the '''Nokia Web SDK Technology Preview''', which has support for MeeGo widgets.
+=== Web Runtime engine ===
+MeeGo already comes with the web runtime engine installed.  You just need to install your WRT application (.wgt file)
-The Nokia Forum website includes a good set of [http://www.forum.nokia.com/Develop/Web/Getting_started/ tutorials about developing widgets]. However, the material on that site is focused on developing widgets for Symbian phones, rather than MeeGo. The reason for ''this'' page is to briefly highlight the differences when developing Web Runtime widgets for MeeGo.
+=== Web Runtime IDE ===
+The Web SDK provides a full development environment with support for creating MeeGo WRT apps. <br>
+It includes:
+* the Web Developer Environment:  an [http://wiki.eclipse.org/index.php/Rich_Client_Platform Eclipse]-based integrated development environment (code editor, debugger, packager etc.)
+* the Web SDK Simulator: runs applications in WebKit-based simulator
-Installing Web SDK is very straightforward: run the <code>.exe</code> file you downloaded and follow the prompts. You'll end up with two applications:
+==== Download the Web SDK Technology Preview ====
+<table border='1' cellpadding='3px' style="padding: 0em">
+ <tr><th>Platform</th><th>Size</th><th>Location</th></tr>
+<tr><td>Windows</td><td>188MB</td><td>http://tools.nokia.com/wrt/install/1.0/Nokia_Web_SDK_1.0.1.exe</td></tr>
+<tr><td>Linux (debian)</td><td>191MB</td><td>http://tools.nokia.com/wrt/install/1.0/NokiaWebSDK_1.0.1.deb</td></tr>
+<tr><td>Linux (rpm*)</td><td>192MB</td><td>http://wiki.meego.com/SDK/Docs/1.1/Web_Runtime_RPM_for_MeeGo</td></tr>
+<tr><td>OSX (pkg)</td><td>222MB</td><td>http://tools.nokia.com/wrt/install/1.0/NokiaWebSDK_1.0.1.pkg</td></tr>
+</table>
-# Nokia Web Developer Environment (WDE): an Eclipse-based integrated development environment (code editor, debugger, packager etc.)
+You can probably do the majority of your development using the included simulator.  Eventually you'll also need a MeeGo device to deploy to, either emulated or real. See [[SDK/Docs/1.1/Getting started with the MeeGo SDK for Linux|these instructions]].
-# Nokia Web SDK Simulator: runs applications inside a simulated device, based on WebKit
-You'll also need some kind of MeeGo device to deploy to, either emulated or real. See [[SDK/Docs/1.1/Getting started with the MeeGo SDK for Linux|these instructions]].
+=== Documentation / APIs ===
+The majority of the Web Runtime documentation is located on Forum Nokia and includes [http://www.forum.nokia.com/Develop/Web/Getting_started/Step_2_Start.xhtml tutorials about developing Web Apps]. The reason for ''this'' page is to briefly highlight the differences when developing Web Runtime Apps for MeeGo.
 == First WRT project ==
@@ Line 30: / Line 44: @@
 # Choose ''Basic web app project'' and click ''Next >''.
 # Enter the project name and choose a directory to create the project in.
-# Enter the widget's display name (how it will be listed on the device).
+# Enter the display name (how it will be listed on the device).
-# Enter a unique identifier for your widget; if possible, use your own company or personal domain, with the name of the project appended. For example, I used <code>http://developer.meego.com/elliot/helloworld</code>.
+# Enter a unique identifier for your Web App; if possible, use your own company or personal domain, with the name of the project appended. For example, I used <code>http://developer.meego.com/elliot/helloworld</code>.
-#: The ''Enable HomeScreen'' option is available for Symbian widgets. See http://wiki.forum.nokia.com/index.php/Homescreen_widget_guidelines for more details.
 # Enter 0.0.1 for the version.
 # Click ''Next >''.
-# Enter names for the three files which will form the basis of the widget (the defaults are fine for now).
+# Enter names for the three files which will form the basis of the Web App (the defaults are fine for now).
 # Click ''Finish''.
@@ Line 52: / Line 65: @@
 === Running the simulator ===
-To preview the widget in the simulator:
+To preview the Web App in the simulator:
 # Right-click on the project name in the ''Project Explorer''.
 # Select ''Preview Web app'' from the context menu.
-# The simulator should start and display your widget, for example:
+# The simulator should start and display your Web App, for example:
 [[File:Websdk-simulator.png|600px]]
@@ Line 62: / Line 75: @@
 === Adding JavaScript ===
-Interactivity is added to widgets by writing JavaScript functions and hooking them to the interface. You can add your own functions to the <code>basic.js</code> JavaScript file, automatically created for your project by WDE.
+Interactivity is added to Web Apps by writing JavaScript functions and hooking them to the interface. You can add your own functions to the <code>basic.js</code> JavaScript file, automatically created for your project by WDE.
 Start by editing the <code>index.html</code> and adding a form with a text entry box and button (NB this is HTML5):
@@ Line 121: / Line 134: @@
 == Debugging ==
-WebSDK provides debugging for widgets running inside the simulator.
+WebSDK provides debugging for Web Apps running inside the simulator.
 <ol>
@@ Line 129: / Line 142: @@
 <li>In the ''Project Explorer'', inside the expanded project content, right-click on the ''index.html'' file and select ''Debug As > Web Application''. This starts the application in the simulator, and switches WDE into debugging perspective.<br/>
 If the perspective doesn't change, go to the ''Window'' menu and select ''Open Perspective > Debug''.</li>
-<li>Use the widget in the simulator.</li>
+<li>Use the Web App in the simulator.</li>
 <li>When you perform an action which will cause the code at the breakpoint to be executed (in this case, clicking the button), the simulator pauses and passes focus back to WDE. WDE may prompt you to confirm the switch to the ''Debug'' perspective: tick the ''Remember my decision'' box and click ''Yes'', so that the perspective automatically switches in future.<br/>
 You should now see the ''Debug'' perspective, with a cursor at the breakpoint, like this:<br/>
@@ Line 140: / Line 153: @@
 Web Runtime on MeeGo uses the <code>wgt</code> packaging format: it's a zip file with configuration metadata in a <code>config.xml</code> file. The configuration follows the [http://www.w3.org/TR/widgets/ W3C Widget Packaging and Configuration] specification.
-Symbian uses <code>wgz</code> files, which are similar; however, <code>wgz</code> files contain a directory at the first level inside the archive, with the widget files inside; while <code>wgt</code> files don't have a top-level directory. The two formats also have different configuration files formats. It is therefore not possible to deploy Symbian widgets to MeeGo without modification.
 The WDE makes it very simple to create a <code>wgt</code> package from a project:
@@ Line 152: / Line 163: @@
 Once you have created a <code>wgt</code> package, transfer it to your device and run it.
-=== Getting the widget package to the device ===
+=== Getting the package to the device ===
 The manual approach is to copy the <code>wgt</code> file to the device. If you have network access to the device, you could push it to the device using ssh or similar; or log in to the device and pull the file over, using a network share, a website, [http://www.home.unix-ag.org/simon/woof.html Woof] etc.
@@ Line 162: / Line 173: @@
 WDE also has a ''Deploy Web app'' option, but this requires a bluetooth connection to the target device from the host.
-=== Installing the widget ===
+=== Installing the Web App ===
 Install the <code>qt-web-runtime</code> packages on the target MeeGo device (real or emulated):
@@ Line 168: / Line 179: @@
   $ zypper install qt-web-runtime
-Optionally, install other WRT packages:
+See [[#Installing and running example Web Apps]] for more about running the WRT examples.
- $ zypper install qt-web-runtime-devel
+Once the Web Runtime components are installed, you are ready to install your new Web App:
- $ zypper install qt-web-runtime-examples  (installs 10 .wgt files in /usr/lib/wrt/examples/demowidgets/)
-Once the Web Runtime components are installed, you are ready to install your new widget:
   $ sudo widgetinstaller <path to .wgt file>
-This creates a new <code>.desktop</code> file in <code>/usr/share/applications/</code> for your widget. Your widget will now appear with other applications.
+This creates a new <code>.desktop</code> file in <code>/usr/share/applications/</code> for your Web App. Your Web App will now appear with other applications.
-=== Running the widget ===
+=== Running the Web App ===
-Run your widget by clicking on its icon in the ''Applications'' zone; or, run it from the command line with:
+Run your Web App by clicking on its icon in the ''Applications'' zone; or, run it from the command line with:
   $ webwidgetrunner <path to .desktop file created in previous step>
+== Installing and running example Web Apps ==
+The <code>qt-web-runtime-examples</code> package for MeeGo includes a set of example Web Apps you can run to get an idea of WRT's capabilities. The package places them in <code>/usr/lib/wrt/examples/demowidgets/</code>, but they must be installed before they can be used.
+For example, to install the bouncing ball Web App:
+ $ widgetinstaller /usr/lib/wrt/examples/demowidgets/Bouncingball.wgt
+You can then run it from the ''Applications'' zone (there should be an icon for it) or the command line with:
+ $ webwidgetrunner /usr/share/applications/CSSBouncingBall.desktop
+(The exact location of the <code>.desktop</code> file might require you to do some digging; <code>ls -tlr /usr/share/applications/</code> can help identify the most recently added desktop file.)