This article provides a complete walkthrough for first time developers about how to use the BlackBerry® WebWorks™ SDK to create a BlackBerry Smartphone application. Developers should be aware that the BlackBerry WebWorks SDK for the BlackBerry® Tablet OS is a separate development tool, and is not included in this walkthrough.
First time developers using the BlackBerry WebWorks SDK for Smartphone application development.
A. Download and install the BlackBerry WebWorks SDK tools for BlackBerry Smartphone development.
B. Create a BlackBerry WebWorks configuration document (config.xml).
C. Create a ZIP archive file containing your BlackBerry WebWorks application assets.
D. Package your BlackBerry WebWorks application using the command line utility.
E. Load and run your BlackBerry WebWorks application on a BlackBerry Smartphone simulator.
1. Download and install the Java® SE 6 Development Kit (JDK) from the Oracle® Web site. The JDK 6 (also referred to as JDK v1.6) is a requirement for using the BlackBerry WebWorks SDK command line tool and is not to be confused with the Java Runtime Environment (JRE).
Optional verification: You can confirm that JDK v1.6 is the default Java compiler being used by your system. Open a command prompt (Start - Run - ”cmd”) and type “javac –version” to confirm what version of the JDK is active.
Troubleshooting: If you do not see version 1.6 as the active Java compiler, it may be due to having previous versions of the JDK installed. The JDK installation process adds its install folder to the Windows® System PATH variable. Verify that the folder path of the JDK v1.6 is defined before any others in the PATH variable. You can find and edit the contents of the PATH variable by opening the system properties window (Start - Control Panel - System), then selecting the Advanced tab and clicking on the “Environmental Variables” button.
2. Download and install the BlackBerry WebWorks SDK for Windows. Once installed, you can begin using the bbwp.exe command line utility which is located in the root of the installation folder.
Tip: The default installation folder of the BlackBerry WebWorks SDK for Smartphone is: C:\Program Files\Research In Motion\BlackBerry WebWorks Packager.
A BlackBerry WebWorks application configuration document contains elements that define application behavior, characteristics, properties as well as features and access permissions. The config.xml documentation guide contains a complete overview of required and optional field names and values that can be added to a config.xml file.
1. Create a new XML file named config.xml using your favorite text editor. Save your config.xml file in the following location:
Tip: Certain text editing tools offer helpful benefits for Web developers such as syntax highlighting, code folding and macros. There are many options available however some recommended text editors for Windows include Notepad++ and UltraEdit and for Mac TextMate and Coda.
2. Edit the config.xml document. Using the config.xml documentation guide, you can manually create each element for your own config.xml file. However as a starting point for developers, the following sample config.xml file can be used. This sample demonstrates how to create a Web launcher to the BlackBerry Developer’s Blog Website. Copy the following XML content into your config.xml file:
<?xml version="1.0" encoding="UTF-8"?>
<description>The BlackBerry Developers Blog</description>
<access subdomains="true" uri="*"/>
3. Create a home screen image icon for your application. Make sure that the name of your icon image matches that which was defined in the <icon> element of your config.xml file. Save the icon image in the same folder location as the config.xml file.
Tip: Information about recommended home screen icon sizes, formats as well as best practices can be found in the BlackBerry Development UI Guidelines.
Tip: BlackBerry home screen icons can either be created net new using image authoring tools, or leveraged from existing Web assets. For instance, if you already have images defined as part of your Web site, you can re-use these files for your BlackBerry WebWorks application.
The ZIP file of your WebWorks application assets will be transformed, by the BlackBerry WebWorks SDK command line tool, into a standalone BlackBerry Smartphone application.
1. Navigate to the folder location of your WebWorks application using file explorer (e.g. “c:\applications\devBlog”). Select all of the files that are considered application assets (e.g. “config.xml” and “icon.png”) and right click on the screen to open the menu. If you have WinZip® installed on your system, you can choose “Winzip - Add to ZIP file” otherwise select the “Send To - Compressed (ZIP) folder” from the menu.
Tip: Ensure that the name of the BlackBerry WebWorks ZIP archive file matches that of your application folder. This will make the packaging and deploying steps easier.
Troubleshooting: The bbwp.exe utility requires that the BlackBerry WebWorks ZIP file has the application assets as the root elements of the archive. Often developers incorrectly archive their BlackBerry WebWorks application’s folder, instead of only the assets. Ensure that the config.xml file can be found in the root of your ZIP archive:
The BlackBerry WebWorks SDK command line tool uses a Java compiler to package the Web assets that are contained within a ZIP file into a standalone BlackBerry application that can run on Device Software 5.0 and higher.
1. Open a command prompt (Start > Run - “cmd”) and change directory to the installation folder of the BlackBerry WebWorks SDK using the following command:
cd "C:\Program Files\Research In Motion\BlackBerry WebWorks Packager"
2. Compile your BlackBerry WebWorks application. This is performed by providing the bbwp.exe utility with the complete file path to your BlackBerry WebWorks application ZIP archive. Use the following command to compile the DevBlog BlackBerry WebWorks application:
Tip: Type “bbwp” on its own to see a list of optional command line arguments. Some of these arguments may be helpful to you as a developer.
3. Verify that the bbwp utility created the correct output files. Using file explorer, navigate to the “c:\applications\devBlog” folder and confirm that a \bin folder was created. Within the bin folder, there should be an \OTAInstall and \StandardInstall folder.
Tip: The OTAInstall folder contains files used for deploying your BlackBerry application to end users via a Web Site. Once these files are correctly hosted on a Web server, end users can download and install your application using their BlackBerry browser.
Tip: The StandardInstall folder contains filed used for deploying your BlackBerry application via BlackBerry® App World™ or using a BlackBerry® Enterprise Server. These files can also be used for deploying your application directly to a BlackBerry Smartphone simulator.
1. Ensure that you have a version of the BlackBerry Smartphone simulator installed, running Device Software 5.0 or higher. The installer for the BlackBerry WebWorks SDK command line tool installs a version of BlackBerry Smartphone simulator in the following location:
C:\Program Files\Research In Motion\BlackBerry WebWorks Packager\simpack
Tip: You can also download and install different versions of the BlackBerry Smartphone simulator should you wish to test your application on difference device and software variations.
2. Start the BlackBerry Smartphone simulator.
Tip: To start a simulator from the BlackBerry WebWorks SDK command line tool installation folder, launch the appropriate *.bat file found within the simulator sub folder (e.g. 9800.bat, 9550.bat or 9700.bat).
Tip: If you have installed your own simulator from the BlackBerry Developers website, you can run it from the Start menu (Start > All Programs > Research In Motion >BlackBerry Smartphone Simulators).
3. Once the simulator has started, select "Load BlackBerry application or theme" from the File menu. Navigate to the *.cod file within the /StandardInstall folder of your BlackBerry WebWorks application development folder and click OK. Once loaded, you will be able to launch your application from the home screen.
At this point, you have created a standalone BlackBerry Smartphone application using the BlackBerry WebWorks SDK. The DevBlog application launches and loads the content from a live Web Site.
To experiment further with the capabilities of the BlackBerry WebWorks SDK, open and review the attached "helloWorld.zip". This application demonstrates how Web content can be packaged into the application itself and accessed even when the device is offline. Using this sample, repeat the archiving, compiling and deployment process outlined in this walkthrough to load the "Hello World" application on a BlackBerry Smartphone simulator.