README.md
author Ryan Willoughby <ryan.willoughby@nitobi.com>
Tue, 06 Jul 2010 11:31:19 -0700
changeset 0 54063d8b0412
permissions -rwxr-xr-x
initial commit of PhoneGap WRT framework, licensing and test code
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
0
54063d8b0412 initial commit of PhoneGap WRT framework, licensing and test code
Ryan Willoughby <ryan.willoughby@nitobi.com>
parents:
diff changeset
     1
PhoneGap Symbian (WRT)
54063d8b0412 initial commit of PhoneGap WRT framework, licensing and test code
Ryan Willoughby <ryan.willoughby@nitobi.com>
parents:
diff changeset
     2
=====================================================
54063d8b0412 initial commit of PhoneGap WRT framework, licensing and test code
Ryan Willoughby <ryan.willoughby@nitobi.com>
parents:
diff changeset
     3
PhoneGap Symbian.WRT is a skeleton application for Nokia's Web RunTime, along with javascript wrapper libraries, which allow a developer to build a native application for a WRT Supported Symbian phone using web technologies. The same set of web application files can be ported to PhoneGap BlackBerry, iPhone, Palm, and more to come...
54063d8b0412 initial commit of PhoneGap WRT framework, licensing and test code
Ryan Willoughby <ryan.willoughby@nitobi.com>
parents:
diff changeset
     4
54063d8b0412 initial commit of PhoneGap WRT framework, licensing and test code
Ryan Willoughby <ryan.willoughby@nitobi.com>
parents:
diff changeset
     5
54063d8b0412 initial commit of PhoneGap WRT framework, licensing and test code
Ryan Willoughby <ryan.willoughby@nitobi.com>
parents:
diff changeset
     6
Pre-requisites
54063d8b0412 initial commit of PhoneGap WRT framework, licensing and test code
Ryan Willoughby <ryan.willoughby@nitobi.com>
parents:
diff changeset
     7
-----------------------------------------------------
54063d8b0412 initial commit of PhoneGap WRT framework, licensing and test code
Ryan Willoughby <ryan.willoughby@nitobi.com>
parents:
diff changeset
     8
There are no real pre-requisites for PhoneGap Symbian.WRT development, as a WRT application consists simply of web files (html, css, js, etc) packaged and compressed into a .wgz file. No build process is necessary. However, for the purposes of development efficiency and testing, the following tools will make life MUCH easier:
54063d8b0412 initial commit of PhoneGap WRT framework, licensing and test code
Ryan Willoughby <ryan.willoughby@nitobi.com>
parents:
diff changeset
     9
 - Aptana Studio and Nokia's WRT Plugin for Aptana Studio. Includes a limited but very handy browser-based device simulator.
54063d8b0412 initial commit of PhoneGap WRT framework, licensing and test code
Ryan Willoughby <ryan.willoughby@nitobi.com>
parents:
diff changeset
    10
 - Optionally S60 5th Edition SDK, which includes the Symbian device emulator.
54063d8b0412 initial commit of PhoneGap WRT framework, licensing and test code
Ryan Willoughby <ryan.willoughby@nitobi.com>
parents:
diff changeset
    11
54063d8b0412 initial commit of PhoneGap WRT framework, licensing and test code
Ryan Willoughby <ryan.willoughby@nitobi.com>
parents:
diff changeset
    12
54063d8b0412 initial commit of PhoneGap WRT framework, licensing and test code
Ryan Willoughby <ryan.willoughby@nitobi.com>
parents:
diff changeset
    13
Set up your dev environment
54063d8b0412 initial commit of PhoneGap WRT framework, licensing and test code
Ryan Willoughby <ryan.willoughby@nitobi.com>
parents:
diff changeset
    14
---------------------------
54063d8b0412 initial commit of PhoneGap WRT framework, licensing and test code
Ryan Willoughby <ryan.willoughby@nitobi.com>
parents:
diff changeset
    15
1. Place your web application in the phonegap_root/symbian.wrt/framework/www folder
54063d8b0412 initial commit of PhoneGap WRT framework, licensing and test code
Ryan Willoughby <ryan.willoughby@nitobi.com>
parents:
diff changeset
    16
