Package and test your app

We have just a few more steps to get your app up and running!

Create your config.xml file

The BlackBerry WebWorks config.xml file contains the information that a BlackBerry PlayBook tablet needs to run your app. The file provides information such as:

  • Application namespace
  • Name of the app
  • Application permissions
  • The start page
  • The icons used in the app
  • General app information, such as author, email address, and license information

In a text editor, create a file named config.xml in the HelloGeo folder. 

Copy and paste the following code into the config.xml file, and then save the file:

<?xml version="1.0" encoding="UTF-8"?>
<widget xmlns="http://www.w3.org/ns/widgets"
        xmlns:rim="http://www.blackberry.com/ns/widgets"
        version="1.0.0.0" id="HelloGeoApp">  
    <name>Hello Geo</name>
    <author>My name</author>
    <description>Geolocation display</description>
    <icon src="images/icon.png"/>
    <content src="index.html"/>
    <rim:permissions>  
        <rim:permit>access_location_services</rim:permit>
    </rim:permissions>    
</widget>

Now, let's have a look at the code we just added.

We start with a standard XML declaration. It defines the XML version (1.0) and the encoding that's used (UTF-8).
<?xml version="1.0" encoding="UTF-8"?>
The <widget> element is the root element that defines:
  • The namespace for the BlackBerry WebWorks app (required)
  • The namespace for BlackBerry specific application extensions (required if you include BlackBerry specific extensions)
  • The version number and id of the app (required)
<widget xmlns="http://www.w3.org/ns/widgets"
        xmlns:rim="http://www.blackberry.com/ns/widgets"
        version="1.0.0.0" id="HelloGeoApp">
The next few lines specify meta data about your app.
<name>Hello Geo</name>
<author>My name</author>
<description>Geolocation display</description>
The <icon> element specifies the icon for the app that appears on the home screen of the BlackBerry device.
<icon src="images/icon.png"/>
The <content> element specifies the page that appears when the app starts. In this case, we specify the index.html file as the source.
<content src="index.html"/>
The <rim:permissions> element specifies the permissions for various features in the app. For the HelloGeo app, we use the <rim:permit> element with the <access_location_services> permission, so that the app can read the current GPS location of the device.
<rim:permissions>  
    <rim:permit>access_location_services</rim:permit>
</rim:permissions>

There are many other elements that you can use in a BlackBerry WebWorks config.xml file. To learn more about these elements, see Create your config.xml file.

After you save your config.xml file, you can build and package your app.

Configure your build settings in the Ripple

You can use the Ripple emulator to build and package your application. The Ripple emulator adds your project files to a .zip file, packages your app, and creates an executable file to run on the BlackBerry PlayBook tablet.

For some versions of Windows, you may need to be logged into an account with administrator privileges to successfully build your BlackBerry WebWorks app.

To build and package your app, you must first configure the build settings in the Ripple emulator.

  1. In the Ripple emulator, select the Build panel.
  2. Select Settings.
  3. In the SDK Path field, type the location where the BlackBerry PlayBook OS SDK is installed. The default locations are:
    • Windows XP: C:\Program Files\Research In Motion\BlackBerry WebWorks SDK for TabletOS <version>
    • Windows 7: C:\Program Files (x86)\Research In Motion\BlackBerry WebWorks SDK for TabletOS <version>
    • Mac OS: /Developer/SDKs/Research In Motion/BlackBerry WebWorks SDK for TabletOS <version>
  4. In the Project Root field, type the location of your project (for example, C:\Users\<Username>\RippleSites\HelloGeo).
  5. In the Archive Name field, type HelloGeo. This is the name for the .zip file.
  6. In the Output Folder field, type the location where you want the output files to be created (for example, C:\Users\<Username>\RippleSites\HelloGeo\Packaged). Do not use the same folder that you specified in the Project Root field.
  7. In the upper-right corner of the window, click the X to close the window and save your settings.

Now you can build and package the app.

With the Ripple emulator, you have several ways of packaging your app:
  • Package: This option builds and packages your app, and creates an unsigned .bar file. The .bar file is your app's executable file that runs on BlackBerry PlayBook tablets.
  • Package & Sign: This option builds, packages, and signs your app's .bar file, which you can deploy to a device or distribute through the BlackBerry World storefront.
  • Package & Launch: This option builds, packages, and launches your app on a BlackBerry PlayBook tablet.

Let's start with just packaging the app.

  1. Make sure that Ripple services are running. If they aren't, click the Ripple icon beside the address bar, and then click Start Ripple Services.
  2. Check your build settings.
  3. Click Package.

The Ripple emulator builds and packages your application. When the build and package process is complete, the message Build succeeded! appears. Your output appears in the output folder you specified.

Test your app on the BlackBerry PlayBook Simulator

The BlackBerry PlayBook Simulator runs in a VMware session. Before you begin, make sure that you install and configure the BlackBerry PlayBook Simulator. For more information, see Deploy to a simulator.

To test your app on the BlackBerry PlayBook Simulator, you start the simulator, then use the Ripple emulator to package, install, and launch your app on the simulator.

  1. Start the simulator. Instructions for how to start the simulator are included with the Download information.
  2. In the Ripple emulator, select the Build panel.
  3. Click Settings.
  4. Fill in the Device IP for your simulated device. To view the tablet's IP address, click the Development mode icon icon. If you do not see this icon, go to Settings > Security > Development Mode, and set the Use Development Mode switch to Yes.
  5. If you set a password for your device, type it in the PlayBook Password field.
  6. Click Package & Launch.

The Ripple emulator builds and packages your app. If the build and package process completes successfully, the message Build succeeded! appears. A .bar file is created in the output folder we specified in the settings.

After a short period of time, the BlackBerry PlayBook Simulator launches the app. The first time users run the app, they are prompted for permission to allow GPS access. After they click OK, the application starts and they can click the Get my coordinates button to retrieve their location information.

The HelloGeo app displayed in the BlackBerry PlayBook Simulator.

Last modified: 2013-08-14