Package and launch your app

Just a few steps left to get your app up and running!

In this section:

Create your config.xml file

The BlackBerry WebWorks config.xml file contains the information needed for your app to run on a BlackBerry PlayBook. It provides information such as:

  • Application namespace
  • Name of the app
  • Application permissions
  • The start page
  • The icons used in the app
  • Additional 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: 

<?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>read_geolocation</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 (include if you are referring to 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 name element specifies the name of your app. The name is displayed when the application icon is viewed on the home screen of the BlackBerry device. 
<name>Hello Geo</name>
The author element specifies the name of the person or company that authored the app. 
<author>My name</author>
The description element describes the app. This description is displayed in the application listing, under Options. 
<description>Geolocation display</description>
The icon element specifies the icon for the app that is displayed 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 source to be the index.html file. 
<content src="index.html"/>
The rim:permissions element specifies the permissions for various features in the BlackBerry WebWorks app. For the HelloGeo app, we added the rim:permit element with the read_geolocation permission, so that the app can read the current GPS location of the device. 
<rim:permissions>  
    <rim:permit>read_geolocation</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.

With the config.xml file saved, you can now build and package your app.

Configure build settings in Ripple

You can use the Ripple emulator to build and package your application. The Ripple emulator zips your project files, packages them, and creates an executable file to run on the BlackBerry PlayBook. To build and package your app, you must first configure the build settings.

If your operating system is Windows 7 or Windows Vista, you may need to ensure that bbwp and java are running with administrator access. Otherwise, these executables will not have access to run, and you will encounter errors when you try to build your BlackBerry WebWorks application.

  1. In the Ripple emulator, select the Build panel.
  2. Select Settings.
  3. In the SDK Path field, type the location where the BlackBerry Tablet 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 we’ve associated with the .zip file.
  6. In the Output Folder field, type the location where you want the output to be created (for example, C:\Users\<Username>\RippleSites\HelloGeo\Packaged). This location cannot be the same as the Project Root folder.
  7. In the top-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 three ways of packaging:
  • Package: This option builds and packages your app, creating an unsigned .bar file. The .bar file is your application's executable file that runs on the BlackBerry PlayBook.
  • Package & Sign: This option builds, packages, and signs your application's executable 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.

In this tutorial, we’ll package and launch the app on the BlackBerry Tablet Simulator.

Launch on the BlackBerry Tablet Simulator

The BlackBerry Tablet Simulator runs in a VMware session. Before you begin, make sure that you have installed and configured the BlackBerry Tablet Simulator. For more information, see Deploy to a BlackBerry tablet simulator.

To launch your app on the BlackBerry Tablet Simulator, you will start the simulator, then use Ripple to launch your app on the simulator.

  1. Start the simulator.
  2. In the Ripple emulator, select the Build panel.
  3. Click Settings.
  4. Fill in the Device IP for your simulated device
    • You can view the tablet's IP address by clicking the Image of Development Mode icon icon. If you do not see this icon, go to Settings > Security > Development Mode and set Use Development Mode to Yes.
  5. If you have 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! is displayed. A .bar file is created in the output folder we specified in the settings.

After a moment, the BlackBerry Tablet 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 retrieve their location information by clicking the Get my coordinates button.

This image shows the BlackBerry PlayBook version of the HelloGeo app.