Developing HTML5 Apps for BlackBerry 10

Developing HTML5 Apps for BlackBerry 10

Kamal Sharma

http://www.facebook.com/BBDevIndia

Contents

Requirements............................................................................................................................................................... 3

Installation ................................................................................................................................................................... 3

Creating Your First Project (Hello World) .................................................................................................................... 4

Project Structure ...................................................................................................................................................... 4

Creating Sample Source File .................................................................................................................................... 4

Creating Sample Config File ..................................................................................................................................... 5

Creating Sample Icon File......................................................................................................................................... 5

Using Ripple ................................................................................................................................................................. 5

Running Project on Ripple ....................................................................................................................................... 5

Ripple Settings for Package App File ........................................................................................................................ 7

Build App File (.bar file)............................................................................................................................................ 7

Package ................................................................................................................................................................ 8

Package & Sign ..................................................................................................................................................... 8

Package & Launch ................................................................................................................................................ 8

Using Simulator ............................................................................................................................................................ 8

Configure Simulator ................................................................................................................................................. 8

Adjust Simulator Size ............................................................................................................................................. 10

Adjust Simulator Orientation ................................................................................................................................. 12

Install App (.bar) file on Simulator ......................................................................................................................... 13

Using Device ............................................................................................................................................................... 14

Configure Device .................................................................................................................................................... 14

Sign Key for Apps ................................................................................................................................................... 14

Building Key using Command Line ..................................................................................................................... 14

Building Key using Graphical Aid Tool ................................................................................................................ 15

Install App (.bar) file on Device .............................................................................................................................. 15

Error Handling ............................................................................................................................................................ 18

Requirements

BlackBerry WebWorks 10 SDK

Ripple Emulator (Chrome Extension)

VMware Player + BlackBerry 10 Dev Alpha Simulator

BlackBerry Graphical Aid Tool

Web Server and PuTTY

Installation

Ripple

Download and install the Ripple Chrome extension from BlackBerry website.

https://developer.blackberry.com/html5/download/ripple

WebWorks

Download and install the WebWorks SDK from BlackBerry website.

https://developer.blackberry.com/html5/downloads/fetch/BB10-WebWorks-SDK-1.0.1.17.exe

VMware Player

Download and install the VMware Player.

https://www.vmware.com/tryvmware/?p=player&lp=1

BlackBerry 10 Dev Alpha Simulator

Download and Install the BlackBerry 10 Dev Alpha Simulator from BlackBerry website.

https://developer.blackberry.com/native/beta/downloads/fetch/BlackBerry10Simulator-Installer-BB10_0_06-

543-Win-201208070619.exe

Graphical Aid

Download and install the Graphical Aid Tool from BlackBerry website.

http://supportforums.blackberry.com/rim/attachments/rim/Testing_and_Deployment_of_Applications@tkb/152

/36/BlackBerry%20Tablet%20OS%20Graphical%20Aid%202.6.6%20-%20Windows%20Installer.zip

PuTTY

Download and install the PuTTY from PuTTY website.

http://www.putty.org/

Web Server

Wamp, Vertrigo etc.

Request permission to Sign your Apps

http://developer.blackberry.com/html5/signingkey

Creating Your First Project (Hello World)

Project Structure

Create a project in your server root (www) folder. If you are using Wamp server root is c:/wamp/www or using

Vertrigo root is c:/program files/vertrigo/www.

Project structure as follow:

YOUR_PROJECT_FOLDER

+ index.html (Source File)

+ config.xml (Configuration file)

+ icon file (Icon Image File)

+ all others files/directories

Creating Sample Source File

Create index.html file in project folder, add the following code and you can add code just like HTML + JavaScript

+ CSS in webpage.

<!DOCTYPE html>

<html>

<head>

<meta id="viewport" name="viewport" content="width=device-width, height=device-height,

user-scalable=no/">

</head>

<body>



<h1>Hello, OpenClass</h1>

</body>

</html>

Note

Viewport meta tag is used for control the zoom level.

<meta id="viewport" name="viewport" content="width=device-width, height=device-height,

user-scalable=no/">

If you want to specify the custom width and height, value is based on pixel. Define like

