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 10 device 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 10 device.

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 10 WebWorks SDK is installed. The default locations are:
    • Windows XP: C:\Program Files\Research In Motion\BlackBerry 10 WebWorks SDK <version>
    • Windows 7: C:\Program Files\Research In Motion\BlackBerry 10 WebWorks SDK <version>
    • Mac OS: /Developer/SDKs/Research In Motion/BlackBerry 10 WebWorks SDK <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 10 devices.
  • 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 10 device.

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 10 Device Simulator

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

To test your app on the BlackBerry 10 Device 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. In the Target field, choose Simulator.
  5. Fill in the Device IP for your simulated device. The IP address appears in the lower-left corner of the BlackBerry 10 Device Simulator.
  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 10 Device 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 10 Device Simulator.

Last modified: 2014-03-10



Got questions about leaving a comment? Get answers from our Disqus FAQ.

comments powered by Disqus