2. Ensure phonegap.js is included in your main html page
54063d8b0412 initial commit of PhoneGap WRT framework, licensing and test code
Ryan Willoughby <ryan.willoughby@nitobi.com>
parents:
diff changeset
    17
3. Place your application icon in the www folder. It should be named Icon.png
54063d8b0412 initial commit of PhoneGap WRT framework, licensing and test code
Ryan Willoughby <ryan.willoughby@nitobi.com>
parents:
diff changeset
    18
4. Modify info.plist (use the existing sample as a guide)
54063d8b0412 initial commit of PhoneGap WRT framework, licensing and test code
Ryan Willoughby <ryan.willoughby@nitobi.com>
parents:
diff changeset
    19
5. Develop your application around this html file ... only this page will have access to the device api
54063d8b0412 initial commit of PhoneGap WRT framework, licensing and test code
Ryan Willoughby <ryan.willoughby@nitobi.com>
parents:
diff changeset
    20
6. Compress the www folder into a zip file, and change the .zip extension to .wgz *
54063d8b0412 initial commit of PhoneGap WRT framework, licensing and test code
Ryan Willoughby <ryan.willoughby@nitobi.com>
parents:
diff changeset
    21
7. Transfer this file to your S60 5th Edition device, and open it. The device should recognize and install the application
54063d8b0412 initial commit of PhoneGap WRT framework, licensing and test code
Ryan Willoughby <ryan.willoughby@nitobi.com>
parents:
diff changeset
    22
54063d8b0412 initial commit of PhoneGap WRT framework, licensing and test code
Ryan Willoughby <ryan.willoughby@nitobi.com>
parents:
diff changeset
    23
Make targets:
54063d8b0412 initial commit of PhoneGap WRT framework, licensing and test code
Ryan Willoughby <ryan.willoughby@nitobi.com>
parents:
diff changeset
    24
  - make js (compile the javascript source into lib/phonegap.js)
54063d8b0412 initial commit of PhoneGap WRT framework, licensing and test code
Ryan Willoughby <ryan.willoughby@nitobi.com>
parents:
diff changeset
    25
  - make package (package the contents of framework/www/ into a .wgz package file, installable to the device)
54063d8b0412 initial commit of PhoneGap WRT framework, licensing and test code
Ryan Willoughby <ryan.willoughby@nitobi.com>
parents:
diff changeset
    26
 
54063d8b0412 initial commit of PhoneGap WRT framework, licensing and test code
Ryan Willoughby <ryan.willoughby@nitobi.com>
parents:
diff changeset
    27
As you can see, you don't need to have any particular tools installed in your development environment to build WRT applications, as there is no building or compiling involved. However there are tools you can use to make development easier. The combination of Aptana Studio and Nokia's WRT Plug-in for Aptana worked nicely for developing and testing WRT applications. It includes an emulator (only for PC) and a browser-based javascript emulator, and can deploy applications directly to your device if bluetooth is enabled.
54063d8b0412 initial commit of PhoneGap WRT framework, licensing and test code
Ryan Willoughby <ryan.willoughby@nitobi.com>
parents:
diff changeset
    28
 
54063d8b0412 initial commit of PhoneGap WRT framework, licensing and test code
Ryan Willoughby <ryan.willoughby@nitobi.com>
parents:
diff changeset
    29
A sample application resides in available at http://github.com/wildabeast/phonegap-demo which demonstrates the use of various device features through the phonegap API. It is essentially just a local website with a couple of rules: you must have an info.plist file and a main html page. To deploy this to your S60 5th Ed. device:
54063d8b0412 initial commit of PhoneGap WRT framework, licensing and test code
Ryan Willoughby <ryan.willoughby@nitobi.com>
parents:
diff changeset
    30
 
54063d8b0412 initial commit of PhoneGap WRT framework, licensing and test code
Ryan Willoughby <ryan.willoughby@nitobi.com>
parents:
diff changeset
    31
1. Add the info.plist file to the application folder.
54063d8b0412 initial commit of PhoneGap WRT framework, licensing and test code
Ryan Willoughby <ryan.willoughby@nitobi.com>
parents:
diff changeset
    32
2. Compress the application folder into a zip file.
54063d8b0412 initial commit of PhoneGap WRT framework, licensing and test code
Ryan Willoughby <ryan.willoughby@nitobi.com>
parents:
diff changeset
    33