content="width=600, height=1000"

If you want to prevent the user to control the zoom level. Define like

content="user-scalable=no"

If you want to set how much the user can zoom in

<meta id="viewport" name="viewport"

maximum-scale=2, minimum-scale=1

In BlackBerry 10 actual device resolutions are in Portrait mode

(aspect ratio) through viewport some sample sizes are:

640x1067, 500x833, 450x750, 300x500 etc.

Creating Sample Config File

<?xml version="1.0" encoding="UTF

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

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

xml:lang="en">

<author href="url" rim:copyright

<icon src="icon.png"/>

<name>OpenClass</name>

<content src="index.html"

<feature id="blackberry.app"

<feature id="blackberry.invoke"

</widget>

Note

� Version is used for versioning

� <name> element is used for App Name.

More settings available at BlackBerry website.

https://developer.blackberry.com/html5/documentation/working_with_config_xml_file_1866

Creating Sample Icon File

You can create maximum size of 86x86 pixel image for App Icon, extension can be .PNG file.

Using Ripple

Running Project on Ripple

Open your source file (index.html) in Chrome browser, if you are using

project URL look like http://127.0.0.1/your_project

how much the user can zoom in (maximum) and out (minimum). Define

"viewport" content="width=device-width, height=device

scale=1/">

actual device resolutions are in Portrait mode 768x1280, you can define

some sample sizes are:

640x1067, 500x833, 450x750, 300x500 etc.

"UTF-8"?>

"http://www.w3.org/ns/widgets"

"http://www.blackberry.com/ns/widgets" version="1.0.0.1" id="OpenClass"

rim:copyright="copyright information">Kamal Sharma

"index.html"/>

"blackberry.app" />

"blackberry.invoke"/>

the Build.

element is used for App Name.

More settings available at BlackBerry website.

https://developer.blackberry.com/html5/documentation/working_with_config_xml_file_1866

86x86 pixel image for App Icon, extension can be .PNG file.

Open your source file (index.html) in Chrome browser, if you are using Vertrigo Server or Wamp Server

http://127.0.0.1/your_project or http://localhost/your_project.

Define like

width, height=device-height,

, you can define your custom size

"OpenClass"

Kamal Sharma</author>

https://developer.blackberry.com/html5/documentation/working_with_config_xml_file_1866970_11.html

86x86 pixel image for App Icon, extension can be .PNG file.

r or Wamp Server your

After opening the URL in browser open the Ripple Emulator extension.

Click Enable to start the Ripple Emulator, this will load your App in Ripp

change the Platforms to BlackBerry 10 WebWorks

Image show App running on Ripple Emulator.

After opening the URL in browser open the Ripple Emulator extension.

to start the Ripple Emulator, this will load your App in Ripple Emulator. After Ripple first launch

BlackBerry 10 WebWorks using Change Platform button.

Image show App running on Ripple Emulator.

After Ripple first launch

Ripple Settings for Package App File

Before performing the Packaging, start the Ripple servi

details.

Where,

� SDK Path is your BlackBerry 10 SDK

Files\Research In Motion\BlackBerry 10 WebWorks SDK 1.0.0.15

� Project Root is where your Project folder exists.

� Archive Name is your App Name;

� Output Folder is where your App file

Build App File (.bar file)

Ripple Emulator provide three types of options for building App file.

Package & Launch App file.

for Package App File

start the Ripple services using start the Services button and fill the

BlackBerry 10 SDK Installation path, for example installation path is

BlackBerry 10 WebWorks SDK 1.0.0.15.

e your Project folder exists.

Name; App Name match with your config.xml <name> element

is where your App file creates.

Ripple Emulator provide three types of options for building App file. Package App file, Package & Sign App file and

button and fill the Settings

Installation path, for example installation path is C:\Program

App Name match with your config.xml <name> element.

Package App file, Package & Sign App file and

Package

Using Package, you can build App file for testing on Simulator and install .bar file manually on simulator using

command line tool.

Package & Sign

Using Package & Sign, you can build App file for installation in device, you need to sign the .bar file before

installing on the device. In Ripple Settings provide your Singing Password as you provide when you requesting the

key in BlackBerry key request form.

