Skip to content

Commit

Permalink
Update README.
Browse files Browse the repository at this point in the history
  • Loading branch information
Justin Tyberg committed Jan 18, 2011
1 parent bd6a355 commit 4ac192b
Showing 1 changed file with 72 additions and 59 deletions.
131 changes: 72 additions & 59 deletions README.md
View file
@@ -1,41 +1,38 @@
PhoneGap BlackBerry Widget
==========================
PhoneGap BlackBerry WebWorks
============================

[PhoneGap framework](http://www.phonegap.com/) for __BlackBerry OS 5.0 and 6.0__. The framework is implemented using the [BlackBerry Web Widget SDK](http://na.blackberry.com/eng/developers/browserdev/widgetsdk.jsp).
[PhoneGap framework](http://www.phonegap.com/) for __BlackBerry OS 5.0 and 6.0__. The framework is implemented using the [BlackBerry WebWorks SDK](http://us.blackberry.com/developers/browserdev/widgetsdk.jsp).

Directory Structure
-------------------

framework/ ... BlackBerry Widget Extension (PhoneGap native code)
framework/ ... BlackBerry WebWorks JavaScript Extension (PhoneGap native code)
js/ .......... PhoneGap JavaScript (Non-concatenated, non-minified)
template/ .... Project template for creating a new projects

Introduction
------------

The Blackberry Widget SDK provides a framework for developing hybrid applications for Blackberry devices that support Blackberry OS 5.0 and higher. In this framework, web applications consisting of web content, resources, and JavaScript can access device specific features through the exposed JavaScript [Blackberry Widget API](http://www.blackberry.com/developers/docs/widgetapi/).
BlackBerry WebWorks is a framework for developing hybrid applications for BlackBerry devices that support Blackberry OS 5.0 and higher. In this framework, web applications consisting of web content and resources (HTML/CSS/JavaScript) can make use of JavaScript APIs to access device features and capabilities.

The Blackberry Widget API is a subset of the [native Blackberry Java API](http://www.blackberry.com/developers/docs/6.0.0api/). A Widget application can make use of the native Java APIs by using JavaScript extensions. Doing so provides the Widget application access to device information and capabilities that the Widget API does not provide. It is therefore helpful to think of a Blackberry Widget application as having two parts:
The WebWorks framework exposes a subset of device capabilities through the [Blackberry WebWorks API](http://www.blackberry.com/developers/docs/widgetapi/). In addition, the framework allows applications to use JavaScript Extensions to extend the WebWorks API and access additional device capabilities. JavaScript Extensions are written in native Java, and expose their own JavaScript API through the WebWorks framework.

1. The Widget application, consisting of HTML, CSS, JavaScript, with access to the exposed Widget APIs.
2. The JavaScript extensions, or native Java code, with access to the full native Java APIs.

The phonegap-blackberry-widget project uses both the Blackberry Widget API and JavaScript extensions. This project will allow you to create your own Blackberry Widget applications that leverage the common PhoneGap API.
The phonegap-blackberry-webworks project allows web developers to develop applications targeting BlackBerry 5.0 and higher devices using the common [PhoneGap API](http://docs.phonegap.com). Under the covers, PhoneGap makes use of the WebWorks API, where possible. However, most PhoneGap features are implemented using a WebWorks JavaScript Extension.

Development Options
-------------------

There are two approaches to developing a PhoneGap BlackBerry Widget:
There are two approaches to developing a PhoneGap BlackBerry WebWorks:

1. Using the ANT command-line tool
- You do not need to install Eclipse
- You can use your favourite source code editor (even Eclipse)
- You can use your favorite source code editor
- Fast and easy to build and deploy applications
2. Eclipse environment
- Better for developing PhoneGap plugins and Widget extensions
- Better for developing PhoneGap plugins and WebWorks JavaScript Extensions

Running PhoneGap BlackBerry Widgets from the Command-line
=========================================================
Running PhoneGap BlackBerry WebWorks from the Command-line
==========================================================

Requirements
------------
Expand Down Expand Up @@ -69,68 +66,80 @@ Installing Apache ANT
Buildfile: build.xml does not exist!
Build failed

Installing PhoneGap-BlackBerry-Widget Framework
-----------------------------------------------
Installing phonegap-blackBerry-webworks Framework
-------------------------------------------------

Cloning the phonegap-blackberry-webworks repository always provides you with the latest (EDGE) version of the PhoneGap code. To clone the repository, do the following:

$ cd C:\some\path\
$ git clone git://github.com/phonegap/phonegap-blackberry-widget.git
$ cd phonegap-blackberry-widget
$ ant help
$ git clone git://github.com/phonegap/phonegap-blackberry-webworks.git

As an alternative, you can download packaged releases of PhoneGap from the [PhoneGap web site](http://phonegap.com). If choosing this method, simply unzip the PhoneGap packaged code and navigate to the BlackBerry directory. The steps below remain the same.

Creating a New PhoneGap Project
-------------------------------

Each project contains the PhoneGap framework and so the project is independent of the phonegap-blackberry-widget source code.
The PhoneGap build script enables you to create multiple, independent PhoneGap projects. The build script packages the PhoneGap source code and resources into each project you create. This allows you to easily distribute the project to other BlackBerry WebWorks developers. To create a PhoneGap project:

This allows you to easily distribute the project to other BlackBerry widget developers.

$ cd phonegap-blackberry-widget
$ cd phonegap-blackberry-webworks
$ ant help

$ ant create -Dproject.path="C:\development\my_new_project"

$ cd C:\development\my_new_project
$ ant help

For each project, you need to tell ANT where you have installed the BlackBerry Widget SDK. You can do this by editing __project.properties__ in the project directory.
For each project, you need to tell ANT where you installed the BlackBerry WebWorks SDK, which packages and compiles your code into a deployable application. You can specify the location of the BlackBerry WebWorks Packager (BBWP) by editing __project.properties__ in the project directory.

[edit project.properties]

Building and Deploying a Project
--------------------------------

PhoneGap provides scripts to automate common tasks, such as compiling your project, and deploying it to simulators or devices. To see what options are available, use:

$ cd C:\development\my_new_project
$ ant help

To build your project into a deployable application (.cod/.jad) file:

$ ant build

To build your project and load it in a BlackBerry simulator:

$ ant load-simulator

To build your project and load it onto a USB-attached device:

$ ant load-device

Updating the PhoneGap Framework
-------------------------------

$ cd phonegap-blackberry-widget
As you develop your application, there may be updates made to the PhoneGap source code. To incorporate PhoneGap changes into your project, use the build script as follows:

$ cd phonegap-blackberry-webworks
$ git pull origin master

$ ant update -Dproject.path="C:\development\my_new_project"

Debugging a Widget
------------------
Debugging a WebWorks Application
--------------------------------

The Eclipse BlackBerry Widget Plugin has some powerful debugging options, such as settings breakpoints in JavaScript. In order to use these features, you must import your source code into a BlackBerry Widget project.
The BlackBerry WebWorks Plugin for Eclipse has some powerful debugging options, such as settings breakpoints in JavaScript. In order to use these features, you must import your source code into a BlackBerry WebWorks project.

### Install Eclipse and the BlackBerry Widget Plugin
### Install Eclipse and the BlackBerry WebWorks Plugin for Eclipse

Follow in the installation instructions under the section __Running PhoneGap BlackBerry Widgets from Eclipse__.
Follow in the installation instructions under the section __Running PhoneGap BlackBerry WebWorks Applications from Eclipse__.

### Import your BlackBerry Widget Project into Eclipse
### Import your BlackBerry WebWorks Project into Eclipse

1. Create a BlackBerry Widget project:
1. Create a BlackBerry WebWorks/Widget project:
1. _File_ -> _New_ -> _BlackBerry Widget Project_
- Project Name: MyNewProject
- Start Page: index.html
2. Import the project:
1. In the project tree, right-click on the widget project (MyNewProject) and select _Import..._
2. Import the PhoneGap resources:
1. In the project tree, right-click on the project (MyNewProject) and select _Import..._
2. Select _General_ -> _Filesystem_
3. Select _Browse..._
4. Add the _www/_ directory of your project
Expand All @@ -139,13 +148,13 @@ Follow in the installation instructions under the section __Running PhoneGap Bla
6. Select _Finish_
7. Select _Yes_ to overwrite the existing index.html and config.xml

Running PhoneGap BlackBerry Widgets from Eclipse
================================================
Running PhoneGap BlackBerry WebWorks Applications from Eclipse
==============================================================

Overview
--------

It is best to setup two projects in Eclipse: a Java project for the Widget Extension native Java code, and a Blackberry Widget project for the web application code and resources.
It is best to setup two projects in Eclipse: a Java project for the WebWorks JavaScript Extension native Java code, and a Blackberry WebWorks project for the web application code and resources.

Requirements
------------
Expand All @@ -155,68 +164,72 @@ Requirements
3. [Eclipse 3.5+](http://www.eclipse.org/downloads/), the Classic Eclipse package is fine
4. [BlackBerry Web Plugin for Eclipse](http://na.blackberry.com/eng/developers/browserdev/eclipseplugin.jsp)

Installing PhoneGap-BlackBerry-Widget Framework
-----------------------------------------------
Installing the phonegap-blackberry-webworks Framework
-----------------------------------------------------

Cloning the phonegap-blackberry-webworks repository always provides you with the latest (EDGE) version of the PhoneGap code. To clone the repository, do the following:

$ cd C:\some\path\
$ git clone git://github.com/phonegap/phonegap-blackberry-widget.git
$ git clone git://github.com/phonegap/phonegap-blackberry-webworks.git

As an alternative, you can download packaged releases of PhoneGap from the [PhoneGap web site](http://phonegap.com). If choosing this method, simply unzip the PhoneGap packaged code and navigate to the BlackBerry directory. The steps below remain the same.

Installing the Eclipse BlackBerry Web Plugin
--------------------------------------------
Installing the BlackBerry WebWorks Plugin for Eclipse
-----------------------------------------------------

1. Open Eclipse
2. _Help_ -> _Install New Software..._ -> _Click Add..._
- Name: Blackberry Update - Web
- Location: http://www.blackberry.com/go/eclipseUpdate/3.5/web
3. Select __Blackberry Web Plugin__ and __Blackberry Widget SDK__
- Note: Even if the standalone Widget SDK is already installed on your system, you must install the Widget plugin to enable Blackberry Widget project capabilities within Eclipse.
- Note: Even if the standalone Widget SDK is already installed on your system, you must install the WebWorks plugin to enable Blackberry WebWorks capabilities within Eclipse.
4. Restart Eclipse

Create Eclipse Project for Extension Development
------------------------------------------------
Create BlackBerry Java Project for PhoneGap JavaScript Extension
----------------------------------------------------------------

1. Create a Java project
1. Create a BlackBerry Java project
1. _File_ -> _New_ -> _Project..._ -> _Java Project_
- Project Name: PhoneGapBlackberryExtension
- Do NOT use special characters or whitespace in Blackberry Widget project names, as the RAPC compiler will choke on them.
- Do NOT use special characters or whitespace in the project names, as the BlackBerry RAPC compiler will choke on them.
- _JRE_ -> _Use a project specific JRE: Blackberry JRE 5.0.0_
2. Import the phonegap extension code
2. Import the PhoneGap Java source code
1. Select the PhoneGapBlackberryExtension project
2. _File_ -> _Import_ -> _phonegap-blackberry-widget/framework/ext_
2. _File_ -> _Import_ -> _phonegap-blackberry-webworks/framework/ext_

Create a New Eclipse Widget Project
-----------------------------------
Create a New BlackBerry WebWorks Project
----------------------------------------

1. Create a BlackBerry Widget project
1. Create a BlackBerry WebWorks/Widget project
1. _File_ -> _New_ -> _BlackBerry Widget Project_
- Project Name: PhoneGapBlackberryWidget
- Start Page: index.html
2. Import the PhoneGap widget code
2. Import the PhoneGap web resources code
1. In the project tree, right-click on the widget project and select _Import..._
2. Select _General_ -> _Filesystem_
3. Import _phonegap-blackberry-widget/www_
3. Import _phonegap-blackberry-webworks/www_
4. Select _config.xml_ and _index.html_
5. Select _ext_ and _javascript_ folders
3. Change PhoneGap widget name
1. Open _config.xml_
2. Click _Overview_ tab
- Name: PhoneGap Widget
4. Build the widget
4. Build the project
1. Select the project, right-click and select _Build and Sign BlackBerry Widget Project_
5. Run the widget
5. Run the project
1. Select the project, right-click and select _Run_ -> _Run as_ -> _Blackberry Simulator_

Troubleshooting
---------------

__Q: I uploaded my application to the BlackBerry device, but it will not open or run.__

__A:__ Try hard resetting the device by pressing and hold ALT + CAPS LOCK + DEL. You must press and hold each key in sequence and not all at once.
__A:__ Try hard resetting the device by pressing and hold ALT + CAPS LOCK + DEL. You must press and hold each key in sequence and not all at once. Some devices require _either_ the right or left CAPS LOCK key to be pressed. Some devices also require this combination to be pressed twice.

__Q: My simulator screen is not refreshing and I see blocks on a clicked position.__

__A:__ Windows 7 and the simulator's graphics acceleration do not mix. On the simulator, set View -> Graphics Acceleration to Off.

__Q: When I use the PhoneGap [Camera.getPicture API](http://docs.phonegap.com/phonegap_camera_camera.md.html#camera.getPicture) on my device, the camera never returns to my application. Why does this happen?__

__A:__ PhoneGap uses a JavaScript extension to invoke the native camera application so the user can take a picture. When the picture is taken, PhoneGap will close the native camera application by emulating key injections (like pressing the back button). On a physical device, users will have to set permissions to allow your application to allow key injections to take place. Setting application permissions is device-specific. On a Storm2 (9550), for example, select the Blackberry button from the Home screen to get to All Applications screen, then Options > Applications > Your Application. Then select Edit Default Permissions > Interactions > Input Simulation and set it to 'Allow'. Save your changes.
__A:__ PhoneGap uses a JavaScript Extension to invoke the native camera application so the user can take a picture. When the picture is taken, PhoneGap will close the native camera application by emulating a key injection (pressing the back/escape button). On a physical device, users will have to set permissions to allow your application to simulate key injections. Setting application permissions is device-specific. On a Storm2 (9550), for example, select the BlackBerry button from the Home screen to get to All Applications screen, then Options > Applications > Your Application. Then select Edit Default Permissions > Interactions > Input Simulation and set it to 'Allow'. Save your changes.

0 comments on commit 4ac192b

Please sign in to comment.