HOW-TO: Build the Wikipedia app for PlayBook using PhoneGap

A week or two ago, a RIM employee ported the Wikipedia app to PlayBook and posted the source on GitHub. Prior to trying this, I was not familiar at all with PhoneGap, but I was able to successfully build the app into an installation file (.bar) and to deploy the app to my PlayBook. So, in the spirit of DevCon Europe (coming up in a day or so) here I will attempt to explain the process.

This tutorial is only useful if you are running a Windows based machine

What  you see below may look daunting, and while it is time consuming, it really is not that difficult.

First

In order to build, compile and deploy this app, you will need to download the following:

  1. Sun JDK, not any other distribution.  Install JDK 1.6 or higher, 32-bit version.
  2. Apache Ant  (Note: PhoneGap was developed using version Ant version 1.8.1)
  3. BlackBerry WebWorks Tablet OS SDK for Playbook
  4. The latest PhoneGap SDK
  5. Download the GitHub repo as a zip

Install Java SDK

IMPORTANT: Use the Sun JDK, not any other distribution.  Install JDK 1.6 or higher, 32-bit version.

  1. Download the Sun JDK
  2. Run the installer
  3. Create a JAVA_HOME environment variable.
    1. Open System Properties -> Advanced -> Environment Variables
    2. Create a new system variable
      1. Variable name: JAVA_HOME
      2. Example value: C:\Program Files (x86)\Java\jdk1.6.0_21
  4. Add %JAVA_HOME%\bin directory to the PATH system variable
    1. Open System Properties -> Advanced -> Environment Variables
    2. Under system variables, select PATH and append ;%JAVA_HOME%\bin
      1. e.g. %SystemRoot%\system32;%SystemRoot%;%JAVA_HOME%\bin
  5. Verify that Java is installed.Open a new command window:Start > Run, type in "cmd", and click OK.C:\>java -version
    java version "1.6.0_21"
    Java(TM) SE Runtime Environment (build 1.6.0_21-b07)
    Java HotSpot(TM) Client VM (build 17.0-b17, mixed mode, sharing)

Install Apache Ant

Download Apache Ant  (Note: PhoneGap was developed using version Ant version 1.8.1).

  1. Extract to a desired installation directory, e.g. C:\apache-ant
  2. Create an ANT_HOME environment variable
    1. Open System Properties -> Advanced -> Environment Variables
    2. Create a new system variable
      1. Variable name: ANT_HOME
      2. Variable value: C:\apache-ant
  3. Add %ANT_HOME%\bin directory to the PATH system variable
    1. Open System Properties -> Advanced -> Environment Variables
    2. Under system variables, select PATH and append ;%ANT_HOME%\bin
      1. e.g. %SystemRoot%\system32;%SystemRoot%;%JAVA_HOME%\bin;%ANT_HOME%\bin
  4. Verify that ANT is installed.Open a new command window and type:C:\>ant -v
    Apache Ant version 1.8.1 compiled on April 30 2010
    Trying the default build file: build.xml
    Buildfile: build.xml does not exist!
    Build failed

Install the BlackBerry WebWorks SDK for Tablet OS

Download  Tablet OS WebWorks

Prerequisite: Make sure you have the Adobe AIR SDK v2.7 or later installed and configured on your machine.

If you have an earlier version of the Adobe Air SDK installed on your computer, you must uninstall it before you install a later version of the Adobe Air SDK. If you do not uninstall the earlier version and you just overwrite it, you might receive errors when you compile your WebWorks application.

  1. Locate the WebWorks installer file that you downloaded to your computer, and run the installer.
  2. Click Next to start the installation process.
  3. Review the license agreement, and if you agree to the terms, select the I accept the terms of the License Agreement option and clickNext.
  4. Specify a location where you want to install the WebWorks SDK, and click Next.
  5. Specify the location of your Adobe AIR SDK, and click Next.
  6. Review the pre-installation summary, and then click Install.
  7. Click Done when the installation process completes.

 

Download PhoneGap

  1. Download the latest stable release of PhoneGap
  2. Select the Downloads button on the upper right.
  3. Select the Download.zip button and save the archive file to a temporary directory.
  4. Unzip the contents of the archive file to a working directory,  e.g. C:\Dev\phonegap-1.3.0

 

Okay, now that everything is downloaded, installed, and ready we can finally get down to business!

If you haven't already head over to GitHub and download the repo as a zip file. Extract the zip to wherever you want, navigate to the directory where you extacted the repo zip and leave the window open.

 

Setting up the directory structure

Now, in a new window go ahead and navigate to:

C:\[the directory where you extracted PhoneGap]\lib\blackberry\www

Once there, you should see two folders ("ext" and "playbook"), a 'config.xml' file, 'plugins.xml' file, and one javascript file.

Double-click the 'playbook' folder. In this folder there should only be one javascript (.js) file.

Leave this window open and jump back to the window displaying the extracted GitHub repo. (see image below)

[caption id="attachment_2691" align="aligncenter" width="584" caption="Extracted directory for Wikipedia App repo from github"][/caption]

In this folder you can see the tree for all the different ports for the wikipedia app.  From this directory, we need to grab the 'assets' folder and copy it over to:

C:\[the directory where you extracted PhoneGap]\lib\blackberry\www

 

Once you copy the 'assets' folder, the structure of the directory should look like the above picture.

While you are still here, double-click the 'playbook' folder to open it up.

Leave the window open and  jump back to the window displaying the Wikipedia app directory downloaded from GitHub, open up the 'blackberry' folder, and copy all of the contents over to

C:\[the directory where you extracted PhoneGap]\lib\blackberry\www\playbook

[caption id="attachment_2693" align="aligncenter" width="614" caption="Click image to see full-size"][/caption]

 

Defining the project properties

Okay, now everything is in place for us to compile the application. In the PhoneGap 'playbook' directory there is a file called "project.properties' that needs to be edited. Open this file in your favorite text editor and see the below image:

[caption id="attachment_2694" align="aligncenter" width="573" caption="Click to see full-size"][/caption]

The directory of the WebWorks SDK must be specified in the 'project.properties' file. Since we are building a PlayBook app here only the playbook.bbwp.dir must be specified.

Important: pay attention to the direction of the slashes in the above image.

From within this file you can also specify the playbook simulator if you wish, and you can also specify the PlayBook's IP address and your signing credentials, but I generally build and sign seperately so if you want to do that, go right ahead.

Once you have finished editing this file save it. Now that this file has been saved we can build a .bar.

 

Compiling the application

  1. Open a command window.
    1. Start > Run, then type "cmd" without the quotes.  Click OK.
  2. Change to the PhoneGap PlayBook directory by typing:
cd\[the directory where you extracted PhoneGap]\lib\blackberry\www\playbook

Now type the following:

ant playbook build

[caption id="attachment_2697" align="aligncenter" width="542" caption="Click to see full-size"][/caption]

So, what just happened? If all went well, then a .bar file has now been created.

 

In the newly created "build" directory there will be a file called "Wikipedia.bar" and all it needs is to be signed and deployed to your PlayBook!

There are several ways of doing this and many more steps that could have been included, but I figure most people simply want to build and deploy the app for their own use, so I attempted to make this tutorial as straight-forward as possible

Join the Forum discussion on this post

Leave your comments

Post comment as a guest

0
  • No comments found
Subscribe to the official OSBB BBM Channel!

osbbchannelQR

C00013E89

Back to top