×
Namespaces

Variants
Actions
(Difference between revisions)

How to port Bondi Widgets to Symbian Web Runtime

From Nokia Developer Wiki
Jump to: navigation, search
jaaura (Talk | contribs)
m
hamishwillee (Talk | contribs)
m (Hamishwillee - Bot update - Fix ArticleMetaData)
 
(13 intermediate revisions by 3 users not shown)
Line 1: Line 1:
[[Category:Web Runtime (WRT)]][[Category:How To]][[Category:Porting]]
+
{{ArticleMetaData <!-- v1.2 -->
 +
|sourcecode= [[Media:Info.plist.zip]]
 +
|installfile= <!-- Link to installation file (e.g. [[Media:The Installation File.sis]]) -->
 +
|devices= <!-- Devices tested against - e.g. ''devices=Nokia 6131 NFC, Nokia C7-00'') -->
 +
|sdk= <!-- SDK(s) built and tested against (e.g. [http://linktosdkdownload/ Nokia Qt SDK 1.1]) -->
 +
|platform= <!-- Compatible platforms - e.g. Symbian^1 and later, Qt 4.6 and later -->
 +
|devicecompatability= <!-- Compatible devices e.g.: All* (must have internal GPS) -->
 +
|dependencies= <!-- Any other/external dependencies e.g.: Google Maps Api v1.0 -->
 +
|signing= <!-- Signing requirements - empty or one of: Self-Signed, DevCert, Manufacturer -->
 +
|capabilities= <!-- Capabilities required by the article/code example (e.g. Location, NetworkServices. -->
 +
|keywords= <!-- APIs, classes and methods (e.g. QSystemScreenSaver, QList, CBase -->
 +
|language= <!-- Language category code for non-English topics - e.g. Lang-Chinese -->
 +
|translated-by= <!-- [[User:XXXX]] -->
 +
|translated-from-title= <!-- Title only -->
 +
|translated-from-id= <!-- Id of translated revision -->
 +
|review-by= <!-- After re-review: [[User:username]] -->
 +
|review-timestamp= <!-- After re-review: YYYYMMDD -->
 +
|update-by= <!-- After significant update: [[User:username]]-->
 +
|update-timestamp= <!-- After significant update: YYYYMMDD -->
 +
|creationdate= 20091102
 +
|author= [[User:Miasa]]
 +
}}[[Category:Porting]][[Category:Symbian Web Runtime]][[Category:How To]]
 +
{{ArticleNeedsUpdate|timestamp=20111013010421|user=[[User:Hamishwillee|&lt;br /&gt;----]]|The Bondi site no longer exists - links to it have broken. It appears that Bondi may have been merged into [http://www.wacapps.net/sdk WAC SDK] however I can't find a clear explanation. This article therefore out of date and should either be deleted or updated to reflect the new API and state of Bondi. This will require some expert help.}}
 
== Preface ==
 
== Preface ==
 
There are many different widget technologies and runtimes out there. One common denominator between many of them is the fact that they are, in effect, renamed zip packages containing common web technologies like HTML, CSS and Javascript etc.
 
There are many different widget technologies and runtimes out there. One common denominator between many of them is the fact that they are, in effect, renamed zip packages containing common web technologies like HTML, CSS and Javascript etc.
  
[http://bondi.omtp.org/default.aspx Bondi] is an open source industry collaboration for widget and web technologies. The following contains guidelines for porting a Bondi widget to the [[::Category:Web Runtime (WRT)|S60 Web Runtime]].
+
Bondi is an open source industry collaboration for widget and web technologies. The following contains guidelines for porting a Bondi widget to the [[::Category:Web Runtime (WRT)|S60 Web Runtime]].
  
 
== Target Audience ==
 
== Target Audience ==
Line 40: Line 62:
 
Take a Bondi widget and unzip it using the unzipping program of your choice. Remember to retain the folder structure, if possible. Note: file extension may need to be changed to *.zip before being extracted.
 
Take a Bondi widget and unzip it using the unzipping program of your choice. Remember to retain the folder structure, if possible. Note: file extension may need to be changed to *.zip before being extracted.
  
=== 2. Create an <tt>info.plist</tt> manifest file ===
+
=== 2. Create an {{Icode|info.plist}} manifest file ===
When installing a *.wgz file the system looks for a manifest file called info.plist. The Bondi Widget equivalent is called <tt>config.xml</tt>.
+
When installing a *.wgz file the system looks for a manifest file called info.plist. The Bondi Widget equivalent is called {{Icode|config.xml}}.
  
Here's how to use the Bondi Widget <tt>config.xml</tt> data to create the WRT manifest file.
+
Here's how to use the Bondi Widget {{Icode|config.xml}} data to create the WRT manifest file.
  
#'''Download and unzip this [http://www.forum.nokia.com/piazza/wiki/images/b/b0/Info.plist.zip info.plist template file] and save it in the widget's root directory.'''<br /><br />
+
#'''Download and unzip this [[Media:Info.plist.zip|info.plist template file]] and save it in the widget's root directory.'''<br /><br />
#'''Add the <tt>DisplayName</tt> (mandatory)'''<br />This can be found from the <tt><name></tt> element of the config.xml file.<br /><br />
+
#'''Add the {{Icode|DisplayName}} (mandatory)'''<br />This can be found from the {{Icode|<name>}} element of the config.xml file.<br /><br />
#'''Add the <tt>Identifier</tt> (mandatory)'''<br />The <tt>id</tt> attribute in <tt>config.xml</tt> can be found in the <tt><widget></tt> element.<code><widget xmlns="http://www.w3.org/ns/widgets"  
+
#'''Add the {{Icode|Identifier}} (mandatory)'''<br />The {{Icode|id}} attribute in {{Icode|config.xml}} can be found in the {{Icode|<widget>}} element.<code><widget xmlns="http://www.w3.org/ns/widgets/"  
xmlns:bondi="http://bondi.omtp.org/ns/widgets"  
+
xmlns:bondi="http://bondi.omtp.org/default.aspx/widgets"  
id="http://bondi.omtp.org/widgets/location"
+
id="http://bondi.omtp.org/default.aspx/widgets/location"
version="1.0"></code>These can be formatted into the same form as the conventional WRT Identifier, which is the URL in reverse with the widget name appended to the end.<br />eg. http://bondi.omtp.org/widgets/location → org.omtp.bondi.widgets.location<br /><br />
+
version="1.0"></code>
#'''Add the <tt>MainHTML</tt> (mandatory)'''<br />Bondi widget config.xml files contain a <tt><content></tt> element, whose attribute <tt>src</tt> contains the HTML file to be opened by the HTML renderer.  If this element exists, its value should be assigned to the MainHTML key in the info.plist file.<br /><br />If it does not exist, then the default value, index.html should be assigned to the MainHTML key.<br /><br />
+
These can be formatted into the same form as the conventional WRT Identifier, which is the URL in reverse with the widget name appended to the end. e.g. <nowiki>http://bondi.omtp.org/default.aspx/widgets/location</nowiki> → org.omtp.bondi.widgets.location<br /><br />
#'''<tt>AllowNetworkAccess</tt> (optional)'''<br />If the widget requires network access, add a self closing tag <tt><true /></tt> under <tt>AllowNetworkAccess</tt> element. To deny network access, add a self closing tag <tt><false /></tt> under <tt>AllowNetworkAccess</tt> element. Leaving the element out of <tt>info.plist</tt> completely is the same as having set the element to false.<br /><br />
+
#'''Add the {{Icode|MainHTML}} (mandatory)'''<br />Bondi widget config.xml files contain a {{Icode|<content>}} element, whose attribute {{Icode|src}} contains the HTML file to be opened by the HTML renderer.  If this element exists, its value should be assigned to the MainHTML key in the info.plist file.<br /><br />If it does not exist, then the default value, index.html should be assigned to the MainHTML key.<br /><br />
#'''<tt>Version</tt> (optional)'''<br />This tag facilitates updating of the widget, allowing it to check if there is a newer version available. The <tt>version</tt> attribute in <tt>config.xml</tt> can be found in the <tt><widget></tt> element.<br /><br />
+
#'''{{Icode|AllowNetworkAccess}} (optional)'''<br />If the widget requires network access, add a self closing tag {{Icode|<true />}} under {{Icode|AllowNetworkAccess}} element. To deny network access, add a self closing tag {{Icode|<false />}} under {{Icode|AllowNetworkAccess}} element. Leaving the element out of {{Icode|info.plist}} completely is the same as having set the element to false.<br /><br />
 +
#'''{{Icode|Version}} (optional)'''<br />This tag facilitates updating of the widget, allowing it to check if there is a newer version available. The {{Icode|version}} attribute in {{Icode|config.xml}} can be found in the {{Icode|<widget>}} element.<br /><br />
 
#'''Save the file.'''
 
#'''Save the file.'''
  
 
=== 3. Find, Move and Rename the icon ===
 
=== 3. Find, Move and Rename the icon ===
You can find the icon file by following the path in <tt>config.xml</tt>:
+
You can find the icon file by following the path in {{Icode|config.xml}}:
 
<code><icon src="thumbnail.png"/></code>
 
<code><icon src="thumbnail.png"/></code>
Copy that image to the root of the widget folder. The icon must be in PNG format and named <tt>icon.png</tt>.<br /><br />
+
Copy that image to the root of the widget folder. The icon must be in PNG format and named {{Icode|icon.png}}.<br /><br />
  
 
=== 4. Add Javascript Libraries (optional) ===
 
=== 4. Add Javascript Libraries (optional) ===
If the widget uses geolocation API, copy files [[Media:Bondi.txt | Bondi.txt]] and [[Media:Platformservices.txt | Platformservices.txt]] to the root of the widget folder. Change the extensions from <tt>*.txt</tt> to <tt>*.js</tt>.
+
If the widget uses geolocation API, copy files [[Media:Bondi.txt | Bondi.txt]] and [[Media:Platformservices.txt | Platformservices.txt]] to the root of the widget folder. Change the extensions from {{Icode|*.txt}} to {{Icode|*.js}}.
  
Add the following lines inside <tt><head></tt> element in main HTML file:
+
Add the following lines inside {{Icode|<head>}} element in main HTML file:
 
<code><script type="text/javascript" src="Bondi.js"></script>
 
<code><script type="text/javascript" src="Bondi.js"></script>
 
<script type="text/javascript" src="Platformservices.js"></script></code>
 
<script type="text/javascript" src="Platformservices.js"></script></code>
  
If the widget does not use geolocation API, copy only [[Media:Bondi.txt | Bondi.txt]] to the root of the widget folder and change the extension from <tt>*.txt</tt> to <tt>*.js</tt>.
+
If the widget does not use geolocation API, copy only [[Media:Bondi.txt | Bondi.txt]] to the root of the widget folder and change the extension from {{Icode|*.txt}} to {{Icode|*.js}}.
  
Add the following line inside <tt><head></tt> element in main HTML file:
+
Add the following line inside {{Icode|<head>}} element in main HTML file:
 
<code><script type="text/javascript" src="Bondi.js"></script></code>
 
<code><script type="text/javascript" src="Bondi.js"></script></code>
  
Line 92: Line 115:
 
*[[How to port Adobe AIR to WRT]]
 
*[[How to port Adobe AIR to WRT]]
 
*[[How to port Opera Widgets to Nokia WRT]]
 
*[[How to port Opera Widgets to Nokia WRT]]
*[http://library.forum.nokia.com/index.jsp?topic=/Web_Developers_Library/GUID-4D13AF3F-4733-44E7-996F-F27A11C9D6BF_cover.html Web Developer's Library 1.7]
+
*[http://library.developer.nokia.com/index.jsp?topic=/Web_Developers_Library/GUID-4D13AF3F-4733-44E7-996F-F27A11C9D6BF_cover.html Web Developer's Library 1.7]
 
+
*[http://bondi.omtp.org/ Bondi home page]
+
*[http://bondisdk.limofoundation.org/ Bondi SDK - LiMo Foundation]
+
  
 +
*[http://www.wacapps.net/sdk WAC SDK] (former Bondi).
  
 
Note that Bondi references may require login credentials.
 
Note that Bondi references may require login credentials.
 +
[[Category:Code Examples]]

Latest revision as of 08:25, 1 August 2012

Article Metadata
Code ExampleArticle
Created: User:Miasa (02 Nov 2009)
Last edited: hamishwillee (01 Aug 2012)

Needs-update.pngThis article needs to be updated: If you found this article useful, please fix the problems below then delete the {{ArticleNeedsUpdate}} template from the article to remove this warning.

Reasons: hamishwillee (13 Oct 2011)
The Bondi site no longer exists - links to it have broken. It appears that Bondi may have been merged into WAC SDK however I can't find a clear explanation. This article therefore out of date and should either be deleted or updated to reflect the new API and state of Bondi. This will require some expert help.

Contents

[edit] Preface

There are many different widget technologies and runtimes out there. One common denominator between many of them is the fact that they are, in effect, renamed zip packages containing common web technologies like HTML, CSS and Javascript etc.

Bondi is an open source industry collaboration for widget and web technologies. The following contains guidelines for porting a Bondi widget to the S60 Web Runtime.

[edit] Target Audience

These instructions are targeted for developers who wish to port their own Bondi widgets to Nokia WRT. It is assumed that they know whether a Bondi widget uses built in Bondi objects and if it requires network access.

[edit] Technology Compatibility

[edit] Web standard technologies

Nokia WRT supports the following technologies:

  • HTML 4.01 Specification, W3C Recommendation 24 December 1999,
  • XHTML Mobile Profiles Specification, XHTML Mobile Profile Version 29-Oct-2001, WAP-277-XHTMLMP-20011029-a
  • CSS Level 2 revision 1 (CSS 2.1), WAP CSS Specification Version 26-Oct-2001, WAP-239-WCSS-20011026-a
  • JavaScript 1.5 (ECMA-262 3rd Edition), ECMAScript Language Specification, 3rd edition (December 1999)
  • The combination of XML, XHTML/HTML, CSS, DOM, and the XMLHttpRequest object to add Ajax capability to a widget


If the widget you wish to port uses technologies that are not in this list, then it will not function as intended without modifications to the source code.

[edit] Runtime specific Javascript APIs

If only standard Javascript has been used in the widget, then no additional javascript libraries need to be added to the widget.

However, the Bondi Widget environment provides Javascript APIs that allows widgets to access special functionality. Those functionalities work differently in the Nokia WRT environment. If the built-in Bondi Widget APIs have been used, then additional Javascript libraries need to be added to the widget. Step 4 explains how to do this.

Be aware that the library is only partially supported and as such will have reduced functionality. The following is a list of the supported functionality.

[edit] Supported attributes and methods

  • bondi.devicestatus.getPropertyValue({aspect:Battery,property:batteryBeingCharged})
  • bondi.geolocation.getCurrentPosition()


To add more functionality, refer to Extending Bondi wrapper library.

[edit] The Method

[edit] 1. Unzip the Bondi package

Take a Bondi widget and unzip it using the unzipping program of your choice. Remember to retain the folder structure, if possible. Note: file extension may need to be changed to *.zip before being extracted.

[edit] 2. Create an info.plist manifest file

When installing a *.wgz file the system looks for a manifest file called info.plist. The Bondi Widget equivalent is called config.xml.

Here's how to use the Bondi Widget config.xml data to create the WRT manifest file.

  1. Download and unzip this info.plist template file and save it in the widget's root directory.

  2. Add the DisplayName (mandatory)
    This can be found from the <name> element of the config.xml file.

  3. Add the Identifier (mandatory)
    The id attribute in config.xml can be found in the <widget> element.
    <widget xmlns="http://www.w3.org/ns/widgets/" 
    xmlns:bondi="http://bondi.omtp.org/default.aspx/widgets"
    id="http://bondi.omtp.org/default.aspx/widgets/location"
    version="1.0">

These can be formatted into the same form as the conventional WRT Identifier, which is the URL in reverse with the widget name appended to the end. e.g. http://bondi.omtp.org/default.aspx/widgets/location → org.omtp.bondi.widgets.location

  1. Add the MainHTML (mandatory)
    Bondi widget config.xml files contain a <content> element, whose attribute src contains the HTML file to be opened by the HTML renderer. If this element exists, its value should be assigned to the MainHTML key in the info.plist file.

    If it does not exist, then the default value, index.html should be assigned to the MainHTML key.

  2. AllowNetworkAccess (optional)
    If the widget requires network access, add a self closing tag <true /> under AllowNetworkAccess element. To deny network access, add a self closing tag <false /> under AllowNetworkAccess element. Leaving the element out of info.plist completely is the same as having set the element to false.

  3. Version (optional)
    This tag facilitates updating of the widget, allowing it to check if there is a newer version available. The version attribute in config.xml can be found in the <widget> element.

  4. Save the file.

[edit] 3. Find, Move and Rename the icon

You can find the icon file by following the path in config.xml:

<icon src="thumbnail.png"/>

Copy that image to the root of the widget folder. The icon must be in PNG format and named icon.png.

[edit] 4. Add Javascript Libraries (optional)

If the widget uses geolocation API, copy files Bondi.txt and Platformservices.txt to the root of the widget folder. Change the extensions from *.txt to *.js.

Add the following lines inside <head> element in main HTML file:

<script type="text/javascript" src="Bondi.js"></script>
<script type="text/javascript" src="Platformservices.js"></script>

If the widget does not use geolocation API, copy only Bondi.txt to the root of the widget folder and change the extension from *.txt to *.js.

Add the following line inside <head> element in main HTML file:

<script type="text/javascript" src="Bondi.js"></script>

[edit] 5. Rezip and rename

Use a packaging tool to create a *.zip file of the widget folder. The S60 Web Runtime requires that the widget contents are in a folder inside the zip file, not as files in the root of the zip. Rename the newly created *.zip into *.wgz

[edit] 6. Deploy

Upload the widget installation package (wgz) to your phone.

[edit] Examples

[edit] References

Note that Bondi references may require login credentials.

This page was last modified on 1 August 2012, at 08:25.
267 page views in the last 30 days.
×