Develop Playbook applications using WebWorks Tablet OS SDK + Ripple

RIM is offering a Free Playbook (official page located here) to anyone who develops and submits an Playbook app before the 13th of February.Looks like you can use any tool (Web SDK, AIR, Android port).

It took me an hour or so to get the development environment setup. This article aims to simplify the process of setting up a Playbook Development environment

When finished here, see Part 2 which covers how to port an HTML / Javascript / CSS app to the Playbook and build it using the Ripple emulator.

Notes:

• Sign up for a Blackberry App World account (us.blackberry.com)
• They need either a notarized document or government issued ID for validation
• This process takes a few days to complete, so it's best to start early
   
• Sign up for an Oracle account to download the Java SDK (oracle.com)
• Download page for Java SE SDK (oracle.com)
  
  
• Blackberry API reference (blackberry.com)
• Getting Started guide (blackberry.com)
  
  
• Adobe Air SDK Download (adobe.com)
• Blackberry Tablet WebWorks SDK Download (blackberry.com)
• Ripple Emulator Download page (blackberry.com)
• Fix scrambled text issue (supportforums.blackberry.com)
• Test apps from Local File system (blackberry.com)
   
• Apache HTTP Server for testing apps with Ripple (apache.org)

Step 1: Install Prerequisite software

Download and install the following Pre-requisite software:

• Adobe AIR SDK needs to be decompressed somewhere (I picked c:\source\AdobeAirSDK)
• Blackberry WebWorks SDK for tablets should be installed next. It depends on Adobe AIR.
• Oracle Java SDK requires an Oracle account before you can download.
• Install an HTTP Server (IIS / IIS Express / Apache / etc...). This lets you test your apps with Ripple.
• If you use Apache on Windows 7 you can place your apps in this directory: C:\Program Files (x86)\Apache Software Foundation\Apache2.2\htdocs
• Depending on what other servers you have installed, port 80 may be taken. During the install of your webserver, be sure to pick an open port (in my case port 8080 was open)
   
• The Ripple Emulator should be installed last.
• There is a way to test apps without Apache or another HTTP server. I haven't tried it, though.

Note: If you see garbled text, garbage characters or a scrambled image when running the Ripple emulator be sure to disable hardware graphics acceleration in the ripple config file. The problem will be immediately apparent if you are affected.

Steps to disable hardware acceleration for Ripple:

1. Open windows explorer and browse to %APPDATA%\Research in Motion\Ripple
2. Open the config.ini file
3. Change enableHardwareAcceleration to equal 0 and save. Here is what my config file looks like (note the second line from the bottom):
   
   
   
4. Re-launch Ripple. Everything should be usable now.

Step 2: Create & run the Sample Application

RIM has a basic application available for reference purposes. You can find it here. I'll step through building the app assuming that Apache is installed locally using port 8080.

1. Create a directory named HelloWorld under C:\Program Files (x86)\Apache Software Foundation\Apache2.2\htdocs
    
2. Create a file named index.html inside the "HelloWorld" folder and save the following HTML/Javascript inside it:
   
   

   < !DOCTYPE html>
   < html>
   < head>
      < meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
      < meta name="viewport" content="width=device-width,height=device-height,user-scalable=no,initial-scale=1.0">
      < title> Hello World </title>
   < /head>
   < body>
      < p>Hello World</p>
   < /body>
   < /html>

   Note: You will need to remove spaces from the tags. Concrete5 doesn't just let me place html in as text...
   
   
3. Create a file named config.xml and save the following XML inside it:
   
   

   < ?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" rim:header="WebWorks Sample">
   
      < name>Hello World</name>
      < description>This is a sample application.</description>
      < content src="index.html"/>
   
   < /widget>

   
   Note: You can change this file to include additional tags
   Note 2: You will need to remove the spaces from the tags (concrete5 issue)
   
   
4. Open the Ripple emulator. If this is your first time running it, it will ask you what platform you want to emulate. Be sure to pick WebWorks-TabletOS!
    
5. When I first ran the emulator it was not apparent how to open application for testing. The Blackberry documentation just says to (Open your index.html file in the Ripple Emulator). You can open your sample application by browsing to http://localhost:8080/HelloWorld/ using the address bar at the top of the Ripple window (See red-underlined area in the screenshot below) and pressing Enter.
   
6. You should see the "HelloWorld" app run and display a Javascript message box. 

Going Forward, you will be able test applications by creating folders for each app in the Apache htdocs root folder (listed in step 1 above)

You can also try Packaging and building your app (I haven't got that far yet. Need my BB Dev account)

UPDATE: Part 2 of the series covers how to port an existing "HTML" App to WebWorks SDK for Playbook and build it using the Ripple emulator.