What is WebWorks?

BlackBerry WebWorks is an application platform for BlackBerry smartphones. The BlackBerry WebWorks SDK was released by Research In Motion in October 2009 - under the name, BlackBerry Widgets - to enable developers to create hybrid (web and native) applications for BlackBerry devices running BlackBerry OS 5.0 and higher. WebWorks applications cannot be run on devices that support BlackBerry OS 4. In September 2010, RIM announced BlackBerry WebWorks, the next generation of the BlackBerry Widget framework. At the time of the announcement, WebWorks was little more than a rebranding of the existing Widget framework. RIM continues to develop WebWorks, and has made a version of the SDK available for the PlayBook tablet. Before the BlackBerry WebWorks SDK was released, developers could only create BlackBerry applications using RIM's Java Development Environment (JDE). The BlackBerry WebWorks SDK is targeted at the web developer and enables a new kind of hybrid (web + native Java) application for BlackBerry devices. The platform includes: The BlackBerry WebWorks API, which exposes device information and capabilities through JavaScript. A framework that enables developers to extend the WebWorks API. The framework allows developers to create JavaScript Extensions, which are written in Java and expose their own JavaScript API through the WebWorks framework. JavaScript Extensions have full access to all the capabilities that RIM's native Java APIs provide. Development tools to help create WebWorks applications and JavaScript Extensions.

RIM also open sourced the WebWorks framework.

Important Information
BlackBerry WebWorks tooling is only available for Windows environments. In addition, if you are running a 64-bit Windows operating system, you must use the 32-bit versions of the Java SDK and Eclipse. WebWorks applications can ONLY be deployed to BlackBerry devices running OS 5.0 and higher. This information will not help you develop PhoneGap applications targeted for BlackBerry OS 4. For instructions on how to do that, see link.

Prerequisites (All Environments)

1. Operating System: Windows XP (32-bit) or Windows 7 (32-bit and 64-bit).

Install Java SDK

IMPORTANT: Use the Sun JDK, not any other distribution. Install JDK 1.6 or higher, 32-bit version. 1. 2. 3. Download the Sun JDK Run the installer Create a JAVA_HOME environment variable. i. Open System Properties -> Advanced -> Environment Variables ii. Create a new system variable a. Variable name: JAVA_HOME b. Example value: C:\Program Files (x86)\Java\jdk1.6.0_21 Add %JAVA_HOME%\bin directory to the PATH system variable i. Open System Properties -> Advanced -> Environment Variables ii. Under system variables, select PATH and append ;%JAVA_HOME%\bin a. e.g. %SystemRoot%\system32;%SystemRoot%;%JAVA_HOME%\bin 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)

4.

5.

Run the PhoneGap Sample Application

This section describes the fastest way to run the PhoneGap sample application on a BlackBerry device simulator. You will need Apache Ant to build the PhoneGap sample, and the BlackBerry WebWorks SDK to package, deploy, and test the application.

Install Apache Ant

1. 2. 3. Download Apache Ant (Note: PhoneGap was developed using version Ant version 1.8.1). Extract to a desired installation directory, e.g. C:\apache-ant Create an ANT_HOME environment variable i. Open System Properties -> Advanced -> Environment Variables ii. Create a new system variable a. Variable name: ANT_HOME b. Variable value: C:\apache-ant Add %ANT_HOME%\bin directory to the PATH system variable i. Open System Properties -> Advanced -> Environment Variables ii. Under system variables, select PATH and append ;%ANT_HOME%\bin a. e.g. %SystemRoot%\system32;%SystemRoot%;%JAVA_HOME%\bin;%ANT_HOME%\bin 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

4.

5.

Install the BlackBerry WebWorks SDK

1. 2. Download the latest version of the BlackBerry WebWorks SDK. Run the BlackBerry WebWorks SDK installer. It is recommended to install to a directory that contains no spaces, e.g. C:\BBWP.

NOTE: To have a choice of locations to install, choose the "Run" option instead of the "Save" option when given that choice during the downloading procedure.

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

Build the PhoneGap Sample Application Project

1. Open a command window. Start > Run, then type "cmd" without the quotes. Click OK. 2. Change to the PhoneGapBlackBerry\WebWorks directory: C:\>cd Dev\phonegap-1.3.0\phonegap-1.3.0\BlackBerry-WebWorks\sample 3. Specify the BlackBerry WebWorks Packager installation directory, bbwp.dir, in the project.properties file. Open the file using a text editor, and set the bbwp.dir path to where you installed BBWP. blackberry.bbwp.dir=C:\\BBWP

Note: be sure to escape the backslashes in the directory path. 4. Return to the command window and build the PhoneGap sample project: C:\Dev\phonegap-1.3.0\phonegap-1.3.0\BlackBerry-WebWorks\sample>ant blackberry build Buildfile: C:\Dev\bbw\sample\build.xml generate-cod-name: [echo] Generated name: PhoneGapSample.cod clean: [delete] Deleting directory C:\bbw\sample\build package-app: [mkdir] Created dir: C:\Dev\phonegap-1.0.0\phonegap-1.0.0\BlackBerry-

WebWorks\sample\build\widget [copy] Copying 8 files to C:\Dev\phonegap-1.0.0\phonegap1.0.0\BlackBerry-WebWorks\sample\build\widget [zip] Building zip: C:\Dev\phonegap-1.0.0\phonegap1.0.0\BlackBerry-WebWorks\sample\build\PhoneGapSample.zip build: [exec] [exec] [exec] [exec] [exec] element [exec] [exec] [exec] [exec]

