Blog

With the launch of Priv™ by BlackBerry®, you’re likely thinking about porting all of your BlackBerry® 10 WebWorks® and Apache Cordova™ apps to run on Android™. Luckily, porting your apps is much easier than you think!

This document outlines nearly everything I’ve learned about porting an app to Android. Since WebWorks is so tightly aligned with Apache Cordova, you should be able to port your apps to Android with minimal effort.

Note: Much of the information here can be found in the Apache Cordova documentation. If you’re looking for more of a low-level guide, see the Cordova Android Platform Guide.

First and foremost, you should back up your apps. Odds are that everything will go smoothly, but if you do run into issues, you’ll have a clean project to revert back to. Maybe now is a great time to start using GitHub®? J

Upgrade Cordova and WebWorks

If you haven’t done so already, you should update your globally installed version of Cordova and the WebWorks SDK that’s installed in your project. This will make developing in the future much easier.

Depending on which API level you’re targeting (generally 21+), install the corresponding packages. The Android Platform Guide recommends that you install the following:

Android 5.1.1 (API 22) platform SDK

Android SDK Build-tools 19.1.0 or higher

Android Support Repository (Extras)

You’re now ready to add Android to your project by running:

$ cordova platform add android

Config.xml

After adding the Android platform to your project, you may experience build errors surrounding the parsing of the config.xml file. That’s likely because you’re using platform specific properties. That’s okay, but it requires a minor change.

Any platform specific features (features another platform’s packager wouldn’t recognize) need to be wrapped in a tag.

After correcting that your project should build fine. Don’t forget, any Android specific properties need to be isolated as well.

Splash Screens

Configuring Splash Screens is also slightly different for Android and requires you to install the cordova-plugin-splashscreen plugin. Once installed, you can specify your Splash Screens for Android.

$ cordova plugin add cordova-plugin-splashscreen

Plugins and APIs

You’re probably wondering if your app works on Android “out-of-the-box”. In my experience, for the most part, the answer is yes, most likely.

If you developed your app using Cordova APIs, and there is nothing exclusive to BlackBerry 10 in your code, you should be able to port it very easily.

If your app uses BlackBerry 10 specific, that aren’t available on other platforms, you will need to get more creative. That’s not to say your app can’t be ported, it just means you’ll likely have to make use of some community-developed Cordova Plugins or create your own.

Each platform you target has its own native functionalities unavailable to other platforms, causing porting issues. The best way to avoid these potential road blocks is to use the core Cordova APIs whenever possible.

For example, interacting with the camera:

The Scenario: You have an app that takes a photo and handles the returned captured-image path. You built the app only for BlackBerry 10, and need to make it work on Android now.

Currently your code likely invokes the BlackBerry 10 camera using the BlackBerry specific “invoke” method. The camera card is invoked, and the corresponding callback is fired.

Now, let’s look at how to port this code block so that it runs on both BlackBerry 10 and Android.

Remove the BlackBerry specific API

$ cordova plugin remove cordova-plugin-bb-camera

Add the Cordova plugin:$ cordova plugin add cordova-plugin-camera

Replace the JavaScript for BlackBerry 10 specific API with the Cordova API:

This code now runs on both BlackBerry 10 and Android devices. As you can see, the JavaScript is quite similar to the original in that you call a method which returns the image’s path.

Testing your app

When you’re done modifying the JavaScript, your app should be ready to run. Plug your Android device in to the computer via USB and run the following:

$ cordova run android --device

Building for release

As with BlackBerry 10, your app needs to be signed before releasing it. For an in-depth walkthrough on how to sign an APK, see the official Android docs on Signing Your Application.

Test Case: Cordova Kitchen Sink Sample (BB10 -> Android)

For a demo, let’s use our latest sample app “The Sample to End All Samples”. As I write this, it supports only BlackBerry 10. Pretend it’s an old app, running an out-of-date version of WebWorks and Cordova. Let’s upgrade it so that it runs on Android.

1. Upgrade Cordova: $ npm update –g cordova

2. Update BlackBerry WebWorks:

$ cordova platform update blackberry10

3. Add the Android platform:

$ cordova platform add android

4. Run the app:

$ cordova run android –device

API Mapping