2. Change the .zip extension to .wgz.
54063d8b0412 initial commit of PhoneGap WRT framework, licensing and test code
Ryan Willoughby <ryan.willoughby@nitobi.com>
parents:
diff changeset
    34
3. Transfer the file to your phone, via bluetooth, downloading from the web, or from email, etc.
54063d8b0412 initial commit of PhoneGap WRT framework, licensing and test code
Ryan Willoughby <ryan.willoughby@nitobi.com>
parents:
diff changeset
    35
4. When you receive the message, your device should recognize the file type and install the application. 
54063d8b0412 initial commit of PhoneGap WRT framework, licensing and test code
Ryan Willoughby <ryan.willoughby@nitobi.com>
parents:
diff changeset
    36
 
54063d8b0412 initial commit of PhoneGap WRT framework, licensing and test code
Ryan Willoughby <ryan.willoughby@nitobi.com>
parents:
diff changeset
    37
Note: a limitation of WRT is that you must define one main html page (defined in info.plist), and this page is the only one which will have access to the device functionality (geolocation, vibration, etc.). You can still use multiple pages, and pages not accessing device functionality will be accessible, but we recommend instead swapping views in and out of the main html page using a local xmlhttprequest, or building a javascript application (swapping views by showing and hiding divs).
54063d8b0412 initial commit of PhoneGap WRT framework, licensing and test code
Ryan Willoughby <ryan.willoughby@nitobi.com>
parents:
diff changeset
    38
54063d8b0412 initial commit of PhoneGap WRT framework, licensing and test code
Ryan Willoughby <ryan.willoughby@nitobi.com>
parents:
diff changeset
    39
54063d8b0412 initial commit of PhoneGap WRT framework, licensing and test code
Ryan Willoughby <ryan.willoughby@nitobi.com>
parents:
diff changeset
    40
Debugging your Symbian.WRT PhoneGap application
54063d8b0412 initial commit of PhoneGap WRT framework, licensing and test code
Ryan Willoughby <ryan.willoughby@nitobi.com>
parents:
diff changeset
    41
-----------------------------------------------
54063d8b0412 initial commit of PhoneGap WRT framework, licensing and test code
Ryan Willoughby <ryan.willoughby@nitobi.com>
parents:
diff changeset
    42
Creating your PhoneGap Nokia project in Aptana Studio's WRT Plugin allows you to simulate the on device behaviour of your application in a browser.
54063d8b0412 initial commit of PhoneGap WRT framework, licensing and test code
Ryan Willoughby <ryan.willoughby@nitobi.com>
parents:
diff changeset
    43
 
54063d8b0412 initial commit of PhoneGap WRT framework, licensing and test code
Ryan Willoughby <ryan.willoughby@nitobi.com>
parents:
diff changeset
    44
Get the Aptana WRT Plugin here.
54063d8b0412 initial commit of PhoneGap WRT framework, licensing and test code
Ryan Willoughby <ryan.willoughby@nitobi.com>
parents:
diff changeset
    45
The simulator requires Firefox and Firebug.
54063d8b0412 initial commit of PhoneGap WRT framework, licensing and test code
Ryan Willoughby <ryan.willoughby@nitobi.com>
parents:
diff changeset
    46
 
54063d8b0412 initial commit of PhoneGap WRT framework, licensing and test code
Ryan Willoughby <ryan.willoughby@nitobi.com>
parents:
diff changeset
    47
1. Install Aptana Studio and the Nokia WRT plug-in.
54063d8b0412 initial commit of PhoneGap WRT framework, licensing and test code
Ryan Willoughby <ryan.willoughby@nitobi.com>
parents:
diff changeset
    48
2. Go to File -> New -> Project. Select Nokia Web Runtime -> New Nokia Web Runtime Widget.
54063d8b0412 initial commit of PhoneGap WRT framework, licensing and test code
Ryan Willoughby <ryan.willoughby@nitobi.com>
parents:
diff changeset
    49
3. Select your desired project name and file locations. Click Finish. You should now see some additional internal application files/folders.
54063d8b0412 initial commit of PhoneGap WRT framework, licensing and test code
Ryan Willoughby <ryan.willoughby@nitobi.com>
parents:
diff changeset
    50
