5. Configuring a BlackBerry Development Environment for PhoneGap

This chapter includes the instructions to follow to install and use the BlackBerry development tools to build PhoneGap applications for both BlackBerry smartphones and BlackBerry PlayBook tablet devices. To complete the steps outlined, you must first perform several installation steps using instructions provided elsewhere in the book:

1. Install the PhoneGap framework using the instructions provided in Appendix A.

2. (Windows only) Install the Oracle Java Developer Kit (JDK) using the instructions provided in Appendix B.

3. (Windows only) Install Apache Ant using instructions provided in Appendix C.

Once you’ve completed those steps, you’re ready to start work on PhoneGap applications for BlackBerry.

Installing the BlackBerry WebWorks SDK

As mentioned in Chapter 1, BlackBerry PhoneGap applications are essentially BlackBerry WebWorks applications (a special kind of BlackBerry application) with some extra PhoneGap stuff baked in. To build PhoneGap applications for BlackBerry, you must leverage the BlackBerry WebWorks SDK. The tools consist of a series of command-line tools you use to create, build, and test WebWorks applications.

To download the BlackBerry WebWorks SDK, point your browser of choice to www.blackberry.com/developers. On the WebWorks page, select the Tools & downloads option, and then download the latest version of the WebWorks SDK for the BlackBerry device for which you will be developing applications. The file is pretty large, so it may take a while to download; the toolkit includes the SDK as well as server components and device simulators needed to test applications for BlackBerry.

The Macintosh and Windows installation steps are essentially the same: Once the download has completed, launch the downloaded file to start the installation process, and follow the prompts until the process completes.

On Windows systems, experience has proven that many Java applications have difficulty running from a location that contains spaces in the folder name. Other applications also seem to have difficulty running within the restricted security environment on Microsoft Windows Vista and Windows 7. For these reasons, it’s recommended to install the WebWorks SDK off the root of the system’s hard drive rather than in the Program Files folder.

For the WebWorks PlayBook SDK installation, you will also need to download and install the Adobe Air SDK from www.adobe.com/go/getairsdk and the VMware Player application (needed to run the PlayBook Simulator).

Creating a BlackBerry PhoneGap Project

When you installed the PhoneGap project files, included with them is a sample project that demonstrates a wide range of PhoneGap project features. Figure 5-1 shows the sample project’s folder. Unfortunately, there’s currently no simple way to create a new blank BlackBerry project using the files provided, but I hope this will be changed in an upcoming release. You’ll have to copy the existing sample project and then remove the code and any extra files included in the project.

Figure 5-1 PhoneGap BlackBerry WebWorks project files

To create a new BlackBerry PhoneGap project, simply copy the sample project folder shown in Figure 5-1 to a new folder, and then modify the contents of the index.html file (located in the www folder) to suit the needs of your application. For the web application code used throughout the remainder of this chapter, we’ll use the HelloWorld3 application used in Chapter 2.

For BlackBerry WebWorks projects, RIM uses a W3C standard called the Widget Packaging and XML Configuration to define a file (config.xml) that contains settings that control part of the application build process. You can find the detailed information about the standard at www.w3.org/TR/widgets. By default, the config.xml file will be located in a PhoneGap project’s www folder. For each PhoneGap application, you will need to modify the contents of this file with settings for your application. A sample config.xml file is shown here.

Table 5-1 briefly describes each of the elements in the file. Additionally, an excellent reference for the settings in the config.xml file can be found at www.tinyurl.com/78q8sgr.

Table 5-1 Config.xml Elements

Using your text editor of choice, edit the application’s config.xml file as needed with the appropriate settings for your application, and then save your changes. At this point, the application is ready to be built.

Building BlackBerry PhoneGap Applications

The default PhoneGap project includes an Ant script that manages the process of building the application plus some additional tasks that help with testing and deploying a PhoneGap application. The script is in a file called build.xml, and it is located in the root of the PhoneGap project folder. I’ll cover the options for that particular file in a minute.

Beginning with PhoneGap 1.3, the PhoneGap development team added support for WebWorks tablet applications (applications built for the BlackBerry PlayBook tablet). With older versions of PhoneGap, all of the supported build processes were implemented in the build.xml file. Beginning with PhoneGap 1.3, the Ant script (described later) calls out to the blackberry.xml or playbook.xml file depending on the platform for which the application is being built.

Configuring the Build Process

The build process leverages configuration settings defined in a WebWorks project properties file called project.properties. This file is located in a WebWorks project’s root folder and contains settings that tell the build script where to locate BlackBerry-specific applications that are used during the build, test, and packaging process. An example project.properties file is shown here.

Table 5-2 lists a brief description of the relevant configuration options defined in the project.properties file. The BlackBerry and PlayBook development kits (at least for the moment) use different SDKs to build their applications. Since the project.properties file has to support configuration options for both SDKs, each of the properties defined within the file are predicated with a blackberry. or playbook. to indicate to which platform the property applies.

Table 5-2 Project.properties Configuration Options

The device simulators included with the WebWorks SDK can access local resources, but when they need to access data or applications residing on a network server, they leverage the BlackBerry Mobile Data System (MDS) server to provide that access. Included with the WebWorks SDK is a full-featured version of the BlackBerry MDS server component. The Ant scripts used to test PhoneGap applications (described later in the chapter) will automatically load the MDS simulator before loading the appropriate device simulator. When the MDS simulator launches, it will open a text-based window similar to the one shown in Figure 5-2. During testing of your application on a BlackBerry simulator, you’ll want to leave this window open. It will display a series of entries every time the device simulator requests and receives data from a network resource such as a web server.

Figure 5-2 BlackBerry MDS simulator window

