View Full Version : GUIDE: Deploying Sencha Touch 2.1 as a Blackberry native apps (Webworks)

21 Dec 2012, 12:07 PM
I am by no means an expert when it comes to Blackberry, but I wanted to at least share my experience with getting Sencha running on Blackberry OS7 devices as a native application using Blackberry's WebWorks API. This post is a follow up post to a bug report previously started last year. (http://www.sencha.com/forum/showthread.php?151188-Blackberry-Webworks-Issues)

We have our app running on all 3 platforms (iOS, Android, Blackberry). While Sencha provides guides on the first two, they seem to neglect the last platform.

The following represents many hours of me testing (and constantly rebooting) Blackberry devices.

You should have experience in how Sencha Touch is structured (http://docs.sencha.com/touch/2-1/#!/guide/getting_started) and also how to setup and run a sample Blackberry WebWorks (https://developer.blackberry.com/html5/documentation/getting_started_with_webworks_for_bb_os.html) application. I posted this thread to mainly help a lot of users past the bugs and quirks.

So, here we go... First thing we have to do is get around the bugs.

1) Viewport Bug - the Viewport is broken under Webworks (http://supportforums.blackberry.com/t5/tkb/articleprintpage/tkb-id/browser_dev@tkb/article-id/146).

This is a nasty problem, plain and simple. Blackberry’s provided work-arounds are pretty worthless, IMO. The issue I found in my testing is that window.innerHeight doesn’t return the correct height ; depending on the device it can be off by 27-53 pixels! I added some special cases for devices that I support (Blackberry 9810, 9850, 9860, 9900, 9930). Not pretty - I know.

The interesting thing is that the Application viewport config takes a height config, but you can’t use this because the height won’t be known until the DOM is ready.

So, here is what we do. Create a new Blackberry Viewport class.

Put it in app/viewport/Blackberry.js

Ext.define('App.viewport.Blackberry', {
extend: 'Ext.viewport.Default',
constructor: function (config) {
// Blackberry does not like height: 100%
this.superclass.config.height = this.getWindowHeight() + 'px';
return this;
getWindowHeight: function () {
/* blackberry variable is defined if we are in a webworks project */
var height = window.innerHeight;
if (typeof blackberry !== 'undefined') {
var useragent = navigator.userAgent.toLowerCase();
var moreHeight = 0;
if (useragent.indexOf("9810") != -1) { // Torch 9810
height = 425;
else if (useragent.indexOf("9850") != -1) { // Torch 9850
height = 533;
else if (useragent.indexOf("9860") != -1) { // Torch 9860
height = 533;
else if (useragent.indexOf("berry 99") != -1) { // Bold 9900/9930
height = 267;
return height;
return height;

}, function () {


Next create our custom Viewport default class. Put it in app/viewport/Viewport.js:

Ext.define('App.viewport.Viewport', {
requires: [

constructor: function (config) {
var osName = Ext.os.name,
viewportName, viewport;
switch (osName) {
case 'Android':
viewportName = (Ext.browser.name == 'ChromeMobile') ? 'Ext.viewport.Default' : 'Ext.viewport.Android';
case 'BlackBerry':
viewportName = 'App.viewport.Blackberry';
case 'iOS':
viewportName = 'Ext.viewport.Ios';
viewportName = 'Ext.viewport.Default';

viewport = Ext.create(viewportName, config);

return viewport;

Finally, we have to tell our app to use this viewport. We do this by adding our new class to the requires section, and passing the viewport our class.


name: 'App',
requires: [
viewport: {
xclass: 'App.viewport.Viewport'

This should fix your Viewport!

2) Buttons in the top left of your titlebar such as the “Back” button aren't tap-able. This is a bug in Blackberry OS7. OS 7.1 seems to fix this issue. Telling our sales force to upgrade isn’t an easy option. The work around I’ve found is adding some space makes the buttons work correctly. There are 2 ways to fix this:
a) On all of your Titlebar/Toolbars, add the spacer if the device is Blackberry OR
b) Create our own TitleBar that override's the one Sencha provides and handle it globally.

Here is option b implementation:

Create app/TitleBar.js:

Ext.define('App.TitleBar', {
override: 'Ext.TitleBar',

constructor: function (config) {
var newconfig = Ext.clone(config);
if (Ext.os.is.BlackBerry) {
if (config.items) {
newconfig.items.splice(0, 0, { xtype: 'spacer', width: 10 });

Now go back to your app.js and let's make sure to require this class. If you did the previous item above, you now have 2 classes required:

name: 'App',
requires: [


Your buttons are now tapable! Please note - this override was only for TitleBar - you'll have to do the same for Toolbar if you use that.

3) If you want to use the Blackberry back button (blackberry.system.event.onHardwareKey), you'll need to turn off animations. Otherwise, once an animation occurs, the back button will exit the app. You'll need to pass animation:false to your configurations as well as override the Component:

Ext.define('App.Component', {
override: 'Ext.Component',
show: function (animation) {
return this.callParent([false]);
hide: function (animation) {
return this.callParent([false]);

Follow the same procedure here as the other ones (add App.Component to your App requires).

4) Use Sencha Cmd to build your application. Run sencha build package. This is what you want to deploy in your WebWorks /www folder. Don't use the index.html that Sencha creates. It creates a viewport that doesn't work with WebWorks. Use something much simpler like this:

<!DOCTYPE html>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<meta name="viewport" content="user-scalable=no, initial-scale=1, maximum-scale=1, minimum-scale=1, width=device-width, height=device-height, target-densitydpi=device-dpi" />

<style type="text/css">
* Example of an initial loading indicator.
* It is recommended to keep this as minimal as possible to provide instant feedback
* while other resources are still being loaded for the first time
html, body {
height: 100%;
background-color: #000000 !important;

#appLoadingIndicator {
position: absolute;
top: 50%;
margin-top: -15px;
text-align: center;
width: 100%;
height: 30px;
-webkit-animation-name: appLoadingIndicator;
-webkit-animation-duration: 0.5s;
-webkit-animation-iteration-count: infinite;
-webkit-animation-direction: linear;

#appLoadingIndicator > * {
background-color: #FFFFFF;
display: inline-block;
height: 30px;
-webkit-border-radius: 15px;
margin: 0 5px;
width: 30px;
opacity: 0.8;

@-webkit-keyframes appLoadingIndicator{
0% {
opacity: 0.8
50% {
opacity: 0
100% {
opacity: 0.8
<link rel="stylesheet" type="text/css" href="app.css" />

<script type="text/javascript" src="app.js"></script>
<div id="appLoadingIndicator">
<a href="" target="_blank" id="linker" style="display: none;"></a>

5) In the example above we added a custom background color to the HTML css. In our implementation we have a logo as well. In your WebWorks config.xml file, there is a config element called rim:loadingScreen. I recommend not setting a splash screen logo, and instead making it only have a backgroundColor which makes the same color in your index.html body background. This will prevent a weird transition effect.

I hope this guide helps out other users. I welcome any improvements to this as I'm still learning myself. We actually have the PhoneGap 2.2 API running in Android and iOS, but when I include it in Blackberry, I get a blank screen - I would love to know why, but I don't have time to figure this out; the WebWorks API is all we really need at this point and PhoneGap just wraps that.

1/29/2013 - Updated code above. Fixed the App.Titlebar and added information about disabling animations.

3/19/2013 - Fixed The App.Titlebar - it incorrectly excluded BlackBerry. Updated App.viewport.Blackberry to have hard-coded heights.

23 Dec 2012, 7:02 AM
Thanks for this post.

22 Feb 2013, 5:05 AM
Great post .. This really helped me ... Thanks

22 Feb 2013, 5:52 AM
Thanks so much for sharing. In honesty was waiting on someone to do this hard work so I could piggy back ;-) ! Thanks again, really appreciate it.

19 Mar 2013, 12:01 PM
I made some code changes to the Titlebar and BlackBerry Viewport. Anyone that has used this should update accordingly.