developing html5 apps for blackberry 10
DESCRIPTION
This Article describe Developing and Building HTML5 based Apps for BB10 using WebWorks, Test HTML5 Apps on Ripple Emulator, Install .bar file on BlackBerry 10 device and Install .bar file on VMware Player Simulator.TRANSCRIPT
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>
<!-- YOUR CODE -->
<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
Before signing the Apps (without debug token), you need to create the author.p12, barsigner.csk and
.csj files, place the file somewhere on disk. For example in c
Device password and Press OK.
IP Address of the Device.
Before signing the Apps (without debug token), you need to create the author.p12, barsigner.csk and
, place the file somewhere on disk. For example in c: /.
� Open command prompt, and navigate to the path
>bin folder.
cd C:\Program Files\Research In Motion
1.0.0.15\dependencies\tools
� 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-
Research In Motion\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-
BlackBerry 10 WebWorks SDK
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.
cd C:\Program Files\Research In Motion
1.0.0.15\dependencies\tools
� 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
Research In Motion\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
BlackBerry 10 WebWorks SDK
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
2. When Packaging App file, getting this error from Ripple Emulator.
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.
3. When Packaging App file, getting this error from Ripple Emulator.
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
When Packaging App file, getting this error from Ripple Emulator.
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.
When Packaging App file, getting this error from Ripple Emulator.
Network Connectivity.
nable to make author.p12 file from Command Line.
Open the BlackBerry Graphical Tool, Navigate to Configuration tab. Run the Configuration Wizard. This
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
Open the BlackBerry Graphical Tool, Navigate to Configuration tab. Run the Configuration Wizard. This