Creating your first app

For your first BlackBerry WebWorks app, we'll stick with the classic, Hello World. It doesn't use JavaScript or BlackBerry WebWorks APIs, but you can verify that you successfully installed the tools and configured them correctly.

You will learn to:

  • Create index.html and config.xml files
  • View the app in the Ripple emulator
  • Configure your build settings in the Ripple emulator
  • Package your application using the Ripple emulator
  • Test your application in an emulator or on a device

Before you start, make sure you have the necessary tools installed. Refer to Setting up your tools, if necessary.

Create the application files

You need to create your application files where the Ripple emulator can find them.

  1. Navigate to your RippleSites folder. As a reminder, you created it in one of the following locations when you set up your tools:
    • Windows XP: C:\Documents and Settings\<Username>\RippleSites
    • Windows 7: C:\Users\<Username>\RippleSites
    • Mac OS: /Users/<Username>/RippleSites
  2. In your RippleSites folder, create a folder named HelloWorld.
  3. In your HelloWorld folder, create an index.html file. This file is the landing page for your app. Use the following code:
    <!DOCTYPE html> 
    <html> 
        <head> 
            <meta http-equiv="Content-Type" 
                  content="text/html; charset=UTF-8"> 
            <title>Hello World</title> 
        </head> 
        <body> 
            <p>Hello World!</p> 
        </body> 
    </html>
  4. When we package your app, we will need an icon.png file to display on the BlackBerry device. In your HelloWorld folder, create a folder named images. Download icon.zip and extract the icon.png file to the images folder.
  5. Create a config.xml file in your HelloWorld folder. Use the following code:
    <?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="HelloWorldApp">   
       
        <name>helloWorld</name> 
        <author>My name</author>
        <description>The classic first app</description>
        <icon src="images/icon.png"/>
        <content src="index.html"/> 
    
    </widget>

To learn more about the config.xml file, see Create your config.xml file.

View your app in the Ripple emulator

The Ripple emulator can act as a local web server for your HTML5 app and can simulate what your app will look like on a BlackBerry device.

  1. Open the Google Chrome browser and 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. Enter the URL for your Hello World landing page. Substitute http://localhost:9910 for the first part of the file path, up to and including /RippleSites (for example, http://localhost:9910/HelloWorld/index.html).
  3. When the page is finished loading, click the Ripple icon beside the address bar.
  4. Click Enable.
  5. When you are asked to select a platform, select WebWorks-TabletOS

The Ripple emulator shows your app as it would appear on the platform you selected.

This image shows the Hello World app as it appears in Ripple when the WebWorks-TabletOS is selected.

Configure your build settings

In the previous section, you used the Ripple emulator to see what your app will look like on a BlackBerry device. With a little bit of configuration, the Ripple emulator can also package your app. The Ripple emulator makes calls to the BlackBerry PlayBook OS SDK on your behalf, so you don't need to type commands at a command prompt. You need to provide the Ripple emulator with the location of the SDK and your app's files.

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

  1. In the Ripple emulator, select the Build panel.
  2. Click 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 HelloWorld folder (for example, C:\Users\username\RippleSites\HelloWorld).
  5. In the Archive Name field, type HelloWorld. The Ripple emulator will use this name when it creates the .zip file that contains your app's files. (Do not type the .zip extension.)
  6. In the Output Folder field, type the location where you want the output files to be created (for example, C:\Users\username\RippleSites\HelloWorld\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 icon to close the window and save your settings.
This is what the Build Settings panel looks like.

This image shows the Ripple Build Settings panel.

Package your app

When you build and package your app, you create an executable file that runs on a BlackBerry device.

The Ripple emulator gives you several choices when packaging your app:

  • Package: This option builds and packages your app, and creates an unsigned executable file that you can install on a BlackBerry device for testing.
  • Package & Sign: This option builds, packages, and signs your app, and creates an executable file that you can deploy to a BlackBerry device or distribute through BlackBerry World.
  • Package & Launch: This option builds and packages your app and launches it on a simulator.

The Ripple emulator makes calls to the BlackBerry WebWorks SDK, so be sure you have the appropriate SDK installed for your platform. Refer to Setting up your tools.

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.

The type of output files that the Ripple emulator builds depends on the choice you made in the Platforms panel. If you selected BlackBerry 10 WebWorks or WebWorks-TabletOS, the Ripple emulator generates a .bar file.

The .bar files for BlackBerry 10 OS and BlackBerry PlayBook OS are not interchangeable. Be sure to select the correct platform.

For more information, including how to package your app from the command line instead of using the Ripple emulator, see Preparing to package.

Test your app

If you install the relevant simulator in the Setting up your tools step, the Ripple emulator makes it straightforward to test your app in the simulator.

  1. Start the simulator.
  2. In the Ripple emulator, select the Build panel.
  3. Click Settings.
  4. Fill in the IP Address for your simulated device. In the BlackBerry PlayBook Simulator, to view the 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. Click the X icon to close the Settings panel and save your changes.
  6. Click Package & Launch.

For information about other testing options, including testing on a BlackBerry device, see Packaging & Testing.

Last modified: 2013-08-14