Introduction
This document is intended to help the developer create a PhoneGap plugin for the callback-blackberry platform. Applications created using this platform will run on BlackBerry smartphone devices that support BlackBerry OS 5.0 and higher.
How WebWorks SDK for BlackBerry SmartPhones Works
BlackBerry WebWorks is a framework for developing hybrid applications for BlackBerry devices. Using this framework, web applications can access device capabilities through JavaScript APIs. RIM provides the BlackBerry WebWorks API as part of the WebWorks SDK for BlackBerry smartphones. Developers can extend the WebWorks API to access additional device features using WebWorks JavaScript Extensions. Here is what the WebWorks stack looks like conceptually:
The WebWorks framework is built on top of RIM's Java runtime, or Java Development Environment. It uses hooks into the browser engine to expose JavaScripts APIs to web application developers. When a web developer invokes one of the JavaScript APIs, whether they are part of the core WebWorks API, or provided by a JavaScript Extension, it is the underlying Java code that does the work.
PhoneGap provides a JavaScript API of its own, with the intent of having a common API across mobile device platforms. Where feasible, PhoneGap for BlackBerry WebWorks utilizes the core WebWorks JavaScript API; however, most of the functionality that PhoneGap provides is implemented using a JavaScript Extension. When web developers invoke the PhoneGap API, it will either invoke the WebWorks API or the PhoneGap Extension API under the covers.
Now that we know how WebWorks works, let's talk about PhoneGap Plugins.
PhoneGap Plugins
The PhoneGap JavaScript Extension is written in Java. The core PhoneGap library contains a set of Plugins, each of which performs one or more actions. For example, the Camera plugin has an action called getPicture. As a web developer, you might invoke this action as follows:
function capturePhoto() {
navigator.camera.getPicture(onCapturePhotoSuccess, onCapturePhotoFail);
}
Under the covers, the PhoneGap JavaScript library invokes the PhoneGap plugin manager, like this:
Camera.prototype.getPicture = function(successCallback, errorCallback, options) {
this.options = options;
var quality = 80;
if (options.quality) {
quality = this.options.quality;
}
var destinationType = Camera.DestinationType.DATA_URL;
if (this.options.destinationType) {
destinationType = this.options.destinationType;
}
var sourceType = Camera.PictureSourceType.CAMERA;
if (typeof this.options.sourceType == "number") {
sourceType = this.options.sourceType;
}
PhoneGap.exec(successCallback, errorCallback, "Camera", "getPicture", [quality, destinationType, sourceType]);
};
The interesting line of code is invoking PhoneGap.exec. Under the covers, the PhoneGap plugin manager looks up a plugin with the name of 'Camera', instantiates its Java class (plugins are lazy loaded), and invokes its 'getPicture' action. This process illustrates the two things that the PhoneGap plugin manager needs:
- A name (e.g. 'Camera').
- A Java class to instantiate. The plugins class(es) must be packaged with the WebWorks application so they can be loaded when the plugin is invoked.
In addition, the PhoneGap JavaScript library provides the JavaScript API (e.g., Camera.prototype.getPicture) that invokes the plugin manager with the correct parameters.
For the plugins included in the core PhoneGap library, developers need not worry about any of these details. All the Java classes are included, the plugin names are registered, and the JavaScript API are written for you. However, the plugin developer must do the following:
- Write the native Java plugin code.
- Write the JavaScript API to register your Java plugin with the PhoneGap plugin manager, and to invoke your plugin.
- Package the Java class file(s) with the WebWorks application.
In this tutorial, we'll take you through each step in this process.
Requirements
Before you can get started, you'll need the following:
- Apache Ant, to facilitate building and packaging the WebWorks application.
- BlackBerry WebWorks Packager, which compiles and packages WebWorks applications into deployable COD/JAD files.
- PhoneGap >= 0.9.4. Important: The ability to register plugins in PhoneGap BlackBerry WebWorks was not added until version 0.9.4.
- Familiarity with Java and JavaScript.
For details on obtaining and installing these pre-requisites, see the Getting Started guide.
Create a Plugin
This section will lead the developer through the exercise of creating a plugin for the PhoneGap BlackBerry WebWorks framework only. Although some steps in the process may be similar to developing plugins for other mobile platforms that PhoneGap supports, plugins created using the following procedure can only be used for phonegap-blackberry-webworks applications.
Create the Plugin Source Code
The easiest way to start writing a PhoneGap BlackBerry WebWorks plugin is to use the build scripts provided with the phonegap-blackberry-webworks project. Whether you download the latest PhoneGap distribution, or fork the project from github, you will want to navigate to the top-level directory, the contents of which will look something like this:
Directory of C:\Dev\phonegap-blackberry-webworks
02/04/2011 04:51 PM <DIR> .
02/04/2011 04:51 PM <DIR> ..
02/02/2011 07:01 PM 8,834 build.xml
02/04/2011 04:51 PM <DIR> framework
02/04/2011 04:51 PM <DIR> javascript
02/04/2011 04:51 PM <DIR> lib
01/18/2011 07:15 AM 3,494 LICENSE
01/18/2011 08:56 AM 11,976 README.md
02/04/2011 04:51 PM <DIR> template
02/02/2011 07:01 PM 6 VERSION
For this tutorial, we'll assume the directory is C:\Dev\phonegap-blackberry-webworks.
- Open a Windows command window (Start > then type 'cmd').
- Change to the C:\Dev\phonegap-blackberry-webworks directory:
C:\>cd Dev\phonegap-blackberry-webworks
- Run the ant create-plugin task. This will create a full plugin directory structure, complete with a plugin example.
C:\Dev\phonegap-blackberry-webworks>ant create-plugin -Dplugin.path=C:\Dev\phonegap-blackberry-webworks\plugins
You must specify a directory into which the plugin will be placed. In this case, we simply put it in the plugins sub-directory to the directory we are in. If the directory does not exist, the task will create it. You should see output similar to:
Buildfile: C:\Dev\phonegap-blackberry-webworks\build.xml
create-plugin:
[mkdir] Created dir: C:\Dev\phonegap-blackberry-webworks\plugins
[copy] Copying 5 files to C:\Dev\phonegap-blackberry-webworks\plugins
[echo]
[echo] Plugin Creation Complete!
[echo] =========================
[echo]
[echo] Getting Started:
[echo] ----------------
[echo]
[echo] cd C:\Dev\phonegap-blackberry-webworks\plugins
[echo]
[echo] ant help
[echo]
BUILD SUCCESSFUL
Total time: 0 seconds
- Now let's take a look at the plugin directory structure:
C:\Dev\phonegap-blackberry-webworks>cd plugins
C:\Dev\phonegap-blackberry-webworks\plugins>dir
Volume in drive C has no label.
Volume Serial Number is B05A-EDB5
Directory of C:\Dev\phonegap-blackberry-webworks\plugins
02/04/2011 05:04 PM <DIR> .
02/04/2011 05:04 PM <DIR> ..
02/04/2011 05:04 PM 2,356 build.xml
02/04/2011 05:04 PM 282 plugin.properties
02/04/2011 05:04 PM <DIR> src
02/04/2011 05:04 PM <DIR> www
- The first thing you'll want to do is pick a name for your plugin. My advice: don't be cute or clever with the name, and try to keep it as generic as possible. For example, if you're creating a plugin to handle barcodes, would it be better to name it 'Barcode' or 'BarcodeScanner'. Well, since you can do more than just scan barcodes (you can encode them as well), perhaps simply 'Barcode' would be the better name. You may start out with just scanning, but who knows, maybe you'll get around to the encoding part later.
Anyway, once you've chosen a name, edit the plugin.properties file in the plugin directory:
plugin.name=Battery
In our example, we're going to create a Battery plugin.
- Now we're ready to look at some source code. If you navigate to the src\com\phonegap\plugins directory, you'll find a sample plugin Java class.
C:\Dev\phonegap-blackberry-webworks\plugins>cd src\com\phonegap\plugins
C:\Dev\phonegap-blackberry-webworks\plugins\src\com\phonegap\plugins>dir
Volume in drive C has no label.
Volume Serial Number is B05A-EDB5
Directory of C:\Dev\phonegap-blackberry-webworks\plugins\src\com\phonegap\plugins
02/04/2011 05:04 PM <DIR> .
02/04/2011 05:04 PM <DIR> ..
02/04/2011 05:04 PM 933 Example.java
02/04/2011 05:04 PM 802 ExampleAction.java
Let's rename the Example.java file to Battery.java. We're going to turn this thing into our own plugin.
C:\Dev\phonegap-blackberry-webworks\plugins\src\com\phonegap\plugins>rename Example.java Battery.java
- Open Battery.java with your favorite editor. Note: You can also use Eclipse, or another IDE, but for the sake of keeping our example simpler, we're sticking with a plain editor.
The contents of Battery.java should be as follows:
package com.phonegap.plugins;
import com.phonegap.api.Plugin;
import com.phonegap.api.PluginResult;
import com.phonegap.json4j.JSONArray;
public class Example extends Plugin {
/**
* Executes the requested action and returns a PluginResult.
*
* @param action The action to execute.
* @param callbackId The callback ID to be invoked upon action completion.
* @param args JSONArry of arguments for the action.
* @return A PluginResult object with a status and message.
*/
public PluginResult execute(String action, JSONArray args, String callbackId) {
return ExampleAction.execute(args);
}
/**
* Called when Plugin is paused.
*/
public void onPause() {
}
/**
* Called when Plugin is resumed.
*/
public void onResume() {
}
/**
* Called when Plugin is destroyed.
*/
public void onDestroy() {
}
}
- Let's focus on the first few lines of the file. Just the package declaration and some imports. Pretty boring stuff. But we'll want to change the class name to Battery to match the filename.
package com.phonegap.plugins;
import com.phonegap.api.Plugin;
import com.phonegap.api.PluginResult;
import com.phonegap.json4j.JSONArray;
public class Battery extends Plugin {
Note the plugin class MUST either extend com.phonegap.api.Plugin, or implement the com.phonegap.api.IPlugin interface. The difference is that the abstract Plugin class contains default implementations of some of the IPlugin interface methods. Of the two options, it is recommended that you extend Plugin.
Important: Note that the default Plugin behavior is to run asynchronously, on a separate Java thread. This is the best practice. You should always strive to handle the plugin operations OFF the application event thread, and allow the JavaScript engine to go about it's business. However, if you have an impossibly simple action that can be performed quickly, and you would like the have your plugin called synchronously, you can override the Plugin.isSynch method:
/**
* Identifies if action to be executed returns a value and should be run synchronously.
* @param action The action to execute
* @return T=returns value
*/
public boolean isSynch(String action) {
return false; // recommended
}
- Now we need to decide what actions our Battery plugin will perform. An obvious one might be to retrieve the battery level. So let's define an action:
import com.phonegap.json4j.JSONArray;
public class Battery extends Plugin {
public static final String GET_LEVEL = "getLevel";
- Now we focus on the meat and potatoes, the execute method:
/**
* Executes the requested action and returns a PluginResult.
*
* @param action The action to execute.
* @param callbackId The callback ID to be invoked upon action completion.
* @param args JSONArray of arguments for the action.
* @return A PluginResult object with a status and message.
*/
public PluginResult execute(String action, JSONArray args, String callbackId) {
return ExampleAction.execute(args);
}
This method is invoked by the PhoneGap plugin manager whenever the Battery plugin is invoked on the JavaScript side. The first parameter is action, which tells the plugin what action to perform. The second parameter, args, is a JSONArray that contains the arguments for the specified action. The third parameter is the JavaScript callbackId. The PhoneGap plugin manager maintains the callbacks for each plugin and, unless the plugin specifies otherwise, the plugin manager will invoke the callback on behalf of the plugin.
Finally, the return value is a PluginResult. It must contain a PluginResult.Status, and can optionally return a JSON formatted result.
- Modify the execute method such that it retrieves the battery level from the system, and returns it in the PluginResult.
public PluginResult execute(String action, JSONArray args, String callbackId) {
PluginResult result = null;
if (GET_LEVEL.equals(action)) {
// retrieve the device battery level and return it in the plugin result
int level = net.rim.device.api.system.DeviceInfo.getBatteryLevel();
result = new PluginResult(PluginResult.Status.OK, level);
}
else {
result = new PluginResult(PluginResult.Status.INVALIDACTION,
"Battery: Invalid action: " + action);
}
return result;
}
- Well, that was easy. The full source should now look like this:
package com.phonegap.plugins;
import com.phonegap.api.Plugin;
import com.phonegap.api.PluginResult;
import com.phonegap.json4j.JSONArray;
public class Battery extends Plugin {
public static final String GET_LEVEL = "getLevel";
/**
* Executes the requested action and returns a PluginResult.
*
* @param action The action to execute.
* @param callbackId The callback ID to be invoked upon action completion.
* @param args JSONArry of arguments for the action.
* @return A PluginResult object with a status and message.
*/
public PluginResult execute(String action, JSONArray args, String callbackId) {
PluginResult result = null;
if (GET_LEVEL.equals(action)) {
// retrieve the device battery level
int level = net.rim.device.api.system.DeviceInfo.getBatteryLevel();
result = new PluginResult(PluginResult.Status.OK, level);
}
else {
result = new PluginResult(PluginResult.Status.INVALIDACTION,
"Battery: Invalid action: " + action);
}
return result;
}
/**
* Called when Plugin is paused.
*/
public void onPause() {
}
/**
* Called when Plugin is resumed.
*/
public void onResume() {
}
/**
* Called when Plugin is destroyed.
*/
public void onDestroy() {
}
}
Provide the JavaScript API
At this point, the native Java code should be complete. Now we focus on the JavaScript side.
If you navigate to the root of the plugins directory, you should see a 'www\javascript' directory. In that directory is a sample JavaScript implementation that we'll modify.
- Navigate to the plugin sample JavaScript directory:
C:\Dev\phonegap-blackberry-webworks\plugins>cd C:\Dev\phonegap-blackberry-webworks\plugins
C:\Dev\phonegap-blackberry-webworks\plugins>cd www\javascript
C:\Dev\phonegap-blackberry-webworks\plugins\www\javascript>dir
Volume in drive C has no label.
Volume Serial Number is B05A-EDB5
Directory of C:\Dev\phonegap-blackberry-webworks\plugins\www\javascript
02/04/2011 05:04 PM <DIR> .
02/04/2011 05:04 PM <DIR> ..
02/04/2011 05:04 PM 906 example.js
- Rename the example.js file to battery.js:
C:\Dev\phonegap-blackberry-webworks\plugins\www\javascript>rename example.js battery.js
- Now take a look at the file:
(function() {
var Example = function() {
return {
echo: function(message, successCallback, errorCallback) {
PhoneGap.exec(successCallback, errorCallback, 'Example', 'echo', [ message ]);
}
}
};
})();
Some pretty fancy stuff (I come from a background in Java, not JavaScript).
There are two sections: the top section contains a function definition that invokes the PhoneGap plugin manager, while the bottom section actually registers the plugin with the plugin manager.
- First, we define a Battery object literal, which contains a function called level. The level function simply invokes the Battery plugin through the PhoneGap plugin manager:
var Battery = {
level: function(successCallback, errorCallback) {
PhoneGap.exec(successCallback, errorCallback, 'Battery', 'getLevel',[]);
}
};
'Battery' is the name of the plugin, and 'getLevel' is the name of the action to perform.
Package the Plugin Source Code
There were differences introduced since BlackBerry WebWorks SDK 1.5.1 was released that causes PhoneGap plugins packaged as .jar files to no longer be recognized inside your WebWorks application. Please make sure you package and include your plugin code properly according to the proper version of the WebWorks SDK you are using.
Using BlackBerry WebWorks SDK 1.5.0 and below
Now that the source code is complete for our Battery plugin, we need to package it up for inclusion in our WebWorks application. The way that the plugin is packaged is determined solely by the requirements of the BlackBerry WebWorks Packager (BBWP). BBWP does not support a JAR file containing compiled Java classes (byte code). It requires the source code!
To make things easier for those who might have trouble wrapping their minds around this peculiar behavior, we created a way to allow you to easily package your plugin source code into a format that BBWP would accept. Just go back to the root plugin directory, and run ant build.
C:\Dev\phonegap-blackberry-webworks\plugins\www\javascript>cd C:\Dev\phonegap-blackberry-webworks\plugins
C:\Dev\phonegap-blackberry-webworks\plugins>ant build
Buildfile: C:\Dev\phonegap-blackberry-webworks\plugins\build.xml
clean:
[delete] Deleting directory C:\Dev\phonegap-blackberry-webworks\plugins\build
build:
[mkdir] Created dir: C:\Dev\phonegap-blackberry-webworks\plugins\build
[mkdir] Created dir: C:\Dev\phonegap-blackberry-webworks\plugins\build\www\ext
[zip] Building zip: C:\Dev\phonegap-blackberry-webworks\plugins\build\www\ext\Battery.jar
[copy] Copying 1 file to C:\Dev\phonegap-blackberry-webworks\plugins\build\www
[echo]
[echo] Plugin Package Complete!
[echo] ========================
[echo]
[echo] Where:
[echo] ------
[echo]
[echo] ./build/www
[echo] ./build/www/ext
[echo]
[echo] Installation:
[echo] -------------
[echo]
[echo] 1. If you have a project at /my_project/
[echo]
[echo] 2. Install the native extension:
[echo]
[echo] - copy ./build/www/ext/Battery.jar to /my_project/www/ext/
[echo]
[echo] 3. Install the Web assets:
[echo]
[echo] - copy ./build/www to /my_project/www
[echo]
BUILD SUCCESSFUL
Total time: 0 seconds
The build script creates a JAR file containing the Java source code, and puts this JAR file and the JavaScript file in a directory structure that mimics a WebWorks application. You will need to copy these files into your application directory. We'll cover that in the next section.
Using BlackBerry WebWorks SDK 1.5.1 and above
Inclusion of .jar files in a WebWorks application from 1.5.1 and above no longer works as before. For some reason, WebWorks applications built with the newer version no longer recognize arbitrary .jars. As such, instead of compiling the plugin source code into a .jar and including it into the ext/ folder of our application, we will directly include the native code for our plugin into the phonegap-blackberry-webworks project code. Further instructions are below - just make sure to follow the directions for the proper SDK version you are using!
Test the Plugin
Our PhoneGap plugin should be ready for use. Now all we need is to test it out. We'll do that by creating a sample phonegap project.
Create a PhoneGap Project
IF YOU ARE USING BLACKBERRY WEBWORKS SDK 1.5.1 AND ABOVE: Before creating a project as per instructions below, copy the Battery.java file into the framework/ext/src/com/phonegap/plugins directory, which is inside the phonegap-blackberry-webworks project (you may have to create the plugins directory). In the newer SDK version, we can no longer include arbitrary .jar files in our WebWorks applications, as such we include the plugin code as part of the base PhoneGap framework.
Navigate to the root phonegap-blackberry-webworks directory, and create a new PhoneGap project. We'll call it BatteryTest.
C:\Dev\phonegap-blackberry-webworks>cd C:\Dev\phonegap-blackberry-webworks
C:\Dev\phonegap-blackberry-webworks>ant create -Dproject.path=C:\Dev\phonegap-blackberry-webworks\BatteryTest
Buildfile: C:\Dev\phonegap-blackberry-webworks\build.xml
clean:
[delete] Deleting directory C:\Dev\phonegap-blackberry-webworks\build
build-javascript:
[mkdir] Created dir: C:\Dev\phonegap-blackberry-webworks\build\javascript
[delete] Deleting: C:\Dev\phonegap-blackberry-webworks\build\javascript\phonegap.0.9.4.min.js.tmp
build-extension:
[mkdir] Created dir: C:\Dev\phonegap-blackberry-webworks\build\ext
[zip] Building zip: C:\Dev\phonegap-blackberry-webworks\build\ext\phonegap.0.9.4.jar
create:
[mkdir] Created dir: C:\Dev\phonegap-blackberry-webworks\BatteryTest
[copy] Copying 10 files to C:\Dev\phonegap-blackberry-webworks\BatteryTest
[copy] Copying 2 files to C:\Dev\phonegap-blackberry-webworks\BatteryTest\www\javascript
[copy] Copying 1 file to C:\Dev\phonegap-blackberry-webworks\BatteryTest\www\ext
[mkdir] Created dir: C:\Dev\phonegap-blackberry-webworks\BatteryTest\lib\phonegap.0.9.4
[copy] Copying 3 files to C:\Dev\phonegap-blackberry-webworks\BatteryTest\lib\phonegap.0.9.4
[echo]
[echo] Project Creation Complete!
[echo] ==========================
[echo]
[echo] Getting Started:
[echo] ----------------
[echo]
[echo] cd C:\Dev\phonegap-blackberry-webworks\BatteryTest
[echo]
[echo] ant help
[echo]
BUILD SUCCESSFUL
Total time: 2 seconds
Copy the Plugin Files to Project Directory
You'll need to copy the JavaScript source file (and, if you are using WebWorks 1.5.0 and below, the .jar file) into the BatteryTest project.
ONLY IF YOU ARE USING WEBWORKS SDK 1.5.0 and below: C:\Dev\phonegap-blackberry-webworks\plugins\build\www\ext\Battery.jar ==> C:\Dev\phonegap-blackberry-webworks\BatteryTest\www\ext
C:\Dev\phonegap-blackberry-webworks\plugins\build\www\javascript\battery.js ==> C:\Dev\phonegap-blackberry-webworks\BatteryTest\www\javascript
Create Application Content
You'll need to modify the index.html file that is created for you in the PhoneGap project to invoke the Battery plugin.
- Edit the file: C:\Dev\phonegap-blackberry-webworks\BatteryTest\www\index.html
- Include battery.js (note: JavaScript filenames are case-sensitive):
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
<meta name="viewport" id="viewport" content="initial-scale=1.0,user-scalable=no">
<script src="javascript/json2.js" type="text/javascript"></script>
<script src="javascript/phonegap.0.9.4.min.js" type="text/javascript"></script>
<script src="javascript/battery.js" type="text/javascript"></script>
<script type="text/javascript">
- Include some content to test the Battery plugin:
function getBatteryLevel() {
Battery.level(function(level) {
alert('Battery level is ' + level);
},
function(error) {
alert('Error retrieving battery level:' + error);
});
<body onload="init()" onunload="unload()">
<h3>Battery Level</h3>
<input type="button" value="Battery Level" onclick="getBatteryLevel();return false;" />
Compile and Run the BatteryTest Project
Finally, we're ready to test the Plugin.
- Change into the BatteryTest project directory:
C:\Dev\phonegap-blackberry-webworks>cd BatteryTest
- Edit the project.properties file. You must specify where you installed the BlackBerry WebWorks Packager:
bbwp.dir=C:\\BBWP
- Build the application using ant build:
C:\Dev\phonegap-blackberry-webworks\BatteryTest>ant build
Buildfile: C:\Dev\phonegap-blackberry-webworks\BatteryTest\build.xml
generate-cod-name:
[echo] Generated name: PhoneGapSample.cod
clean:
[delete] Deleting directory C:\Dev\phonegap-blackberry-webworks\BatteryTest\build
package-app:
[mkdir] Created dir: C:\Dev\phonegap-blackberry-webworks\BatteryTest\build\widget
[copy] Copying 11 files to C:\Dev\phonegap-blackberry-webworks\BatteryTest\build\widget
[zip] Building zip: C:\Dev\phonegap-blackberry-webworks\BatteryTest\build\PhoneGapSample.zip
build:
[exec] [INFO] Parsing command line options
[exec] [INFO] Parsing bbwp.properties
[exec] [INFO] Validating widget archive
[exec] [INFO] Parsing config.xml
[exec] [WARNING] Failed to find the <author> element
[exec] [INFO] Populating widget source
[exec] [INFO] Compiling widget
[exec] [INFO] Generating output files
[exec] [INFO] Widget packaging complete
BUILD SUCCESSFUL
Total time: 8 seconds
- Now you're ready to test. Load the application on either the simulator or the device:
C:\Dev\phonegap-blackberry-webworks\BatteryTest>ant load-simulator
- Ta da!
What About the PlayBook?
The WebWorks SDK for Tablet OS is built on top of Adobe Air, not Java. However, work has started to port the Java WebWorks implementation to Air!
It should be merged into the main repo soon but in the mean time check it out here: https://github.com/tinyhippos/phonegap-blackberry-webworks