For additional information on the capabilities provided by MDS, refer to Chapter 4 of my other mobile development book, BlackBerry^® Development Fundamentals (www.bbdevfundamentals.com).

Using your text editor of choice, modify the project.properties file as needed for your particular system’s configuration and save your changes, and you’re ready to build your application.

Executing a Build

To build a BlackBerry PhoneGap application, open a command prompt or terminal window, navigate to the project’s root folder, and issue the following command:

Click here to view code image

ant blackberry build

Ant will read its instructions from the build.xml file included with the project and perform the steps needed to build the application.

To build a PlayBook PhoneGap application, issue the following command:

Click here to view code image

ant playbook build

A sample listing of the output from this process is shown here:

Click here to view code image

Buildfile: C:DevPhoneGapBlackBerrysampleuild.xml

blackberry:

build:

generate-cod-name:
     [echo] Generated name: PhoneGapSample.cod

clean:
   [delete] Deleting directory C:DevPhoneGapBlackBerry
     sampleuild

package-app:
  [mkdir] Created dir:
    C:DevPhoneGapBlackBerrysampleuildwidget
  [copy] Copying 9 files to
    C:DevPhoneGapBlackBerrysampleuildwidget
  [zip] Building zip:
    C:DevPhoneGapBlackBerrysampleuildPhoneGapSample.zip

build:
  [exec] [INFO]     Parsing command line options
  [exec] [INFO]     Parsing bbwp.properties
  [exec] [INFO]     Validating application archive
  [exec] [INFO]     Parsing config.xml
  [exec] [WARNING]  Failed to find the <author> element
  [exec] [INFO]     Populating application source
  [exec] [INFO]     Compiling BlackBerry WebWorks application
  [exec] [INFO]     Generating output files
  [exec] [INFO]     BlackBerry WebWorks application packaging
    complete

BUILD SUCCESSFUL
Total time: 21 seconds

C:DevPhoneGapBlackBerrysample>

If everything is configured correctly and the files are all in the right locations, at this point you’ll have a compiled version of the application all ready to go.

During the build process, the script will create a new folder called build under the project’s root folder. Within that folder are two folders that are important when it comes to deploying your application to BlackBerry smartphones: OTA Install and Standard Install. The OTA Install folder contains the files you will need to deploy the application over the air (OTA), pushed to devices by the BlackBerry Enterprise Server (BES). The files located in the Standard Install folder can be used to manually install an application (discussed later), be pulled down to a device from a web server, or be deployed through the BlackBerry App World. Each of these options is described in detail in Chapter 16 of BlackBerry^® Development Fundamentals (www.bbdevfundamentals.com).

Besides the build command used in the previous example, the build.xml file also contains code supporting command-line options for the following processes:

• load-device

• load-simulator

• package-app

• clean

• clean-device

• clean-simulator

• help

To view information about each of these options, issue the command ant help in the same command prompt window used to build the application. The script will display usage instructions for each of the available options.

Testing BlackBerry PhoneGap Applications

To test the application, you have two options: You can test in the BlackBerry simulator, or you can test on a physical device. This section contains instructions for how to execute each option.

Testing on a BlackBerry Device Simulator

To test your PhoneGap application on a BlackBerry device simulator, open a command prompt, navigate to the project’s root folder, and issue the following command:

Click here to view code image

ant blackberry load-simulator

The build script will load the BlackBerry MDS simulator and then load the appropriate device simulator (BlackBerry or PlayBook) using default options for the WebWorks SDK or using the specific settings you added to the project’s project.properties file.

For BlackBerry devices, the location for the application’s icon will vary depending on which version of BlackBerry Device Software the simulator is running. For newer BlackBerry Device Software versions, the application’s icon can typically be found in the Downloads folder, but in some cases it’s loaded directly on the Home Screen, as shown in Figure 5-3.

Figure 5-3 BlackBerry HelloWorld PhoneGap application icon

When you click the application’s icon, the application will load and display a screen similar to the one shown in Figure 5-4.

Figure 5-4 BlackBerry HelloWorld PhoneGap application

To test your PhoneGap application on a BlackBerry Playbook device simulator, issue the following command to load the application onto the simulator:

Click here to view code image

ant playbook load-simulator

You will need to launch the simulator manually and configure the options in the project.properties file to load the application on the PlayBook simulator. Refer to the PlayBook developer resources web site at www.blackberry.com/developers for additional information on how to configure and use the PlayBook simulator.

For PlayBook tablets, the application will load onto the device’s home screen. The PlayBook does not currently support the concept of folders for grouping application icons. To launch the application, simply touch the application icon on the device screen.

Testing on a Device

To test your PhoneGap application on a physical BlackBerry device, connect a device to the system using a USB cable, open a command prompt, navigate to the project’s root folder, and issue the following command:

Click here to view code image

ant blackberry load-device

The build script will load the application on the physical device.

You can also use the BlackBerry JavaLoader program (javaloader.exe) to load the application onto a physical BlackBerry device. Navigate to the WebWorks SDK installation’s bin folder, and then execute the following command:

Click here to view code image

JavaLoader.exe -u load codfilename.cod

In this example, codfilename refers to the relative path to the application’s compiled executable (the .cod file), which for the current example is as follows:

Click here to view code image

JavaLoader.exe -u load c:devphonegapBlackBerryHelloWorldBuildStandardInstallHelloWorld.cod

JavaLoader will connect to the device over the USB cable and transfer the application’s files to the device. Once the process has completed, you can navigate to the application’s icon on the device’s home screen and launch the application.

To test your PhoneGap application on a physical PlayBook device, connect a device to the system using a USB cable, open a command prompt window, navigate to the project’s root folder, and issue the following command:

Click here to view code image

ant playbook load-device