PhoneGap is a great tool for creating cross platform mobile apps. Whilst the documentation for deploying to iOS and Android is really thorough, I’ve found the BlackBerry PlayBook guide, especially when using a Mac, to be quite sparse.

Here are the steps I took to setup a development environment for both the simulator and an actual device.#Prerequisites

Before you get started you need to download the following:

• BlackBerry WebWorks for Tablet OS (this also meant installing the Adobe AIR SDK for me too)
• Latest PhoneGap release

Note: When asked where to install the WebWorks SDK I chose /Developer/PlayBookSDK. You will need this path later so if you install somewhere different then make a note of it.

Build & run PhoneGap HelloWorld

Once the WebWorks SDK is installed and PhoneGap has been downloaded, you will need to:

Copy the sample application

Copy the folder lib/blackberry from the PhoneGap release to a new location

$ cp -ap ./lib/blackberry /Developer/Apps/PlayBook/helloworld

Then change your working directory to the sample folder

$ cd ./sample

Update the properties file

Various parameters need to be set within the project.properties file, to enable building and deployment of WebWorks apps. Firstly you need to provide the location of the BlackBerry WebWorks Packager (aka bbwp). Its important that you use the directory to which you installed the SDK, not the path to the bbwp directory itself (use the directory one level higher). For my setup the correct path was:

playbook.bbwp.dir=/Developer/PlayBookSDK

Install the PlayBook Simulator

The PlayBook simulator is bundled with the SDK download and can be run from within VMWare Fusion. Open Fusion and import the following file:

/Developer/PlaybookSDK/bbwp/blackberry-tablet-sdk/BlackBerryPlayBookSimulator-1.0.7/BlackBerryPlayBookSimulator.vmx

Once imported, run the simulator.

Setup the Simulator for Development

To setup the simulator for development work you will need to do the following:

1. Tap on the Settings icon top right of the screen
2. Select the ‘Security’ tab
3. Select ‘Development Mode’

4. Enable the ‘Use Development Mode’ toggle

   

5. Return to the homescreen and a new icon should have appeared in the menubar

6. Tap the new icon and make a note of the IP address

   

Now update you project.properties file with the simulators IP address:

playbook.sim.ip=172.16.91.139

You’re now ready to deploy the app to the simulator:

ant playbook load-simulator

Depending on the file permissions of your SDK folder you may need to run the ant command as sudo. Once the build has completed the Hello World app should launch in the simulator.

Setup a Device for Development

Follow steps 1-6 from the above simulator instructions on the device to enable Development Mode and obtain the devices IP address. Add the IP address to your project.properties.

playbook.device.ip=172.16.91.139

Signing certificates are required to test applications on real hardware. These can be applied for with the BlackBerry Code Signing Keys Order Form. I found the turn-around to be very quick, with the keys arriving within a couple of hours.

Once your keys arrive (via email) then follow the instructions from the BlackBerry site on how to install them. Note that the “password” you choose will need to be written into a plain text file so don’t pick anything you use for anything else!

You then just need to update your project.properties file once again and add the passwords you created in the previous step:

playbook.sigtool.csk.password=PASSWORD
playbook.sigtool.p12.password=PASSWORD

You should now be able to deploy to the device using the deploy script:

ant playbook load-device

Enabling the Remote Inspector

At the time of writing the PlayBook is the only device to ship with remote WebKit debugging. This is one area that the PlayBook really excels and makes creating PhoneGap based apps much easier when compared to other platforms such as iOS & Android.

To enable this functionality in your PhoneGap/WebWorks app you need to do the following steps.

From either the simulator or device:

Ensure a password is set

• Tap on the Settings icon top right of the screen
• Select the ‘Security’ tab
• Select ‘Password’
• Enable the ‘Use Password’ toggle & provide a password

Add the password to your properties file:

Add the following to you project.properties file:

playbook.device.password=PASSWORD

or for simulator:

playbook.sim.password=PASSWORD

Update the build settings

Add a flag to the playbook.xml file. Find <!-- BBWP MACRO --> and add <arg value="-d" /> to the two <exec> nodes in following block:

<exec executable="${bbwp}">
    <arg file="${build.dir}/${cod.name}.zip" />
    <arg value="-gcsk" />
    <arg value="${properties.playbook.sigtool.csk.password}" />
    <arg value="-gp12" />
    <arg value="${properties.playbook.sigtool.p12.password}" />
    <arg value="-o" />
    <arg file="${build.dir}" />
    <arg value="-buildId" />
    <arg value="${build.number}" />
    <arg value="-d" />
</exec>

and

<exec executable="${bbwp}">
    <arg file="${build.dir}/${cod.name}.zip" />
    <arg value="-o" />
    <arg file="${build.dir}" />
    <arg value="-buildId" />
    <arg value="${build.number}" />
    <arg value="-d" />
</exec>

This will enable the Web Inspector for your WebWorks/PhoneGap app (be sure to remove this when it comes time to distribute).

Load a browser on your desktop/laptop

Visit the IP address of your device/simulator using port 1337, e.g.

http://172.16.91.139:1337

You should now be able to debug your application using the familiar WebKit inspector, including JavaScript breakpoints, console access and CSS manipulations.

---

I wrote this guide partly as a resource for myself after working on porting the Rareloop Mobile Data Collection framework to work on the Playbook. If you find any in-accuracies or improvements or would like to discuss our mobile data collection platform some more, just give me a shout in the comments or via the Rareloop website.