PhoneGap framework for BlackBerry 5 and 6. It is built using the WebWorks SDK.
Java JavaScript
Clone or download
Pull request Compare This branch is 161 commits ahead of jtyberg:master.
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Failed to load latest commit information.

PhoneGap BlackBerry WebWorks

PhoneGap framework for BlackBerry Tablet OS. The framework is implemented using the BlackBerry WebWorks SDK.

Directory Structure

framework/ ... BlackBerry WebWorks JavaScript Extension (PhoneGap native code)
javascript/ .. PhoneGap JavaScript (Non-concatenated, non-minified)
lib/ ......... Third party tools
template/ .... Project template for creating a new projects


BlackBerry WebWorks is a framework for developing web-based applications for BlackBerry SmartPhones (BlackBerry OS 5.0 and higher) and the TabletOS. Creating a web application is one of the easiest ways to have an application that runs on both platforms.

The WebWorks framework allows developers to create applications using web content and resources (HTML/CSS/JavaScript) that are able to access device features through the Blackberry WebWorks API. In addition, the framework allows developers to create their own WebWorks JavaScript Extensions to expose additional device capabilities through JavaScript APIs. These extensions are written using either the BlackBerry Java API for SmartPhones, or Adobe AIR for the Tablet OS.

The phonegap-blackberry-webworks platform allows web developers to develop applications targeting BlackBerry 5.0 and higher devices using the common PhoneGap API. When possible, PhoneGap makes use of the WebWorks JavaScript API; however, most PhoneGap features are implemented in the native Java environment as a WebWorks JavaScript Extension.

Getting Started

Several guides are available on the PhoneGap Wiki to help you get started developing for the phonegap-blackberry-webworks platform. This guide will help you install and configure the BlackBerry WebWorks development environment, and the phonegap-blackberry-webworks platform. It will also step you through the process of creating a PhoneGap project.

Getting Started with PhoneGap BlackBerry WebWorks

This guide is for advanced developers who wish to develop their own phonegap-blackberry-webworks plugin.

How To Create a PhoneGap Plugin for PhoneGap BlackBerry WebWorks

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://

As an alternative, you can download packaged releases of PhoneGap from the PhoneGap web site. If choosing this method, simply unzip the PhoneGap packaged code and navigate to the BlackBerry/WebWorks directory. The steps below remain the same.

Creating a New PhoneGap Project

The PhoneGap build script enables you to create multiple, independent PhoneGap projects.

(Note: The PhoneGap build script requries Apache ANT 1.8 or higher. See the Getting Started guide for instructions on how to install and configure Apache ANT).

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:

$ 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 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 in the project directory.


Building and Deploying a Project

The PhoneGap build scripts 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

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"

Customizing PhoneGap

By default, PhoneGap gives access to all the core PhoneGap APIs as detailed at If you want to remove some of those APIs you can do so by editing the plugins.xml document in your application root. You need to edit the plugins.xml file to add third-party plugins to your application as well.

Creating a Distribution

Update Version

$ ant version -Dvalue="1.0.0"

$ git diff
$ git commit -am "Update to version 1.0.0"
$ git tag 1.0.0

Create distribution

$ ant dist


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. 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 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 a key injection (pressing the back/escape button). On a physical device, users will have to set permissions to allow the 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.

Q: None of the PhoneGap APIs are working, why is that?

A: You probably need to update your plugins.xml file in the root of your application.