Anatomy of a widget
From Symbian Developer Community
 |
| ||||||||||||
Creating widgets is quite easy using development tools such as Eclipse based Aptana, Adobe Dreamweaver and Microsoft Visual Studio. However, understanding what is required for a minimal application provides a good foundation. Not only does one understand what is required but you learn to appreciate the functionality provided by what is optional.
Let's consider a minimal Symbian/S60 widget. It is composed of two files: info.plist and an html file.
info.plist is an xml file containing key value pairs. It must define the application name, an identifier and the html file. Here is a example.
info.plist:
<?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>MySiteWidget</string>
<key>Identifier</key>
<string>com.MySiteWidget.basic.widget</string>
<key>MainHTML</key>
<string>Main.html</string>
</dict>
</plist>
Main.html
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd">
<html>
<head>
<title>Simple widget</title>
</head>
<body id="body">
The sky is so beautiful. I can bite my toes.
</body>
</html>
These files are usually created by a development tool wizard. The tools we have already mentioned - Eclipse based Aptana, Adobe and Microsoft Visual Studio plugins all create these files and allow editing and debugging widgets. Still, it is useful to understand the process, so let's do this widget without the help of tools. Deploying is pretty simple:
- Assuming these two files are in their own directory, we can simply zip it up (Use Windows Explorer and Send To a compressed folder.)
- Rename the file extension from zip to wgz.
- Send it over to the phone.
Normally, you would use Aptana to do this. However, if doing this manually, we must ensure that:
- The name of the html file must match the string in info.plist
- The wgz file name must match the directory name that includes the files
Getting the app to the phone is quite easy - there are many ways described here.
Now let's turn our attention to the phone. This minimal widget will show up on the phone like any other application. Launch the application which we called MySiteWidget. Not too exciting. You should see a white screen displaying the text from the html file. Developer's will appreciate that no signing was involved. User's will appreciate not having to entry a URL on the phone and that it is easy to launch the application.
Bring your website to the phone with the minimal steps
To put this knowledge to good use, let's modify this simple widget to show an existing web site. This could be useful if you already have a website and want the simplest way to create a site widget. Ideally your site should be able to render pages for smaller screens, but even if that is not the case, the phone browser will do a decent job of rendering for you.
Given the WRT API, you might be tempted to use the URL as an argument to widget.openURL(). This will go to the desired website but it will launch the web browser - in a new window. An alternative approach which will show the site in the widget window would be using window.location, as follows:
window.location = "http://m.twitter.com";
When the widget is installed, you can go to mobile version of twitter from the phone menu!
If you run this widget, you'll notice a problem. There are no softkeys. Here is the code to fix that.
if (window.widget) {
menu.showSoftkeys();
}
The JavaScript code can be either embedded in HTML or supplied in a separate file. Since our widget is so simple, we'll embed it in HTML:
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd">
<html>
<head>
<title>My Site Widget</title>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
</head>
<body onLoad="javascript:init();">
<script language="javascript" >
function init() {
if (window.widget) {
menu.showSoftkeys();
}
window.location = "http://m.twitter.com";
}
</script>
</body>
</html>
Comments
Hamishwillee said…
Stichbury said…
Didja read the Maintenance comment? This article is recognisably in "a stateTM" and in Ivan's list to sort out. He's not got there yet. It's almost tempting to delete it anyway but let's give it one last shot. Maybe you can help Tasneem, from Paul's team, who is over for SEE to sort it out and take it off Ivan's lengthy to do list?
--Stichbury 10:13, 16 October 2009 (BST)
Ivanl said…
Page refactored. Most content has been moved to appropriate locations, and the remainder has been turned into a recipe.
--Ivanl 11:45, 26 October 2009 (UTC)
Sign in to comment…
What does the line mean " Also, when the user exits the browser they will need to widget."
Everything after heading "bring your website to the phone with the minimal steps" needs to be re-written to add context. It just doesn't make any sense the way it is now.
--Hamishwillee 04:30, 16 October 2009 (BST)