Package & Launch

Using Package and Launch, you can build .bar file and install directly on Simulator if the Simulator is running by

provide the simulator IP Address.

Using Simulator

Configure Simulator

Open VMware Player.

Click on Open a Virtual Machine. Windows file

Windows 7 Virtual Machines folder found

BB10_VERSION).

Open the BlackBerry10Simulator file, Select the

panel and click on Play Virtual machine.

Wait few seconds, Simulator will launch

Windows file Browser will open, Navigate to Virtual Machine Folder

Virtual Machines folder found in Libraries->Documents->Virtual Machines->BlackBerry10Simulator

, Select the Blackberry 10 Dev Alpha Simulator from the navigation in left

Play Virtual machine.

imulator will launch.

Virtual Machine Folder (in

>BlackBerry10Simulator-

from the navigation in left

Obtain the IP Address of the Simulator by clicking

testing the App on the Simulator.

Adjust Simulator Size

Due to 768x1280 resolution of the device, this size is

the simulator you need to connect to Simulator using

of the Simulator by clicking on the icon and Development Mode

of the device, this size is larger than the normal monitor screen

the simulator you need to connect to Simulator using Telnet or SSH, Open PuTTY for setup the resolution.

Development Mode should be ON for

larger than the normal monitor screen. To adjust the size of

for setup the resolution.

Host Name as the Simulator IP Address

Login screen will open; requesting login

is devuser. To control the zoom level type the following command and

ves-zoom value%

This command will immediate control the zoom and

your monitor screen resolution.

Simulator IP Address and Connection type to Telnet, Click on Open.

requesting login username and password, by default for all the username and password

type the following command and press enter.

This command will immediate control the zoom and scroll bar will disappear; adjust zoom

username and password

; adjust zoom value according to

Adjust Simulator Orientation

By default Simulator start in Portrait orientation, you can change the orientation by dragging the cursor from the

bottom right corner, just like in the screenshot.

Install App (.bar) file on Simulator

You can install App (.bar file) in Simulator

line tool.

Deploy to a Simulator Using Ripple

� Open Ripple Settings option; provide the

� Use Ripple Package & Launch

Deploy to a Simulator Using Command line tool

� Build the App file using Ripple using

other is for Simulator.

� Choose the file from Simulator folder

dependencies->tools->bin folde

WebWorks SDK 1.0.0.15\dependencies

� Open command prompt using

following DOS command.

cd C:\Program Files\Research In Motion

1.0.0.15\dependencies\tools

� Type the following command to install the file on simulator,

Address and OpenClass.bar is App file.

blackberry-deploy -installApp

password 12345

App is installed and running on Simulator.

on Simulator

You can install App (.bar file) in Simulator, directly from Ripple using Package & Launch button or usi

provide the Simulator IP Address and Password 12345.

button for install App in Simulator.

ommand line tool

App file using Ripple using Package button, Ripple will create two folders

Simulator folder and place the App (.bar) file in BlackBerry 10 WebWorks SDK

folder. Absolute path is C:\Program Files\Research In Motion

dependencies\tools\bin. [Path is depending on your installation.

using cmd and navigate to the path BlackBerry 10 WebWorks SDK

Research In Motion\BlackBerry 10 WebWorks SDK

tools\bin

Type the following command to install the file on simulator, where 192.168.61.128

OpenClass.bar is App file.

installApp -device 192.168.61.128 -package OpenClass.bar

App is installed and running on Simulator.

button or using command

12345.

folders one is for Device and

BlackBerry 10 WebWorks SDK->

Research In Motion\BlackBerry 10

on your installation.]

BlackBerry 10 WebWorks SDK using the

BlackBerry 10 WebWorks SDK

192.168.61.128 is Simulator IP

package OpenClass.bar -

Using Device

Configure Device

� Connect Device to computer, install the BlackBerry Device Driver.

� Popup asking password for connect

� Enable Development Mode in Device

Sign Key for Apps

Building Key using Command Line

http://developer.blackberry.com/html5/signingkey

Before signing the Apps (without debug token), you need to create the author.p12, barsigner.csk and

barsigner.db files.

� After obtaining the both .csj file

Connect Device to computer, install the BlackBerry Device Driver.

word for connecting device to the computer. Provide Device password

in Device from Settings option and Note down the IP Address

Building Key using Command Line

ckberry.com/html5/signingkey


.csj files, place the file somewhere on disk. For example in c

Device password and Press OK.

IP Address of the Device.


, place the file somewhere on disk. For example in c: /.

� Open command prompt, and navigate to the path

>bin folder.



� Type the following command for signing. Where

form and NEW_PASSWORD is new password for the keys.

blackberry-signer –register

XXX.csj C:\client-PBDT-XXX.csj

Building Key using Graphical Aid Tool

� Open the BlackBerry Graphical Aid

� Switch to Configuration tab, Run Configuration wizard using

� In the Next step provide your BlackBerry WebWorks SDK location

� After next step location, in Developer Certificate click on

Install App (.bar) file on Device

Deploy to a Device Using Graphical Aid

� Open BlackBerry Graphical Aid tool, Navigate to

and provide the device password.

� Click on Install.

ompt, and navigate to the path BlackBerry 10 WebWorks SDK-


tools\bin

Type the following command for signing. Where YOUR_PIN is your PIN which you specified in

is new password for the keys.

register –csjpin YOUR_PIN –storepass NEW_PASSWORD C:

XXX.csj

Building Key using Graphical Aid Tool

BlackBerry Graphical Aid tool,

, Run Configuration wizard using Run Configuration button.

BlackBerry WebWorks SDK location.

After next step location, in Developer Certificate click on Create Certificate.

Device

Graphical Aid Tool

Open BlackBerry Graphical Aid tool, Navigate to install tab. choose the .bar file from the

device password.

-> dependencies->tools-


PIN which you specified in key signing

storepass NEW_PASSWORD C:\client-RDK-

button.

from the Device folder

Deploy to a Device Using Command line tool

� Build App (.bar) file using Ripple

� Choose the file from Device folder

dependencies->tools->bin folder. Absolute path is

WebWorks SDK 1.0.0.15\dependencies

� Open command prompt using

following DOS command.



� Type the following command and press enter

Address and OpenClass.bar is App file.

blackberry-deploy -installApp

12345

ommand line tool

using Ripple Package & Sign button.

folder and place the App (.bar) file in BlackBerry 10 WebWorks SDK

folder. Absolute path is C:\Program Files\Research In Motion

dependencies\tools\bin. [Path is depending on your installation.]

using cmd and navigate to the path BlackBerry 10 WebWorks SDK


tools\bin

and press enter to install the file on Device, where 169.254.0.1

OpenClass.bar is App file. Make sure Development Mode is ON.

installApp -device 169.254.0.1 -package OpenClass.bar

BlackBerry 10 WebWorks SDK->

Research In Motion\BlackBerry 10

[Path is depending on your installation.]

BlackBerry 10 WebWorks SDK using the


169.254.0.1 is Device IP

package OpenClass.bar -password

App is installed and running on Device.

App is installed and running on Device.

Error Handling

1. When Packaging App file, getting this error from Ripple Emulator.

This is due to Ripple Build and Deploy services in not running. Start the Services using Start Services button in

Ripple


This is due to Bundle Number that used in previous package

For example when successfully build the Package

Number to 2. Check the Bundle Number and also in config.xml file.


This is due to Network Connectivity

4. Unable to make author.p12 file from

Open the BlackBerry Graphical Tool, Navigate to Configuration tab. Run the Configuration Wizard. This

process will create the certificate for signing.

When Packaging App file, getting this error from Ripple Emulator.

ld and Deploy services in not running. Start the Services using Start Services button in


Bundle Number that used in previous package; change the Bundle Number

For example when successfully build the Package Bundle Number was 1 then Ripple Increment the Bundle

. Check the Bundle Number and also in config.xml file.


Network Connectivity.

nable to make author.p12 file from Command Line.


process will create the certificate for signing. Then build using WebWorks.

ld and Deploy services in not running. Start the Services using Start Services button in

Bundle Number in Ripple Settings.

then Ripple Increment the Bundle

Technology

Developing HTML5 Apps for BlackBerry 10