[INFO] [INFO] [INFO] [INFO] [WARNING] [INFO] [INFO] [INFO] [INFO]

Parsing command line options Parsing bbwp.properties Validating widget archive Parsing config.xml Failed to find the <author> Populating widget source Compiling widget Generating output files Widget packaging complete

BUILD SUCCESSFUL Total time: 7 seconds

Run the PhoneGap Sample Application in a Simulator

Use the ant build script in the PhoneGap project directory to run the PhoneGap sample application in the simulator of your choice. By default, the build script will choose the first simulator it finds within the BlackBerry WebWorks Packager directory. You can override this behavior and specify which simulator to use by editing the project.properties file within the project directory. 1. Run the PhoneGap sample in BlackBerry smartphone simulator: C:\Dev\phonegap-1.3.0\phonegap-1.3.0\BlackBerry-WebWorks\sample>ant blackberry load-simulator 2. On the simulator, click the BlackBerry icon and go to the Downloads folder. You will see the PhoneGap sample app listed there.

3.

[Optional] Run the PhoneGap sample in a user-defined BlackBerry simulator. Edit the project.properties file. In this case, we specify the simulator running BlackBerry OS 6.0 (Torch 9800) that comes installed with the BlackBerry WebWorks Packager. When finished, repeat steps 1 and 2.

# (Optional) Simulator Directory # # If sim.dir is not specified, the build script will use the simulator

directory # within the Blackberry Widget Packager. # blackberry.sim.dir=C:\\BBWP\\simpack\\6.0.0.227 # (Optional) Simulator Binary # # If sim.bin is not specified, the build script will attempt to use the default # simulator in the simulator directory. # blackberry.sim.bin=9800.bat

Run the PhoneGap Sample Application on a Device

Use the ant build script in the PhoneGap project directory to run the PhoneGap sample application on a BlackBerry device that is connected via USB. In order to use the application on a device, you must codesign the application. This is similar to Apple's provisioning profile. 1. 2. Purchase code-signing keys from Research in Motion (Web Form). Once purchased, an email will describe how to install the keys to your WebWorks SDK. Run the PhoneGap sample on BlackBerry smartphone device: C:\Dev\phonegap-1.3.0\phonegap-1.3.0\BlackBerry-WebWorks\sample>ant load-device 3. 4. On the device, click the BlackBerry icon and go to the Downloads folder. You will see the PhoneGap sample app listed there. [Optional] Save your code signing password. Edit the project.properties file. In this case, we specify the signing tool password: # Code Signing Password # # If you leave this field blank, then # the signing tool will prompt you each time # sigtool.password=mysecretpassphrase

Develop a PhoneGap Application Using Eclipse IDE

In addition to the standalone BlackBerry WebWorks SDK installation, Research In Motion provides plugins that enable you to take advantage of IDE's like Eclipse and Microsoft Visual Studio. This sections describes the steps necessary to begin developing your PhoneGap application in Eclipse.

Download and Install Eclipse IDE

IMPORTANT: The BlackBerry WebWorks SDK, version 1.5 requires Eclipse 3.6 or later (Helios). You may also use the previous version of the BlackBerry WebWorks SDK (version 1.0) with Eclipse 3.5 (Galileo); however, RIM recommends using the latest version. 1. 2. Download the 32-bit version of Eclipse 3.6. Unpack the contents of the archive file into a directory of your choice, e.g. C:\eclipse-3.6.1.

Install the BlackBerry Web and WebWorks SDK Plug-ins for Eclipse
End Of Life Notice: The BlackBerry WebWorks Plug-in For Eclipse will no longer be available for download as of Oct. 18, 2011. Support for the plug-in will be discontinued on Dec. 31, 2011. Read more. You will need at least two plug-ins to develop WebWorks applications using Eclipse: the BlackBerry Web Plug-in, and the WebWorks SDK Plug-in. Both are available using the standard Eclipse software installation procedure. Note: Even if the standalone BlackBerry WebWorks SDK is already installed on your system, you must install the BlackBerry WebWorks Plug-in for Eclipse to enable Blackberry WebWorls project capabilities within Eclipse. 1. 2. Start Eclipse and create a workspace. Help -> Install New Software... -> Click Add... Name: Blackberry Update - Web Location: Blackberry Web - http://www.blackberry.com/go/eclipseUpdate/3.6/web Select Blackberry Web Plug-in Category. This will select both of the required plug-ins

3.

4.

Restart Eclipse

Create a BlackBerry WebWorks Project in Eclipse

This section describes how to create a new BlackBerry WebWorks project in Eclipse, and import the PhoneGap sample application and framework. 1. 2. Create a BlackBerry WebWorks project. File -> New -> Project... -> BlackBerry -> BlackBerry Widget Project Project Name: PhoneGapSample Start Page: index.html Note: The BlackBerry WebWorks Packager really hates special characters, like hyphens `-` in project names. It is recommended that you avoid them. Import the PhoneGap sample application i. In the project hierarchy, right-click on the WebWorks project and select Import...Select General -> Filesystem ii. Browse to the `www` directory within the project directory you created above, e.g. C:\Dev\phonegap-1.3.0\phonegap-1.3.0\BlackBerryWebWorks\sample\www

3.

iii.

Select the `www` directory to import its entire contents

4. 5.

Build the WebWorks application i. Select the project, right-click and select Build BlackBerry Widget Project Run the WebWorks application in the simulator i. Select the project, right-click and select Run as -> Blackberry Simulator