blackberry playbook tablet creating your first application module 3

8/22/2019 BlackBerry PlayBook Tablet Creating Your First Application Module 3

1/32

BlackBerry HTML5WebWorksApplications for theBlackBerry

PlayBook TabletModule 3 - Writing YourFirst Application for theBlackBerry PlayBookTablet


2/32

BlackBerry HTML5 WebWorks Applications

2 2012 Research In Motion Limited Module 3 Writing the First Applicationv0.01


3/32

Bl ackBer r y HTML5 WebWor ks Appl i cat i ons

Module 3 Writing the First Application 2012 Research In Motion Limited 3v0.01

2012 Research In Motion Limited. All rights reserved. BlackBerry, RIM, Research In Motion, SurePress, SureType and

related trademarks, names and logos are the property of Research In Motion Limited and are registered and/or used in the U.S. and

countries around the world.

Ripple is a trademark of tinyHippos, Inc.; JavaScript is a trademark of Oracle America, Inc.; Dropbox is a trademark of Dropbox, Inc.

Corporation.; WinZip is a Registered Trademark of WinZip International LLC.; VMware is a trademark of VMware, Inc.; Windows is a

trademark of Microsoft Corporation.; Mac OS is a trademark of Apple Inc. Google Chrome is a trademark of Google Inc.; Mozilla andFirefox are trademarks of Mozilla Foundation.; Web Inspector is a trademark of Wintriss Engineering Corporation. All other

trademarks are the property of their respective owners.

This documentation including all documentation incorporated by reference herein such as those provided or made available by

hyperlink is provided or made accessible "AS IS" and "AS AVAILABLE" and without condition, endorsement, guarantee,

representation or warranty of any kind by Research In Motion Limited and its affiliated companies ("RIM") and RIM assumes no

responsibility for any typographical, technical, or other inaccuracies, errors or omissions in this documentation. In order to protect

RIM proprietary and confidential information and/or trade secrets, this documentation may describe some aspects of RIM

technology in generalized terms. RIM reserves the right to periodically change information that is contained in this documentation;

however, RIM makes no commitment to provide any such changes, updates, enhancements, or other additions to this

documentation to you in a timely manner or at all.

This documentation might contain references to third-party sources of information, hardware or software, products or services