One aspect that can be tricky when porting an app is when platform specific APIs are used. In many cases there are equivalent cross-platform Cordova plugins and I highly recommend using these whenever possible.

Here’s a list of BlackBerry plugins with Cordova equivalents (where applicable). In many cases you can simply use the Cordova API to handle the task on BlackBerry 10 and Android.

For plugins that are not BlackBerry 10 compatible, you’ll likely need to add logic to your app which determines: a) which platform it’s running on, and b) calls the appropriate API.

Having issues getting your Android development environment setup? Cordova 5 comes with a new “requirements” flag. By running the command from your projects root folder, Cordova checks each installed platform and lets you know if one of the dependencies is missing.

Every time I forget why I like jQuery®, they keep reminding me.Not too long ago I came across jQuery deferred (even though it was added already in JQuery 1.5) and I immediately liked it. I feel this feature brings the web application development a bit closer to the desktop development.

This is actually the simplest example of using Deferreds.JQuery ajax methods (get,post,ajax…) return an object which you can add callback methods to it.

Why is it better?

Simply because it lets you keep the logic of execution and the logic of the result separated. This makes a more readable and maintainable code.

So what is a ‘Deferred’?

Deferred is an object which lets you add multiple callback methods to it.It is also a triggering events which determine the state of the call. Using it will determine which callback methods will be triggered. In the Ajax example above the two callbacks are ‘done’ and ‘fail’ which are triggered according to the state of the Ajax call.

This list shows which events will trigger which callbacks.

Callbacks Events→ ↓

deferred.always()

deferred.done()

deferred.fail()

deferred.progress()

deferred.notify()

Triggered

deferred.notifyWith()

Triggered

deferred.reject()

Triggered

Triggered

deferred.rejectWith()

Triggered

Triggered

deferred.resolve()

Triggered

Triggered

deferred.resolveWith()

Triggered

Triggered

What is a ‘Promise’?

A Promise is an object which is given from the Deferred and may be used just to add callbacks.

The two objects, Deferred and Promise, give us the separation in the logic of the caller and the logic of the result.

For example, in the ajax calls of JQuery, the ajax call creates a Deferred and also a Promise from that Deferred. The Deferred is used to trigger events and the Promise is returned to the user so he will add callback functions to it.

Create your own Deferreds functions

You also can use Deferreds in your function much like the ajax functions are using them.

In the example above I have created a function similar to the what ajax function is doing.I have created a Deferred, used that Deferred to trigger an event by using the resolve() function once the operation was done, and returned the Promise which I created from that Deferred.The returned promise is then used for adding callbacks.

Progress

resolve() and reject() are both events that determine the status of the result of the operation.But there is another event you can trigger – notify().This event which was added in version 1.7 can be triggered if you have a process and you want to trigger a callback while the process is still running.

In this case the done callback will be triggered only when the two processes are resolved.This gives you the ability to synchronize between many long lasting processes, which can be useful for so many things. For example, if you are loading many sources and you wish to do something when they are all done.

Changing the result with ‘then’

I mentioned that you can’t trigger events on a Promise, you can only add events to a Promise.However, you still have a way to control the result in another way; by adding filters to the Promise which will be able to alter the response from the caller.Since jQuery 1.8 this is done using the ‘then‘ command:

This example shows that even though the deferred(the ajax) failed, the filter changed the result to resolve, causing the ‘done’ callback to be triggered instead of ‘fail’. Notice that ‘then’ returns also a promise, this makes it a chainable command, which means that you can chain a more than one filter one after the other.

*Notice, before version 1.8 you would do this using the pipe command, but since 1.8 it is done using ‘then‘.‘then’ was originally added in version 1.5 as a callback which is triggered on every event.But since version 1.8 it changed it’s purpose to be a filtering chainable method which can effect the state of the result. This is why you can still see examples on the web that do it the old way.

Adding a callbacks after event was triggered

You should know that you can add callback functions to a promise even if the Deferred was already resolved or failed. This means that if you add a callback method to an ajax call for example, that already returned, the callback would immediately be triggered. This small and seemingly unimportant feature is actually quite useful, because you don’t have to worry that the Deferred is finished when adding callbacks. More over, it lets you add many callbacks whenever you like and by so, reuse deferreds.

A good example for this use would be a cache of ajax calls, this is infact something I have implemented in my workplace(convertro.com) quite successfully.

