Web Runtime Widget Tutorial – Part 5: Installing the widget on your Phone

Grab the code!

In this fifth and final part part of the tutorial we look at transferring our widget from our PC based development environment to our phone.

As I said at the end of part 4 of the tutorial, we’ll be using Aptana to prepare our widget for transfer to our phone, but we’ll also need some way of getting a file from the PC to the phone.

Obviously we also need a phone that supports the Nokia WRT. Forum Nokia provide a Device Specifications table that you can filter by feature. I’ve provided a link that filters for WRT enabled devices.

I’ll be installing the widget on a Nokia E71, using a micro USB cable to move the widget from my PC to my phone.

Note: It’s also possible to install your completed widget on your S60 SDK emulator if you wish, however I’m not discussing that in this tutorial.

Packaging the widget up for its journey to your phone

In common with widgets you may have developed for other platforms, a WRT widget is packaged up into what is a standard ZIP file, with a modified file extension.

All of the constituent files of your WRT widget need to be zipped up into a single file, with the extension .wgz.

That’s not a difficult task, but Aptana helps out here turning this simple task into an even easier two-click operation directly within Aptana.

Right click on your project in Aptana, bringing up the context menu shown below:

Now click on the “Package Widget” option in the context menu:

Aptana will create a DiggClient.wgz file for you and add it to your project. The list of files in your project should now look like this:

Notice that your packaged widget file, DiggClient.wgz, is now shown in the list of files that make up your project.

Copying the widget to your phone

As I said earlier, I’m going to use a USB cable to facilitate transferring my DiggClient.wgz file to my phone. You could use Bluetooth to transfer the file, or any other method with which you are comfortable.

When I connect my phone to my PC via a USB cable, Windows will open an Explorer window showing me the accessible content on my phone:

You can in principle copy any file to any directory presented to you, although it is often suggested that you copy installation files to the “Others” directory shown in the image above.

Now you just need to find the DiggClient.wgz file on your disk and copy it to your phone. Way back in part 1 of the tutorial you will have defined the location that Aptana uses to store your project file. If you can’t remember where that is, no problem, we’ll just let Aptana show us where it has stored your project files.

Right click on the DiggClient.wgz file in your project’s list of files in Aptana to bring up the following context menu:

If you click on the “Explore Files” option in the menu, Aptana will open an Explorer window in the directory containing your project files. DiggClient.wgz should be selected in Explorer for you:

 

To copy your packaged widget to your phone, drag DiggClient.wgz from the Explorer window shown above, to the “Others” directory in the Explorer window showing the accessible contents of your phone.

Once you’ve copied the file, be sure to disconnect your phone from your PC before trying to install the widget.

Installing the widget on your phone

Installation is a simple process, although the exact mechanism will vary slightly depending on your phone model.

On the E71 a File Manager application is included in the “Office” application folder. This provides a straightforward route to installing the widget on this phone.

Using the File Manager application UI, navigate to the directory you copied DiggClient.wgz to, making sure to check you are looking at the contents of your memory card and not the phone’s internal memory. Note that although the directory was shown as “Others” in Windows Explorer, it appears as “Other” in the File Manager application UI, at least on the E71.

Once you locate the DiggClient.wgz file, select the file and answer the prompts to confirm that you want to install your widget on your phone.

Once installation is complete, you will find your widget in the “Installations” application folder. Again, the exact folder you will find your widget in will vary slightly between phone models, it may for example be in a folder called “Applications” instead.

Running your widget on your phone

In order to run your widget, you just navigate to it and launch it as you would launch any other application.

Once you’ve entered a topic in the edit field and used tab navigation to select the “Digg it” button, you will get a prompt asking you to confirm that you want your widget to connect to the internet. An internet connection is clearly necessary if we’re going to talk to Digg and retrieve some stories on your chosen topic. However, when deciding whether or not to allow your widget access to the network, bear in mind that you may have to pay for internet access from your phone.

Note that if you do not allow your widget network access, the HTTP request to Digg will fail immediately and your widget will simply show that there are no stories available.

And finally…

Well, that’s it for our tutorial widget. I hope you’ve found it useful and feel confident to go out and experiment with WRT and create some great widgets for your phone and maybe publish them on Ovi Store so others can use them too!

The widget we’ve created isn’t perfect, there are still a couple of rough edges that you could explore – the rough edges I’m thinking of  involve “focus”. Over to you!

Or you could look at extending the widget to use more services provided by the Digg APIs. One idea might be to remove the possibility of typing in a non-existent topic by retrieving a list of topics from Digg and then allowing the user to choose from such a list.

Lastly, please make use of the WRT resources available at Forum Nokia. For example, there is a collection of community provided articles & samples that show how to achieve a large number of tasks using WRT.

Have fun working on your own widgets!