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 it will allow you to verify that you have successfully installed the tools and configured them correctly.

Whether you are creating a BlackBerry WebWorks app for BlackBerry 10 devices, the BlackBerry PlayBook, or BlackBerry 7 and earlier devices, the high level steps are the same.

You will learn to:

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

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

Create the application files

The application files need to be created 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:
    • Windows XP: C:\Documents and Settings\<Username>\RippleSites
    • Windows 7: C:\Users\<Username>\RippleSites
    • Mac OS: /Users/<Username>/RippleSites
  2. Within the RippleSites folder, create a folder named HelloWorld.
  3. Create an index.html file in your HelloWorld folder. This will be 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 go to package your app, we will need an icon.png file to use display on the device. Within your HelloWorld folder, create an images folder. 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 program</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 the application in the Ripple emulator

  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, substituting 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. Once the page is finished loading, click the Ripple icon next to the address bar.
  4. Click Enable.
  5. Select the platform you wish to use.
    • For BlackBerry 10, select BlackBerry 10 WebWorks.
    • For BlackBerry PlayBook, select WebWorks-TabletOS.
    • For BlackBerry 7 and earlier, select WebWorks.

    You can change the platform using the Platforms panel. If the panel is not visible, click the tiny arrow in the top-left corner of the screen. Select your desired platform, then click Change Platform.

    You can switch devices within a platform by using the Devices panel.

The Ripple emulator shows your app as it would appear on the platform you selected. Here is an example showing how it would look if you selected BlackBerry PlayBook.

This image shows the output of HelloWorld in the Ripple emulator for the BlackBerry PlayBook

Configure your build settings

The Ripple emulator can make calls to the BlackBerry WebWorks SDK on your behalf once you provide it with a few pieces of information, such as the location of the SDK and your application's files. This saves you having to type commands at a command prompt. The Ripple emulator also shows you what your app will look like on a device.

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. Click Settings.
  3. In the SDK Path field, type the location where the BlackBerry WebWorks SDK is installed. If you have more than one SDK installed, be sure to select the one that corresponds to the platform you currently have selected in Ripple. The default locations are:
    • For BlackBerry 10 OS:
      • 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>
    • For BlackBerry PlayBook OS:
      • 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>
    • For BlackBerry 7 and earlier:
      • Windows XP: C:\Program Files\Research In Motion\BlackBerry WebWorks SDK <version>
      • Windows 7: C:\Program Files (x86)\Research In Motion\BlackBerry WebWorks SDK <version>
      • Mac OS: /Developer/SDKs/Research In Motion/BlackBerry WebWorks SDK <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. This is the name of the .zip file that will contain your application's files. (Do not type the .zip extension.)
  6. In the Output Folder field, type the location where you want the output to be created. For example, C:\Users\username\RippleSites\HelloWorld\Packaged. Note that you cannot use the same folder as you used for Project Root.
  7. In the top right corner of the window, click the X to close the window and save your settings.
This is what the Build Settings panel looks like if you chose BlackBerry 10 as your platform. The appearance is similar for other platforms.

This image shows the Ripple Build Settings panel as it appears when BlackBerry 10 WebWorks has been selected as the platform

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 three choices when packaging your app:

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

Ripple 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. Ensure that Ripple services are running.
  2. Check your build settings.
  3. Click Package.

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

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

The .bar files for BlackBerry 10 and BlackBerry PlayBook are not interchangeable. Be sure you have selected the correct platform.

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

Test your app

The steps needed to test your app vary depending on which platform (BlackBerry 10, BlackBerry PlayBook, or BlackBerry 7 and earlier) you are using, as well as whether you are testing in a simulator or using an actual device.

If you selected BlackBerry 10 or BlackBerry PlayBook as your platform and installed the relevant simulator in the Setting up your tools step, Ripple 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. If you are working with BlackBerry 10, set the Target field to Simulator.
  5. Fill in the IP Address for your simulated device:
    • For BlackBerry 10, the IP address appears in the lower left corner of the simulator screen.
    • For BlackBerry PlayBook, 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. The icon will now appear, allowing you to view the IP address.
  6. Click X to close the Settings panel and save your changes.
  7. Click Package & Launch.

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