Background

BlackBerry 10 offers a wide variety of ways to create a mobile application. Often, organizations or individuals will already have a mobile website that they're looking to deploy to BlackBerry 10 but want to minimize the effort in rewriting code, or simply want to gauge interest before developing a full-fledged application.

On BlackBerry 10, it's easy to create an application that simply launches an external URL, allowing you to deliver your mobile experience in the form of an application.

The main benefits of this approach include:

Discoverability: You can deploy and market your application through the BlackBerry World storefront.

Usability: The application exists on the device home screen.

User Experience: The application is launched in its own container, not in the Browser application, which can detract from the overall experience.

User Interface: Every pixel on the screen is dedicated to your application's content; no additional toolbars or navigation panes.

Prerequisites

BlackBerry WebWorks SDK

Download and install the latest version of the BlackBerry WebWorks SDK from the following location:

Once you download bbidtoken.csk, you can launch the WebWorks GUI. Example (Windows):

Start > BlackBerry > BlackBerry WebWorks SDK 2.0.0.71

This should launch a web server and open your browser to the WebWorks management console.

Click on the Certificates panel to view the Code Signing registration tool.

Populate the Signing TokenLocation field with the path to your own bbidtoken.csk file and click Replace Signing Key. This should register your key and you can view where it was installed under the Developer Certificate Location path.

Once your Code Signing token has been registered, you are ready to create your launcher application.

In the Configuration screen, there are a number of optional values to fill in, but the most basic configuration for a launcher application will need the following:

Icon > Source

Your icon should be 114x114px and you need to provide a path relative to your www folder. For example, if my path was icon.png, then it would refer to an icon located on my file system as follows.

C:\Users\eoros\WebWorks Projects\Project1\www\icon.png

Splash Screen > Source

Similar to the Icon, you will need a relative path to your www folder. Depending on the devices you are deploying to, you can add multiple splash screens.

720x1280px (BlackBerry Z30 and Z3)

768x1280px (BlackBerry Z10)

720x720px (BlackBerry Q10 and Q5)

Main URL

This is the most important piece as it determines what to show when the application launches. By default it will refer to index.html. You will want to change this to reflect your own external URL. Example:

This is the second most important piece. In order to actually allow your launcher to reach out to external URLs. For the example above, you would need to white-list the following origin, with Allow subdomains enabled.

Note that if you are using both http and https, you will need to whitelist each individually.

You will need to whitelist every protocol (http, https) and domain combination that your application will be accessing. If you are not able to whitelist every combination (i.e. some domains may not be known), you can disable the Enable Web Security option.

Additional Considerations

Other values you may want to consider filling in are:

App Description

Author

Author Email

Author URL

Once complete, Save your Configuration. Once saved, you are ready to build your launcher application for deployment.

In your project's www folder, you can actually remove all files (except config.xml) and your launcher application will still function since all HTML5 content is being loaded externally.

Building Your Launcher Application

Building your application will take the files you have created, specifically your Configuration file, and will create a BlackBerry Archive (BAR) file that you can deploy to a device for testing, or distribute through the BlackBerry World storefront.

In the WebWorks management console, switch to the Build pane for your project.

You can use this screen to build your application and test on a device (via Build & Install if the device is connected to your PC via USB), or build in Release Mode to get a BAR file to deploy to the BlackBerry World storefront.

This will enable a number of command-line interface (CLI) tools that you can use to register your code signing keys and make available the WebWorks command, enabling you to create new projects, deploy to devices, and build release versions of your application.

For those familiar with PhoneGap™, BlackBerry WebWorks 2.0 is similarly a Cordova™-based product. The benefit of using the BlackBerry WebWorks SDK 2.0 is that your environment is automatically configured to build for BlackBerry® 10 devices without the need for any additional configuration. Both Cordova and PhoneGap are valid tools, although you will need to follow the corresponding platform guides to configure your development environment should you choose that route.

For more Information on BlackBerry WebWorks 2.0, please see the following.

If you have already registered your BlackBerry Code Signing keys, you do not need to take any action. BlackBerry Code Signing is transitioning to be completely BBID-based so, if you have not yet made the switch, you are encouraged to do so (though not required at this time.)

If you have not yet registered any BlackBerry Code Signing keys, you will need to do so.