including components and content such as content protected by copyright and/or third-party web sites (collectively the "Third Party

Products and Services" ). RIM does not control, and is not responsible for, any Third Party Products and Services including, withoutlimitation the content, accuracy, copyright compliance, compatibility, performance, trustworthiness, legality, decency, links, or any

other aspect of Third Party Products and Services. The inclusion of a reference to Third Party Products and Services in this

documentation does not imply endorsement by RIM of the Third Party Products and Services or the third party in any way.

EXCEPT TO THE EXTENT SPECIFICALLY PROHIBITED BY APPLICABLE LAW IN YOUR JURISDICTION, ALL CONDITIONS,

ENDORSEMENTS, GUARANTEES, REPRESENTATIONS, OR WARRANTIES OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING WITHOUT

LIMITATION, ANY CONDITIONS, ENDORSEMENTS, GUARANTEES, REPRESENTATIONS OR WARRANTIES OF DURABILITY, FITNESS

FOR A PARTICULAR PURPOSE OR USE, MERCHANTABILITY, MERCHANTABLE QUALITY, NON-INFRINGEMENT, SATISFACTORY

QUALITY, OR TITLE, OR ARISING FROM A STATUTE OR CUSTOM OR A COURSE OF DEALING OR USAGE OF TRADE, OR RELATED TO

THE DOCUMENTATION OR ITS USE, OR PERFORMANCE OR NON-PERFORMANCE OF ANY SOFTWARE, HARDWARE, SERVICE, OR

ANY THIRD PARTY PRODUCTS AND SERVICES REFERENCED HEREIN, ARE HEREBY EXCLUDED. YOU MAY ALSO HAVE OTHER RIGHTS

THAT VARY BY STATE OR PROVINCE. SOME JURISDICTIONS MAY NOT ALLOW THE EXCLUSION OR LIMITATION OF IMPLIED

WARRANTIES AND CONDITIONS. TO THE EXTENT PERMITTED BY LAW, ANY IMPLIED WARRANTIES OR CONDITIONS RELATING TO

THE DOCUMENTATION TO THE EXTENT THEY CANNOT BE EXCLUDED AS SET OUT ABOVE, BUT CAN BE LIMITED, ARE HEREBY

LIMITED TO NINETY (90) DAYS FROM THE DATE YOU FIRST ACQUIRED THE DOCUMENTATION OR THE ITEM THAT IS THE SUBJECTOF THE CLAIM.

TO THE MAXIMUM EXTENT PERMITTED BY APPLICABLE LAW IN YOUR JURISDICTION, IN NO EVENT SHALL RIM BE LIABLE FOR ANY

TYPE OF DAMAGES RELATED TO THIS DOCUMENTATION OR ITS USE, OR PERFORMANCE OR NON-PERFORMANCE OF ANY

SOFTWARE, HARDWARE, SERVICE, OR ANY THIRD PARTY PRODUCTS AND SERVICES REFERENCED HEREIN INCLUDING WITHOUT

LIMITATION ANY OF THE FOLLOWING DAMAGES: DIRECT, CONSEQUENTIAL, EXEMPLARY, INCIDENTAL, INDIRECT, SPECIAL,

PUNITIVE, OR AGGRAVATED DAMAGES, DAMAGES FOR LOSS OF PROFITS OR REVENUES, FAILURE TO REALIZE ANY EXPECTED

SAVINGS, BUSINESS INTERRUPTION, LOSS OF BUSINESS INFORMATION, LOSS OF BUSINESS OPPORTUNITY, OR CORRUPTION OR

LOSS OF DATA, FAILURES TO TRANSMIT OR RECEIVE ANY DATA, PROBLEMS ASSOCIATED WITH ANY APPLICATIONS USED IN

CONJUNCTION WITH RIM PRODUCTS OR SERVICES, DOWNTIME COSTS, LOSS OF THE USE OF RIM PRODUCTS OR SERVICES OR

ANY PORTION THEREOF OR OF ANY AIRTIME SERVICES, COST OF SUBSTITUTE GOODS, COSTS OF COVER, FACILITIES OR SERVICES,

COST OF CAPITAL, OR OTHER SIMILAR PECUNIARY LOSSES ,WHETHER OR NOT SUCH DAMAGES WERE FORESEEN OR

UNFORESEEN, AND EVEN IF RIM HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.

TO THE MAXIMUM EXTENT PERMITTED BY APPLICABLE LAW IN YOUR JURISDICTION, RIM SHALL HAVE NO OTHER OBLIGATION,

DUTY, OR LIABILITY WHATSOEVER IN CONTRACT, TORT, OR OTHERWISE TO YOU INCLUDING ANY LIABILITY FOR NEGLIGENCE OR

STRICT LIABILITY.

THE LIMITATIONS, EXCLUSIONS, AND DISCLAIMERS HEREIN SHALL APPLY: (A) IRRESPECTIVE OF THE NATURE OF THE CAUSE OF

ACTION, DEMAND, OR ACTION BY YOU INCLUDING BUT NOT LIMITED TO BREACH OF CONTRACT, NEGLIGENCE, TORT, STRICT

LIABILITY OR ANY OTHER LEGAL THEORY AND SHALL SURVIVE A FUNDAMENTAL BREACH OR BREACHES OR THE FAILURE OF THE

ESSENTIAL PURPOSE OF THIS AGREEMENT OR OF ANY REMEDY CONTAINED HEREIN; AND (B) TO RIM AND ITS AFFILIATED

COMPANIES, THEIR SUCCESSORS, ASSIGNS, AGENTS, SUPPLIERS (INCLUDING AIRTIME SERVICE PROVIDERS), AUTHORIZED RIM


4/32



DISTRIBUTORS (ALSO INCLUDING AIRTIME SERVICE PROVIDERS) AND THEIR RESPECTIVE DIRECTORS, EMPLOYEES AND

INDEPENDENT CONTRACTORS.

IN ADDITION TO THE LIMITATIONS AND EXCLUSIONS SET OUT ABOVE, IN NO EVENT SHALL ANY DIRECTOR, EMPLOYEE, AGENT,

DISTRIBUTOR, SUPPLIER, INDEPENDENT CONTRACTOR OF RIM OR ANY AFFILIATES OF RIM HAVE ANY LIABILITY ARISING FROM OR

RELATED TO THE DOCUMENTATION.

Prior to subscribing for, installing or using any Third Party Products and Services it is your responsibility to ensure that your airtimeservice provider has agreed to support all of their features. Some airtime service providers may not offer Internet browsing

functionality with a subscription to BlackBerry Internet Service. Check with your service provider for availability, roaming

arrangements, service plans and features. Installation or use of Third Party Products and Services with RIM's products and services

may require one or more patent, trademark, copyright or other licenses in order to avoid infringement or violation of third party

rights. You are solely responsible for determining whether to use, Third Party Products and Services and if any third party licenses are

required to do so. If required you are responsible for acquiring them. You should not install or use Third Party Products and Services

until all necessary licenses have been acquired. Any Third Party Products and Services that are provided with RIM's products and

services are provided as a convenience to you and are provided "AS IS" with no express or implied conditions, endorsements,

guarantees, representations or warranties of any kind by RIM and RIM assumes no liability whatsoever, in relation thereto. Your use

of Third Party Products and Services shall be governed by and subject to you agreeing to the terms of separate licenses and other

agreements applicable thereto with third parties, except to the extent expressly covered by a license or other agreement with RIM.

Certain features outlined in this documentation require a minimum version of BlackBerry Enterprise Server software, BlackBerry

Desktop Software, and/or BlackBerry Device Software and may require additional development or Third Party Products and

Services for access to corporate applications.

This product includes software developed by the Apache Software Foundation (http://www.apache.org/) and/or licensed pursuant to

Apache License, Version 2.0 (http://www.apache.org/licenses/). For more information, see the NOTICE.txt file included with the

software. Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS

IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific

language governing permissions and limitations under the License.

The terms of use of any RIM product or service are set out in a separate license or other agreement with RIM applicable thereto.

NOTHING IN THIS DOCUMENTATION IS INTENDED TO SUPERSEDE ANY EXPRESS WRITTEN AGREEMENTS OR WARRANTIES

PROVIDED BY RIM FOR PORTIONS OF ANY RIM PRODUCT OR SERVICE OTHER THAN THIS DOCUMENTATION.


5/32



About this lab manualThis material was designed under the assumption that all required prerequisites are completed by

participants before attempting these exercises.

To avoid negatively impacting the quality of the learning experience, RIM recommends studentscomplete the prerequisites.


6/32



ContentsAbout this lab manual ................................................... 5Overview ............................................................. 7

Objectives . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7Recommended Prerequisites. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7Software Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7

Creating an .html File.................................................... 9Creating an icon for the application........................................ 10Creating the Configuration Document config.xml ........................... 11Compiling an HTML5 WebWorks Application ................................ 13

Creating an Archive. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13Figure 3: Output folder . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14

Packaging an application for Deployment on the Simulator ..................... 15Compiling and Packaging Using the Ripple Emulator.......................... 18

Accessing Files from a Local File System Using Ripple . . . . . . . . . . . . . . . . . . . . . . . . 18Accessing a Project File from a Remote Web Server Using Ripple . . . . . . . . . . . . . . . . 19Ripple Emulator Packaging Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21Optional Packaging Settings in the Ripple Emulator . . . . . . . . . . . . . . . . . . . . . . . . . . 23Packaging an Application using the Ripple Emulator . . . . . . . . . . . . . . . . . . . . . . . . . . 24

Deploying the Application to the Tablet Simulator Using the Command Prompt...... 25Deploying the Application to the Tablet Simulator using the Ripple Emulator ....... 30Summary and Further Learning ........................................... 31

Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31Further Learning . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31Additional Resources. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31


7/32



Overview

ObjectivesIn this module the learner will be introduced to:

Creating an index.html file for an application

Leveraging an existing graphic for an icon for the application

Creating a config.xml file for an application

Packaging the application files using the BlackBerry WebWorks Packager into a .bar fileusing the command prompt

Accessing a Project File from a Remote Web Server in the Ripple Emulator for viewing theapplication

Packaging an application using the Ripple Emulator

Deploying the application on the BlackBerry Playbook simulator using the command prompt

Packaging and launching the application on the BlackBerry PlayBook simulator using theRipple Emulator

Recommended Prerequisites

For this module, the recommended prerequisite skills and areas of knowledge are:

Knowledge of web standards such as HTML, CSS and JavaScript

Experience using the Windows Command Prompt tool

Experience with using an application to create a .zip file

Software Requirements

In order to complete this module, the following are required:

An HTML editor (such as Notepad)

The icon.png file from the sample code folder

The index.html and config.xml files from the sample code folder

An application that can create .zip files such as WinZip

Installation of the BlackBerry WebWorks SDK

Installation of the BlackBerry PlayBook Simulator (using VMWare)

Installation of the Ripple Emulator software

Access to a Remote Web Server (such asDropbox)
http://www.dropbox.com/http://www.dropbox.com/http://www.dropbox.com/http://www.dropbox.com/


8/32



The icon.png file is a graphical image that can be used as the icon for the application students willbuild. This icon will appear on the BlackBerry PlayBook home screen on the BlackBerry PlayBook

Simulator.

If WinZip is not installed on the local host computer, an open source application such as 7-zip can bedownloaded and used. 7-zip can be downloaded fromhttp://www.7-zip.org/

To test the application, the BlackBerry PlayBook Simulator must be installed prior to this module.Installation instructions along with the recommended hardware and software requirements areincluded in Module 2. Likewise, instructions for the installation of the Ripple Emulator software canalso be found in Module 2.

A Dropbox account for this module can be created free of charge atwww.dropbox.com
http://www.7-zip.org/http://www.7-zip.org/http://www.7-zip.org/http://www.dropbox.com/http://www.dropbox.com/http://www.dropbox.com/http://www.dropbox.com/http://www.7-zip.org/


9/32



Creating an .html FileTo begin building the Hello World application, open a text editor such as Notepad to create a new file.This file will contain the content of the application. This file will be saved as an .html file.

In the new file, add the HTML code:

After adding the HTML code as the content for this file, save this file as index.html.

body { f ont - si ze: 5em; }

Hel l o Wor l d


10/32



Creating an icon for the applicationIn order to make an application accessible to users, it should have an icon that users can click on fromthe home screen of the tablet to start the application.

Icons can leverage either an existing graphic or be custom created using a graphics editing software (ex:Adobe Photoshop), re-use images from your own web site or from a royalty free images database online(ex: iStockphoto.com). Another option is to create your own icon using an application such asIconMaker for BlackBerry PlayBook

If creating or leveraging an existing graphic for an icon, the following are the recommended dimensionsand file formats:

Recommended dimensions : 86 x 86 pixels

Recommended file format: PNG

For this module, we will use the icon.png graphic that is included in the sample code folder with thismodule.

Figure 1: Hello World icon icon.png
http://www.orison.biz/apps/playbook-icon-maker/http://www.orison.biz/apps/playbook-icon-maker/http://www.orison.biz/apps/playbook-icon-maker/http://www.orison.biz/apps/playbook-icon-maker/http://www.orison.biz/apps/playbook-icon-maker/http://www.orison.biz/apps/playbook-icon-maker/


11/32



Creating the Configuration Documentconfig.xml

The BlackBerry HTML5 WebWorks configuration document is an .xml file that contains the elementsto define the BlackBerry HTML5 WebWorks application namespace, the name of the application,application permissions, the start page, and the icons to use for the application. It also contains theelements to define information such as the author, and email address and other configuration settings.The configuration document contains the widget element at its root. The widget element provides acontainer for all other elements. The configuration document is an XML document based onW3Cspecifications.

The config.xml file contains elements to define the:

Application namespace and name of the application

Application permissions

Start page

Icon to use for the application

Name of the applications developer

Other configuration settings (such as network transport priority, start-up options, etc)

The config.xml document also defines additional configurations settings such as network transportpriority, start-up options, license information, etc. A full listing can be found atBlackBerry DevelopersBlog.

To create the config.xml document, open a text editor such as Notepad and create a new file.

Once the new file is open, add the following XML content to the file:

Hel l o Wor l d
http://www.w3.org/TR/widgets/http://www.w3.org/TR/widgets/http://www.w3.org/TR/widgets/http://www.w3.org/TR/widgets/https://bdsc.webapps.blackberry.com/html5/documentation/ww_developing/working_with_config_xml_file_1866970_11.htmlhttps://bdsc.webapps.blackberry.com/html5/documentation/ww_developing/working_with_config_xml_file_1866970_11.htmlhttps://bdsc.webapps.blackberry.com/html5/documentation/ww_developing/working_with_config_xml_file_1866970_11.htmlhttps://bdsc.webapps.blackberry.com/html5/documentation/ww_developing/working_with_config_xml_file_1866970_11.htmlhttps://bdsc.webapps.blackberry.com/html5/documentation/ww_developing/working_with_config_xml_file_1866970_11.htmlhttps://bdsc.webapps.blackberry.com/html5/documentation/ww_developing/working_with_config_xml_file_1866970_11.htmlhttp://www.w3.org/TR/widgets/http://www.w3.org/TR/widgets/


12/32



When creating a config.xml file for an HTML5 WebWorks application, you must assign the namespacefor the BlackBerry HTML5 WebWorks application to the widget element. If the namespace is missing,

the application archive is not valid. The application namespace isht t p: / / www. w3. or g/ ns/ wi dget s

The namespace for BlackBerry HTML5 WebWorks extensions is not optional. The namespace for

BlackBerry specific application extensions is xml ns: r i m

The config.xml file defines the visual characteristics of the application. For example, in the followingXML code:

The tags highlighted in red indicate the visual characteristics of the application: the application name(Hello World) and its graphic (the icon.png graphic).

Figure 2: Hello World icon

Hel l o Wor l d


13/32



Compiling an HTML5 WebWorksApplication

After creating an index.hml, config.xml and an icon, a basic HTML5 WebWorks application can becreated and loaded onto the BlackBerry PlayBook simulator. Before loading the application onto theBlackBerry PlayBook simulator or Tablet, the files must be compiled into a .bar file.

When compiling a BlackBerry WebWorks application, the BlackBerry WebWorks Packager performsthe following actions:

Validates the contents of the BlackBerry HTML5 WebWorks archive file

Creates the output target folder and cleans up any old files (if necessary)

Creates the source target folder (if specified) and cleans up any old files (if necessary)

Creating an ArchiveA BlackBerry HTML5 WebWorks archive is a .zip file you can create with any zip archiving tool, which

is then compiled using the BlackBerry WebWorks Packager command line tool (bbwp) to create theapplication.

The application archive contains the following resources:

configuration document (.xml file)

start page (.html or other files)

application icons (.png file)

other resources and objects that are referenced in your app

The name of the .zip archive file must not be longer than 10 characters (not including the .zipextension). If you have previously submitted the application to BlackBerry App World, you cannotchange the .zip file name for subsequent releases; it must remain the same. If the .zip file name has beenchanged, an attempt to upgrade the application will not succeed.

You should not place any of your application's source files, or your application's archive file in theBlackBerry WebWorks Packager installation folder. When compiling an application using the bbwpcommand line tool, the default output folder created is "bin" which will attempt to overwrite the

BlackBerry WebWorks SDK's "bin" directory which contains critical files.

To create the archive .zip file, use the following steps:

1. Create a folder to store the files

C:\myapp


14/32



Save the config.xml, index.html and icon.png to this folder

2. Save both the index.html and config.xml and icon.png as a .zip file

Rename the .zip file to hw.zip

3. Create a second folder in the C:\myapp directory called output

C:\myapp\output

You will need the C:\myapp\output folder when the application is compiled. When the application iscompiled using the BlackBerry WebWorks Packager, a .bar file will be provided that will be stored inthe output folder. This .bar file will be deployed on the Tablet.

Figure 3: Output folder


15/32



Packaging an application for Deploymenton the Simulator

Once the archive has been created, the HTML5 WebWorks application can be compiled and packagedfor deployment. To deploy the application on the BlackBerry Tablet simulator, it must be packaged as a.bar file. The first method that can be used for packaging an HTML5 WebWorks application is using

the Windows Command Line Prompt tool and the BlackBerry WebWorks Packager (bbwp.exe).

To access the Command Line Prompt on a Windows OS computer, click the Start menu Runcmd(hit Enter key)

To use the Command Line Prompt, type:

cd C:\Program Files\Research In Motion\BlackBerry HTML5 WebWorks SDK for TabletOS

2.2.0.5\bbwp

Compile the application by using the following syntax:

bbwp C:\myapp\hw.zip o C:\myapp\output

Figure 4: Packaging an application for deployment


16/32



If the compilation was successful, a .bar file will be created in the C:\myapp\output folder if the oparameter value is specified. If no o parameter is specified, the .bar file is created in a subfolder

called bin that is located in the C:\myapp folder.

Figure 5: Packaging an application for deployment


17/32



Figure 6: .bar file created in specified directory

If the application was compiled correctly, a .bar file will be created in the C:\myapp\output directory

as seen in the diagram above.


18/32



Compiling and Packaging Using the RippleEmulator

A second method for packaging and deploying and application is using the Ripple Emulator. Once thefiles for an application are developed (the .html, config.xml and the icon.jpg and other relatedfiles), they can be packaged and compiled using the Ripple Emulator for deployment to the PlayBookSimulator.

Accessing Files from a Local File System Using Ripple

If the application files are stored on a developers local computer, they can be accessed if a remote webserver is not available. From the Ripple emulator, you can open files directly from the local file systemon your computer using the following steps:

1. Copy your project folder and all of its contents into the RippleSites folder. If this folder doesn'texist, you must create it in one of the following locations::

Windows XP:

C:\Documents and Settings\\RippleSites

Windows 7: C:\Users\\RippleSites

Mac OS: /Users//RippleSites

2. From Ripple, in the address bar, type http://localhost:9900/followed by your project folder andlanding page

For example:

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

More information on how to access files using Ripple if a remote web server is not available can beaccessed from theBlackBerry Developer Blog.
https://bdsc.webapps.blackberry.com/html5/documentation/ww_developing/accessing_a_local_project_in_ripple_1948645_11.htmlhttps://bdsc.webapps.blackberry.com/html5/documentation/ww_developing/accessing_a_local_project_in_ripple_1948645_11.htmlhttps://bdsc.webapps.blackberry.com/html5/documentation/ww_developing/accessing_a_local_project_in_ripple_1948645_11.htmlhttps://bdsc.webapps.blackberry.com/html5/documentation/ww_developing/accessing_a_local_project_in_ripple_1948645_11.html


19/32



Accessing a Project File from a Remote Web Server Using Ripple

To test an HTML5 WebWorks application in the Ripple Emulator that is installed on remote web server(such as Drop Box), files must be stored in a Public Folder. Any of the files will be accessible to the

public. To use a service such as Drop Box, place the index.html, config.xml and icon.png and any other

files into a public folder.

If using Drop Box, save the index.html, config.xml and icon.png files to the Public folder in yourDrop Box account. After saving to the Public folder, follow the following steps:

Open your Dropbox account in a web browser (such as Google Chrome, Mozilla Firefox, etc)

Navigate to the Public folder, right click on the index file, select Copy Public Link

Figure 7: Accessing a project file from Dropbox


20/32



Select Copy to Clipboard

Figure 8: Copy to Clipboard

Paste this link to the Ripple address bar

Figure 9: Ripple address bar

The Hello World message will appear on the PlayBook screen in the Ripple Emulator

Figure 10: Hello World message in Ripple Emulator


21/32



Ripple Emulator Packaging Options

The Ripple Emulator can be used to package and compile the files for an HTML5 WebWorksapplication. Before starting to compile an application using the Ripple Emulator, you should be familiar

with some of the packaging option available. For information on how to download and install the Ripple

Emulator software, please refer to Module 2.

To use any of these packaging options, the settings must be configured for the platform being used inthe Ripple Emulator (for example WebWorks-TabletOS); To configure the settings, click on thePlatforms menu option and select WebWorks-Tablet OS.

Figure 11: Selecting your packaging option

To access the packaging options in the Ripple Emulator, click on the wrench icon in the topright-hand corner your screen.

The following options are available for packaging:

Figure 12: Packaging options

Package - This option builds and packages the application. For BlackBerry tablet applications, this

option creates the .zip and .bar files for the application

Package & Sign - This option builds, packages, and signs the application. For BlackBerry tabletapplications, this option creates the .zip and signed .bar files for the application

Package & Launch - This option builds, packages, and launches the application on the specifiedsimulator. For BlackBerry tablet applications, this option creates the .zip and .bar files for theapplication


22/32



To package an application in the Ripple Emulator:

Select the wrench icon located in the top right of the Ripple emulator and then selectSettings

In the Package dialog box, you will be required to enter the location of the BlackBerry HTML5WebWorks SDK and the location of the Hello World application files. For information on how todownload and install the BlackBerry HTML5 WebWorks SDK, please refer to Module 2.

SDK Path - The path to where the BlackBerry WebWorks SDK is installed. This information isrequired to package the application. The following are the default SDK paths:

Windows XP: C:\Program Files\Research In Motion\BlackBerry WebWorks SDK forTabletOS

Windows 7: C:\Program Files (x86)\Research In Motion\BlackBerry WebWorks SDKfor TabletOS

Mac OS: /Developer/SDKs/Research In Motion/BlackBerry WebWorks SDK forTabletOS

Project Root- The location of your project (where the index.html, config.xml and icon.png files aresaved). This setting is required to package your application.

Example: C:\myapp\hw

Archive Name - The name the archive file is going to be (for example, hw or HelloWorld). Thissetting is required to package your application.

Output Folder - The location where the output files are going to reside. This cannot be the samelocation as the Project Root. This information is required to package your application.

Example: C:\myapp\output

Figure 13: Example C:\myapp\output


23/32



Optional Packaging Settings in the Ripple Emulator

There are additional packaging settings in the Ripple Emulator. These additional options include:

Enable Web Inspector - This setting specifies whether to enable or disable the remote web

inspector to debug and profile the application on a live device Note: This should be disabled when packaging the application for distribution to the

BlackBerry App World storefront

Conditional: This setting is required only if a developer is testing the application withthe remote web inspector

CSK Password - The password specified for a developers keystore (when a developer registeredwith the RIM Signing Authority for Code Signing Keys

Conditional: This setting is required only if signing the application

P12 Password - the password a developer specifies when creating their developer certificate.Otherwise, this is their keystore password


Bundle Number - The bundle number for the developers application (for example, 1.0.0.x, wherex is the bundle number). After successfully signing the application, this number automaticallyincreases by 1.


PlayBook IP - The IP address of the developers BlackBerry Tablet Simulator. Conditional: This setting is required only if launching the application in a simulator

PlayBook Password - The password of the developers BlackBerry Tablet Simulator

Conditional: This setting is required only if launching the application in a simulator


24/32



Packaging an Application using the Ripple Emulator

Before starting to package your application using the Ripple Emulator make sure that the Buildsettings are configured. Likewise, make sure that the configuration document (config.xml) file is storedin the project root.

To package your application:

Select the wrench icon located in the top right of the Ripple emulator

Select Package

The Ripple emulator builds the application. If the build and package completes successfully, themessage "Build succeeded!" is displayed and the .bar file is stored in the Output Folder

Figure 14: Successful build


25/32



Deploying the Application to the TabletSimulator Using the Command Prompt

After successfully packaging and compiling your application it is recommended that the application betested in the BlackBerry PlayBook Simulator before deployment to the Tablet. The BlackBerry TabletSimulator enables developers to run and test an application without having access to the physicalhardware. Testing and debugging an application is important task in the software development process.This is also true for creating mobile applications for devices such as smartphones and tablets. Deployingthe application on the BlackBerry Tablet Simulator allows developers to see and test the application asit will function on an actual BlackBerry PlayBook Tablet using VMware software.

To test the application on the BlackBerry PlayBook Simulator using the Command Prompt, use thefollowing steps:

Start the BlackBerry PlayBook Simulator in VMware Player

Turn on Development Mode. The Development Mode on the BlackBerry PlayBook Tablet Simulatormust be enabled before the application can be loaded.

To enable Development Mode, click on the gear icon in the upper-right corner of thesimulator screen

Figure 15: Enabling developer mode


26/32



On the Security Screen click Development Mode. To use the Use Development Mode label, set theDevelopment Mode setting to ON. In the Device Password field (on the main Securitymenu), typethe password for your tablet (The default password for the Tablet is PlayBook).

Figure 16: Developer mode

Record the IP address of the simulator. You can view the tablet's IP address by tapping the icon to theright of the clock on the status bar

Figure 17: Obtaining IP address


27/32



Open up a command prompt, and navigate to the bbwp\blackberry-tablet-sdk\bin folder, which isunder the BlackBerry WebWorks SDK installation folder. Type the following text:

C:\Program Files\Research In Motion\BlackBerry WebWorks SDK for TabletOS2.2.0.5\bbwp\blackberry-tablet-sdk\bin

Type the following command to load and run your application in the simulator:

blackberry-deploy -installApp -password -device -package

Figure 18: Packaging the application using the Windows Command Prompt


28/32



Return to the PlayBook simulator and click on the All menu option. The icon for the HelloWorld application should be featured as seen below:

Figure 19: Hello World application


29/32



Click on the Hello World application icon to view the application

Figure 20: Hello World application


30/32



Deploying the Application to the TabletSimulator using the Ripple Emulator

An application can also be deployed to the BlackBerry PlayBook Simulator using the Ripple Emulator.Before deploying the application to the BlackBerry PlayBook Simulator,

Make sure you configure the "Build" and "Launch" settings in the Ripple Emulator

Make sure that you store the configuration document (config.xml) file in the project root

Make sure that the PlayBook Tablet Simulator is already started (in VMWare Player)

To deploy the application using the Ripple Emulator,

Select the wrench icon located in the top right of the Ripple Emulator

Select Package & Launch. The Ripple emulator builds the application. If the build and package iscompleted successfully, the message "Build succeeded!" is displayed

Figure 21: Successful build

For BlackBerry tablet applications, the .zip and .bar files for the application are stored in thespecified output folder. The BlackBerry Tablet Simulator launches the application.

Figure 22: Hello World application launched in BlackBerry Tablet Simulator


31/32



Summary and Further Learning

Summary

In this module the following topics were covered:

Creating an index.html file for an application

Leveraging an existing graphic for an icon for the application

Creating a config.xml file for an application

Packaging the application files using the BlackBerry WebWorks Packager into a .bar file

Accessing a Project File from a Remote Web Server in the Ripple Emulator for viewing theapplication

Packaging an application using the Ripple Emulator

Deploying the application on the BlackBerry Playbook simulator using the command prompt

Packaging and launching the application on the BlackBerry PlayBook simulator using theRipple Emulator

Further LearningAfter successfully completing this module, next steps include getting an application ready to deploy on

a Tablet. These steps include:

Configuring a developers computer to request code signing keys

Signing an application for deployment on a Tablet

Creating a debug token to deploy an application on a Tablet

Using the Web Inspector tool to test and debug

Information on these next steps can be found in the Module 4 - Testing, signing and deploying anapplication to the BlackBerry PlayBook tablet module.

Additional Resources

The following are additional resources that can be accessed to provide additional information on topicscovered in this module.

For more information about configuration documents, seeCreating a WebWorks configuration

document

For more information about the BlackBerry Tablet Simulator, seeUsing the tablet simulator.

For more information on using an open-source remote web server such as Drop Box, visit theBlackBerry Support Forums

For more information on how to access local projects using Ripple, visit theBlackBerry HTML5WebWorksportal
http://wbt20ykf/html5/documentation/ww_developing/working_with_config_xml_file_1866970_11.htmlhttp://wbt20ykf/html5/documentation/ww_developing/working_with_config_xml_file_1866970_11.htmlhttp://wbt20ykf/html5/documentation/ww_developing/working_with_config_xml_file_1866970_11.htmlhttp://wbt20ykf/html5/documentation/ww_developing/working_with_config_xml_file_1866970_11.htmlhttp://wbt20ykf/html5/documentation/ww_testing/using_the_tablet_simulator_1866980_11.htmlhttp://wbt20ykf/html5/documentation/ww_testing/using_the_tablet_simulator_1866980_11.htmlhttp://wbt20ykf/html5/documentation/ww_testing/using_the_tablet_simulator_1866980_11.htmlhttp://supportforums.blackberry.com/t5/Web-and-WebWorks-Development/Trouble-Opening-Sample-Index-File-Using-Ripple/td-p/1435099http://supportforums.blackberry.com/t5/Web-and-WebWorks-Development/Trouble-Opening-Sample-Index-File-Using-Ripple/td-p/1435099https://bdsc.webapps.blackberry.com/html5/documentation/ww_developing/accessing_a_local_project_in_ripple_1948645_11.htmlhttps://bdsc.webapps.blackberry.com/html5/documentation/ww_developing/accessing_a_local_project_in_ripple_1948645_11.htmlhttps://bdsc.webapps.blackberry.com/html5/documentation/ww_developing/accessing_a_local_project_in_ripple_1948645_11.htmlhttps://bdsc.webapps.blackberry.com/html5/documentation/ww_developing/accessing_a_local_project_in_ripple_1948645_11.htmlhttps://bdsc.webapps.blackberry.com/html5/documentation/ww_developing/accessing_a_local_project_in_ripple_1948645_11.htmlhttps://bdsc.webapps.blackberry.com/html5/documentation/ww_developing/accessing_a_local_project_in_ripple_1948645_11.htmlhttp://supportforums.blackberry.com/t5/Web-and-WebWorks-Development/Trouble-Opening-Sample-Index-File-Using-Ripple/td-p/1435099http://wbt20ykf/html5/documentation/ww_testing/using_the_tablet_simulator_1866980_11.htmlhttp://wbt20ykf/html5/documentation/ww_developing/working_with_config_xml_file_1866970_11.htmlhttp://wbt20ykf/html5/documentation/ww_developing/working_with_config_xml_file_1866970_11.html


32/32


For more information about additional configuration settings in the XML file, visitWorkingwith the XML config File
https://bdsc.webapps.blackberry.com/html5/documentation/ww_developing/working_with_config_xml_file_1866970_11.htmlhttps://bdsc.webapps.blackberry.com/html5/documentation/ww_developing/working_with_config_xml_file_1866970_11.htmlhttps://bdsc.webapps.blackberry.com/html5/documentation/ww_developing/working_with_config_xml_file_1866970_11.htmlhttps://bdsc.webapps.blackberry.com/html5/documentation/ww_developing/working_with_config_xml_file_1866970_11.htmlhttps://bdsc.webapps.blackberry.com/html5/documentation/ww_developing/working_with_config_xml_file_1866970_11.htmlhttps://bdsc.webapps.blackberry.com/html5/documentation/ww_developing/working_with_config_xml_file_1866970_11.html