4. Copy your web application pages into the project folder (unless starting from scratch).
54063d8b0412 initial commit of PhoneGap WRT framework, licensing and test code
Ryan Willoughby <ryan.willoughby@nitobi.com>
parents:
diff changeset
    51
5. Ensure that the MainHTML property in info.plist refers to your application starting page.
54063d8b0412 initial commit of PhoneGap WRT framework, licensing and test code
Ryan Willoughby <ryan.willoughby@nitobi.com>
parents:
diff changeset
    52
6. Right click on the file "wrt_preview_frame.html", and select Debug As -> Javascript Web Application.
54063d8b0412 initial commit of PhoneGap WRT framework, licensing and test code
Ryan Willoughby <ryan.willoughby@nitobi.com>
parents:
diff changeset
    53
 
54063d8b0412 initial commit of PhoneGap WRT framework, licensing and test code
Ryan Willoughby <ryan.willoughby@nitobi.com>
parents:
diff changeset
    54
Your application should run inside Firefox, with the phonegap API functioning and returning test data for geolocation, contacts, acceleration, etc.
54063d8b0412 initial commit of PhoneGap WRT framework, licensing and test code
Ryan Willoughby <ryan.willoughby@nitobi.com>
parents:
diff changeset
    55
54063d8b0412 initial commit of PhoneGap WRT framework, licensing and test code
Ryan Willoughby <ryan.willoughby@nitobi.com>
parents:
diff changeset
    56
Notes
54063d8b0412 initial commit of PhoneGap WRT framework, licensing and test code
Ryan Willoughby <ryan.willoughby@nitobi.com>
parents:
diff changeset
    57
------------------------------------------------------
54063d8b0412 initial commit of PhoneGap WRT framework, licensing and test code
Ryan Willoughby <ryan.willoughby@nitobi.com>
parents:
diff changeset
    58
 - The memory available to WRT apps is very limited. Loading large javascript files into memory, playing sound files, and excessive monitoring of sensors can fairly easily crash your application. Minify js files, and use sensor monitoring (accel, gps, etc) conservatively.
54063d8b0412 initial commit of PhoneGap WRT framework, licensing and test code
Ryan Willoughby <ryan.willoughby@nitobi.com>
parents:
diff changeset
    59
 - If your symbian phone has contacts synced via PC Suite or Ovi Sync, and you attempt to query the contacts api, your app will crash. This is discussed here: http://discussion.forum.nokia.com/forum/showthread.php?t=170839&highlight=contacts+api+crashing. Hopefully nokia will fix it soon.
54063d8b0412 initial commit of PhoneGap WRT framework, licensing and test code
Ryan Willoughby <ryan.willoughby@nitobi.com>
parents:
diff changeset
    60
 - Javascript animation in WRT is not great. I've tried dojo, scriptaculous, & emile, to no avail. You can leave it in ... your app will reach the animation end state ... but the animation itself won't be pretty.
54063d8b0412 initial commit of PhoneGap WRT framework, licensing and test code
Ryan Willoughby <ryan.willoughby@nitobi.com>
parents:
diff changeset
    61
54063d8b0412 initial commit of PhoneGap WRT framework, licensing and test code
Ryan Willoughby <ryan.willoughby@nitobi.com>
parents:
diff changeset
    62
Helpful Links
54063d8b0412 initial commit of PhoneGap WRT framework, licensing and test code
Ryan Willoughby <ryan.willoughby@nitobi.com>
parents:
diff changeset
    63
-----------------------------------------------------
54063d8b0412 initial commit of PhoneGap WRT framework, licensing and test code
Ryan Willoughby <ryan.willoughby@nitobi.com>
parents:
diff changeset
    64
  - PhoneGap API Docs: 			docs.phonegap.com
54063d8b0412 initial commit of PhoneGap WRT framework, licensing and test code
Ryan Willoughby <ryan.willoughby@nitobi.com>
parents:
diff changeset
    65
  - PhoneGap Wiki: 				phonegap.pbworks.com
54063d8b0412 initial commit of PhoneGap WRT framework, licensing and test code
Ryan Willoughby <ryan.willoughby@nitobi.com>
parents:
diff changeset
    66
  - Nokia Web Runtime: 			http://www.forum.nokia.com/Technology_Topics/Web_Technologies/Web_Runtime/