Now, you are at the point of exporting your Construct 2 application for the BlackBerry 10 platform. To do so, we will need to begin in the command-line. On your PC, open a command-line terminal and navigate to the folder where you would like to create your project. For this example, we will be using c:\webworks.

C:\>cd webworks
C:\webworks>

From here, we want to create a new WebWorks project that will house our Construct 2 application. For this, we use the webworks create command, and then we'll navigate into our newly created folder.

C:\webworks>webworks create C2Sample

C:\webworks>cd C2Sample

C:\webworks\C2Sample>

This will generate a pre-populated, sample folder structure for your application. We'll want to navigate to the following sub-folder and delete everything except config.xml. Only config.xml should remain.

C:\webworks\C2Sample\www

Next, let's switch over to the Construct 2 IDE. From the Construct 2 IDE, we'll want to click through the following.

id: This should be unique to your application. A reverse-domain format similar to com.vendorName.applicationName is recommended.

version: Change this to the current release version of your application. For test builds, you can leave this as-is.

: The application name that will be displayed on the device's homescreen.

: A description for your application.

: Your email, website, and name. Email and website are optional.

Also, take note of the element. If your application is loading resources from external locations, you will need to white-list those URLs. For more information on and various config.xml elements, please check the following documentation.

Switch your device to Development Mode by navigating: Settings > Security and Privacy > Development Mode > Development Mode: On.

Connect your device to your PC via USB.

Execute the webworks run command from the root folder of your WebWorks project, using the CLI.

C:\webworks\C2Sample>webworks run

You should be prompted for your Device Password, after which the WebWorks SDK will create and deploy a debug token, uninstall any previous versions of the application, and install the current project in debug mode; enabling Web Inspector automatically.

Building a Release Version

To release an application through the BlackBerry® World™ storefront; it must be fully signed. To do so, execute the following command from the root folder of your WebWorks project, using the CLI.

Where 123456should be replaced with your own Code Signing password, and the buildId should reflect the current version of your application. Most developers will begin at 1 and increment with each new release.

The buildId is combined with the version specified in your config.xml. For example, if your config.xmlversion is 1.0.0 and your buildId is 25, the full version of your application will be 1.0.0.25. When submitting to BlackBerry World, new releases must have a higher version than the previous release. You can achieve this by either increasing the version in config.xml, or by incrementing your buildId.

Note that 2.0.0.1 is a higher version number than 1.2.3.25.

WebWorks API Plugins

For information on including BlackBerry® Messenger and In-App Payment plugins in your Construct 2 applications, please refer to this GitHub® page:

Symptoms

If you are using an iframe to load content (for example, from a secure web server, "https://"), you will notice that starting with OS 10.2, your local JavaScript files are being blocked, and the following error appears in the Web Inspector Console:

Diagnosis

