1. Setting up your tools

The BlackBerry PlayBook OS SDK provides a set of tools that you can run from the command line. With just a little bit of configuration, the Ripple emulator can take care of running these commands for you. The Ripple emulator tool can also act as a local web server for your HTML5 application, and can simulate what your app looks like on a BlackBerry device. Although it's possible to develop BlackBerry WebWorks apps without using the Ripple emulator, for the introductory apps we create in the Getting Started section, we assume that you are using the Ripple emulator.

Before you begin:

• You need a text editor or IDE for creating HTML5, JavaScript, CSS, and config.xml files.

• You need to install the Google Chrome browser. (The Ripple emulator runs as a Google Chrome extension.)

1. Download the tools available on the Downloads page.

   1. Download the Ripple emulator.

   2. Download the BlackBerry PlayBook OS SDK.

   3. Download a simulator. If you have a BlackBerry device available for testing, downloading a simulator isn't essential, but you will probably find it convenient to have one.

Do symulacji użyłem VMware Workstation 10.

1. Enable the Ripple emulator.

2. Create a folder named RippleSites in one of the following locations, so that Ripple can find your app's files.

   1. Windows XP: C:\Documents and Settings\Username\RippleSites

   2. Windows 7: C:\Users\Username\RippleSites

   3. Mac OS: /Users/Username/RippleSites

1. Set up for signing by requesting code signing keys. Signing keys allow you to test your app on a device and, when you're ready, to distribute it through BlackBerry World. You don't need signing keys to work through the examples in the Getting Started section. If you request them now, you will have them ready when you need them.

   2. Enable the Ripple emulator

Before you can test your app using the Ripple emulator, you need to start Ripple services.

1. Start the Google Chrome browser.

2. Click the Ripple icon beside the address bar.

   • If you see Start Ripple Services, click it and go to the next step.

   • If you do not see Start Ripple Services, it means that you have not yet accepted the EULA for the Ripple emulator.

     1. Navigate to any page that is on a web server (not a local file). For example, you could use this page that you are reading right now.

     2. Click the Ripple icon beside the address bar, then click Enable.

     3. Review and accept the license agreement.

     4. Now when you click the Ripple icon you will be able to click Start Ripple Services. If you want Ripple to start automatically every time you start the Google Chrome browser, select the checkbox below Start Ripple Services.

     5. You can use Disable to stop displaying the current page in the emulator.

3. In the browser's address bar, type the URL or path to the landing page of your application (typically index.html). For example, try out the kitchen sink sample application at the following URL: http://blackberry.github.com/WebWorks-Samples/kitchenSink.

4. Click the Ripple icon beside the address bar, then click Enable.

5. If this is the first time you've enabled the Ripple emulator for this particular page, you will need to select the platform that your application is intended for. Select WebWorks-TabletOS. The Ripple emulator remembers this selection and loads it automatically the next time you load the same URL.

6. If you want to change the platform that you are testing with, under the Platforms panel, click the setting next to Platform, select a platform, and then click Change Platform.

Explore the other panels in the Ripple emulator to see the additional settings you can use to test your application.

Now that you've tried a ready-made application using the Ripple emulator, create your own BlackBerry WebWorks application and test it with the Ripple emulator. For more information, see:

• Creating your first app

• Tutorial: Geolocation

  1. Access your project in Ripple

If you do not have a web server set up, you can open files directly from the local file system on your computer by completing the following tasks:

1. Create a folder named RippleSites 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. Copy your project folder and all of its contents into the RippleSites folder.

3. In the address bar, type http://localhost:9910/ followed by your project folder and landing page. For example:

http://localhost:9910/HelloWorld/index.html

In Mac OS, if you have packed and launched your application by using the Package & Launch option in the Ripple emulator, the RippleSites folder is created automatically, however, you may have to change its permissions so that you can copy or move your local resources into it.

1. Features

The Ripple emulator interface includes a rich set of control panels that enable you to interact with your application as if you are using a mobile device. You can simulate a GPS location, the device accelerometer, device events, and much more.

Panel	Description
Devices	This panel enables you to quickly switch between the devices that are supported for the selected platform. You can also switch the device orientation from portrait to landscape for devices that support the functionality, so you can test your application layout for various screen sizes and orientations.
Platforms	This panel enables you to switch between platforms.
Information	This panel provides you with general information about your application, including the current platform and device that are set for the emulator.
Accelerometer	This panel enables you to simulate device rotation and movement using a three dimensional device.
Messaging	This panel enables you to type simulated SMS messages to send to the device.
Push	This panel enables you to use the BlackBerry WebWorks Push API.
Settings	This panel enables you to change Ripple-specific settings, such as the theme and tool tips display.
Device & Network Settings	This panel is specific to the platform that you are using. You can set communication transports that your application uses, device identifiers such as the IMEI or PIN, and other network settings. You can use various APIs with your application to access these settings.
Geo Location	This panel enables you to simulate changes in the physical location of the device, slow down GPS response times, simulate a GPS timeout, and change other GPS simulation settings.
Events	This panel enables you to simulate system level events that are supported in the specified platform.
Config	This panel displays information about the config.xml file for your application, and includes alerts for errors and omissions in the config.xml file.
Phone	This panel enables you to simulate various call states, such as missed or received calls.
Build	This panel enables you to specify settings for building, packaging, and signing your application.

1. 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.

2.1. 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:

4. <!DOCTYPE html>

5. <html>

6. <head>

7. <meta http-equiv="Content-Type"

8. content="text/html; charset=UTF-8">

9. <title>Hello World</title>

10. </head>

11. <body>

12. <p>Hello World!</p>

13. </body>

</html>

1. 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.

2. Create a config.xml file in your HelloWorld folder. Use the following code:

3. <?xml version="1.0" encoding="UTF-8"?>

4. <widget xmlns="http://www.w3.org/ns/widgets"

5. xmlns:rim="http://www.blackberry.com/ns/widgets"

6. version="1.0.0.0" id="HelloWorldApp">

8. <name>helloWorld</name>

9. <author>My name</author>

10. <description>The classic first app</description>

11. <icon src="images/icon.png"/>

12. <content src="index.html"/>

</widget>

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

2. 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.

2. 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.

2. 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.

2. 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.

   • 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 IP Address for your simulated device. In the BlackBerry PlayBook Simulator, to view the IP address, click the 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.