This is by design and complies with web security standards. This happens because you are attempting to load files accross protocols (https:// to local://).

Solution

The solution is using the secure window.postMessage() function to communicate between the iframe and parent page, without stepping on the cross-protocol boundaries.

The flow is as follows:

//Load the local JS file in the parent window (typically index.html)
//The parent window (typically index.html), listens for messages using:
window.onmessage = function(message) {
if (message.data === "showAlert")
showAlert();
};
//Inside the window loaded by the iframe, we need to trigger a function from inject.js, this is done by passing a message to the parent
parent.postMessage("showAlert", "*");
//Note the "*" indicates that you are not bound by any origin domains.
The parent window receives the message, and triggers whatever you like, without stepping over cross-protocol boundaries.

We are currently using EVAL push credentials, but for PROD credentials you will need to update the element to white-list the production URL.

We are using the identify and read_device_identifying_information permission to get the device's current PIN; used to dynamically send the push back to ourselves.

index.html

Push Initiator

Tap to Send Push

We start with some basic styling to display our elements in a readable fashion. When the page loads, we'll be showing Tap to Send Push in large letters in the center of the screen.

The config object must be updated.

ppgUrl: Update the cpid to match your own unique URL.

appId: Update to match the App ID provided with your own Push credentials. The digits before the hyphen (-) should match yoru cpid.

pwd: Update to match the Pwd provided with your own Push credentials; this is found under the Server section of the email.

recipient: Currently we are dynamically sending to ourselves. You can replace this with push_all to send to all recipients that are registered with your push service.

This sample application is only set up to push to one address (1 recipient or push_all.) If you want to push to multiple recipients, you will need to modify the template to include a unique element for each recipient.

data: The string that you want to send.

We use a template for the push defined in postData. Inside of this template are a number of tags that we replace with the actual push content. For example:

$(boundary), $(pushid), etc. These are simply strings that we look for and replace. The $ has no special meaning.

We then perform a standard XMLHttpRequest (Ajax) POST with our combined data.

Finally, in the load event, we are adding a touchstart listener to the main

Many developers, who have successfully produced BlackBerry® 7 applications using the BlackBerry® WebWorks™ SDK for Smartphones, are now looking to port their applications to BlackBerry® 10. In order to do so, developers are required to re-package their application content using the brand new BlackBerry 10 WebWorks SDK. Also developers may be required to make coding changes to use new APIs that take advantage of the features and capabilities of the new platform. Doing so will ensure the functionality of your application continues to function as expected on BlackBerry 10.

The BlackBerry Java® runtime is not part of BlackBerry 10 OS. As such, applications compiled using the BlackBerry WebWorks SDK for Smartphones (targeting version 5.0, BlackBerry® 6 and BlackBerry 7 device software) will not run on BlackBerry 10 devices. The content for these applications will need to be repackaged using the BlackBerry 10 WebWorks SDK.

Although a re-packaging exercise will introduce an additional step in porting your applications from BlackBerry 7 to BlackBerry 10, it is important to highlight that the Web platform is forwards compatible. This is due to the fact that both environments were designed to support standardized web technologies: HTML, CSS and JavaScript.

So all that hard work you invested into building a BlackBerry 7 application can be leveraged towards making your application successful on BlackBerry 10 as well.

There are significant hardware and software differences between the two environments. The same content running on each platform may have a very different look, feel and performance. It is entirely possible that content, designed for BlackBerry 7 will run without errors when repackaged using the BlackBerry 10 WebWorks SDK. However although your application may run on both devices, they may not behave the same.

The following are recommendations that developers can use to help identify and repair common issues they may encounter when porting applications from BlackBerry 7 to BlackBerry 10.

1. Scaling issues

The increased screen density of the BlackBerry 10 Dev Alpha places a great deal of importance on good UI and UX design. Page content that appears incorrect zoomed in or out may be difficult to interact with if it is rendered incorrectly on the 4.2” BlackBerry 10 Dev Alpha device (e.g. buttons, hyperlinks, input fields).

3. Loading screen background color

The config.xml document is used by the BlackBerry WebWorks SDK to define elements that specify application behaviors and characteristics. One of these characteristics is the default loading screen background color. The format of this element definition has been updated in order to comply with the W3C standard. If you were using the rim:loadingScreen element in your config.xml file, you must update to the new format for BlackBerry 10 (see the param element documentation).

BlackBerry 7:

BlackBerry 10:

4. Using BlackBerry 10 WebWorks APIs

The architecture of how the JavaScript® APIs are used in the BlackBerry 10 WebWorks SDK now depends on a webworks.js library. This library must be included in your project. When your application starts, this webworks.js library is loaded and it begins to load all API dependencies into memory. Once complete, the webworksready event is fired and you can begin using these APIs.

If you see runtime errors from your application that report undefined errors, it could mean that you are trying to use these blackberry.* APIs before the webworksready event has occurred.

BlackBerry 7:

Add a to config.xml for the API to be used.

Start using API.

BlackBerry 10:

Add a to config.xml for the API to be used.

Include a reference to webworks.js in your project. This file is located in the /Framework/clientFiles folder.

5. Changes to the JavaScript APIs in the BlackBerry WebWorks SDK between BlackBerry 7 and BlackBerry 10

BlackBerry WebWorks APIs are implemented using the native language of the device software. For BlackBerry 7, this was Java and for BlackBerry 10 it is C/C++. As such, there are differences in capabilities between what and how each feature can be implemented in each environment.

Please refer to the BlackBerry WebWorks API reference guide for current support. You can filter APIs in this reference guide for each platform by clicking on the appropriate links in the left side menu.

APIs that have had significant changes are highlighted in the following table:

6. Invoke APIs

The structure of how to invoke 3rd party applications changed significantly in BlackBerry 10. The brand new invocation framework is extremely powerful, far more flexible and more scalable than ever before. If your application no longer responds to certain blackberry.invoke APIs, ensure you are using the new BlacKBerry 10 format.

7. Orientation

The config.xml document is used by the BlackBerry WebWorks SDK to define elements that specify application behaviors and characteristics. One of these characteristics is the application's screen orientation (portrait, landscape or auto). The format of this element definition has been updated in order to comply with the W3C standard. If you were using the orientation element in your config.xml file, you must update to the new format for BlackBerry 10 (see the param element documentation).

BlackBerry 7:

BlackBerry 10:

8. System memory

The BlackBerry OS allocates memory in order for applications to run. If an application consumes too much memory, the OS may take corrective action to increase the amout of available system resources. These actions can include: invoking garbage collection, displaying warning messages to the user, or shutting down the running application.

Developers are highly encouraged to use remote web inspector to profile resource usage within their application. By inspecting the size and volume of page assets that are being loaded in and out of memory, developers can identify opportunities for improvement and reduce the overall memory footprint of their application.

BlackBerry 7:

If system memory is low, the applications created using the BlackBerry WebWorks SDK for smartphones will invoke a request to begin garbage collection in order to free up available system resources. When this occurs, users will see an hourglass icon appear.

The BlackBerry Smartphone device software is designed such that all third party applications that use an embedded WebView, such as those compiled from the WebWorks SDK, share the same instance of the WebKit rendering engine. This design is in place to make as efficient use as possible of limited system resources.

It is also very important to remember that the same application running on different devices may have varied performance due to the differences in available memory among each of those devices.

BlackBerry 10:

One of the strengths of the the QNX-based BlackBerry 10 OS is its efficient ability to manage memory. Each running application, including WebWorks apps, receives its own allocation of system memory that can grow in size when needed.

Application that consume too much memory may automatically be closed by the BlackBerry 10 OS if they exceed the limit of available system memory. This can more often occur when there are many simultaneous running applications. This mechanism is in place as a system failsafe to prevent runaway applications.

9. Code signing

The code signing process for signing BlackBerry applications has evolved. Since BlackBerry 7 is based on Java, the former process was designed to allow developers to sign compiled *.COD applications against the RIM signing server. The new process uses different signing keys.

BlackBerry 7:

Developers who register for BlackBerry smartphone code signing keys receive a number of *.CSI files. Once these files are installed on their computer, applications can be signed using the BlackBerry WebWorks for Smartphones SDK.

Developers who register for BlackBerry 10 code signing keys receive a number of *.CSJ files. Once these files are installed on their computer, applications can be signed using the BlackBerry 10 WebWorks SDK.

10. Background start pages

BlackBerry applications can be configured to run on startup, or continue to run when minimized.

BlackBerry 7:

To start an application when the device starts and when the application is installed, specify a background start page in config.xml. This page will automatically be run:

BlackBerry 10:

At the time of writing, invisible applications running in the background, written by 3rd party developers, are not supported on BlackBerry 10. The user must manually start the application from the home screen, or by invoking it from another application.

However, applications can be configured to run while minimized at the home screen:

To ensure that JavaScript continues to run, and is not automatically suspended by the system when the user minimized an appilcation, add the run_when_backgrounded permission to config.xml.

11. Page transition effects

A transition effect can occur when a user navigates between separate screens within a Web application. This effect provides a separation of content and confirms a change in application context. Often, developers wish to enable a slide-left or slide-right transition when the user navigates between pages.

BlackBerry 7:

A transition effect can be defined in the WebWorks configuration file. This effect is applied to the actual WebView object, and not the application content itself. On BlackBerry 7, the WebView object was a Java class called 'BrowserField'.

config.xml:

BlackBerry 10:

The WebView object (a native C/C++ class) in BlackBerry 10 does not support native transition effects and thus the config.xml loadinScreen parameter is not supported. Developers are encouraged to follow the BlackBerry 10 UI guidelines to design application structure that provides a BlackBerry 10 look and feel (tabs, context menus, etc).

The following Web frameworks follow the BlackBerry 10 UI guidelines to provide a native look and feel:

12. Focus mode (cursor) navigation

For trackpad or trackball BlackBerry devices, the default navigation scheme provides a cursor that can be used to scroll around the screen and interact with page elements. Developers who were interested in providing a native look and feel within their WebWorks applications could disable this cursor-based navigation scheme by enabling focus-mode navigation. This feature is not supported on BlackBerry 10 as there is no trackpad or trackball and thus no cursor-based navigation.

BlackBerry 7:

config.xml:

JavaScript&colon;

function moveTo(id) { blackberry.focus.setFocus(id);}

BlackBerry 10:

N/A - focus mode navigation is not available nor is the blackberry.focus API. However DOM focus events still occur when the user places focus on certain page elements: input, button, textarea, a and select.

This article is primarily directed at BlackBerry® WebWorks™ developers who have written extensions in Adobe® AIR® and would like to be able to use the free Adobe debugging tool to debug them.

For this example I will be using two custom pieces. First off we will be using my fork of @rem’s JSConsole because it is a simple WebWorks tool that will let us access the WebWorks APIs to demonstrate them. Second we are going to use my systemlog API for WebWorks because it contains the ability for WebWorks Applications to write trace statements which show up in the FDB debugger.

Everyone has used the -d option with WebWorks to bring up our old friend the Web Inspector™, but I will touch on this first.

This of course leads to one of the things that makes developing web apps for the BlackBerry® PlayBook™/ BlackBerry® 10 so much simpler than most other mobile platforms. The first time I showed some friends who were developing for other tablets the Web Inspector, they nearly flipped out.

This of course lets us be able to debug everything on the “web” side of WebWorks; diagnose problems with the UI or set breakpoints for JavaScript® debugging.

However the reason we are talking is that we want to debug the “flash” side of things, and not the JavaScript/HTML side. What if we want to debug our extensions or even if we just want to watch the trace() output from extensions?

Because I had written the extension I spoke of earlier, I had actually written some logic where I was sending trace() calls out to the debugger. However, since I had added the technology only to match the behavior of the handheld extension, I had not tested it yet.

When I presented at BlackBerry DevCon Asia on the topic back in the fall, I glossed over the fact that I was unsure how to effectively debug a running WebWorks App on the Adobe® ActionScript® Level. I in fact said, when you build with -s you should be able to open the resulting source in Adobe® Flash Builder® and it should all “Just Work.” I then added that I did not personally have a copy of Flash Builder and so I was unsure.

With a desire to actually have my extension merged in, I wanted to actually verify that it was correctly logging things. I started off here:

It's a useful KB Article about how to build using the command line tools which are freely available for debugging PlayBook applications. The real key take away on that is that you need to do two things:

I will refer back to this article later, because it also describes how to connect the debugger to a running application; but let's leave that for later.

Armed with this information I decided the next course of action would be to look at the WebWorks packager and see what could be done to manipulate it to build the way I wanted.

This meant finalizing my process of installing Maven and getting building up and running for BBWP. The instructions here are fairly detailed and functional. Once I had successfully built the BBWP tooling from GitHub®, I opened it up in Eclipse™. Which worked like a charm by making a project in the root level and importing the existing project of “packager”.

This is where I started looking around at how the code worked and that is where I discovered something special.

It seems that someone at BlackBerry wanted there to have the ability to do this.

Looking closely at the code I realized that you could change the “TARGET” to “bar-debug” by setting what was referred to as an “debugModeInternal”.

Now that I knew that it had already been done, I just needed to go and figure out how to send us down that code path.

Thankfully because WebWorks is all open source I was able to track down the command line parsing code to discover this gem.

What amazed me the most about this was it is actually in shipped versions of the WebWorks packager, at least in BBWP version 2.0.0.4. So we can simply append this option to our build and we wind up with a build we can attach the debugger to.

The resulting BAR file can be loaded onto the PlayBook simulator and we wind up with a result that looks like this on launch :

From here we need to follow the second set of instructions from the KB Article.

We need to:

Open a new command line window and run fdb.exe.

Once the program starts enter run.

Return to the simulator.

In the simulator window enter the IP address of your computer, that you are assigned by VMware®. Under IP Config it is listed as VMnet8. For my machine it is 192.168.159.1.

Press OK and alt tab back to the other command line window running fdb.

If all you care about is trace statements enter continue at the prompt. If you are more interested in complicated debugging you will have to learn how to use fdb.