How to: Migrate your BlackBerry WebWorks application from BlackBerry Tablet OS to BlackBerry 10

by Retired on ‎11-16-2012 11:41 AM - edited on ‎11-16-2012 11:58 AM by Retired (4,634 Views)

Many developers, who have successfully produced BlackBerry® PlayBook™ applications using the BlackBerry® WebWorks™ SDK for Tablet OS, are now looking to port their applications to BlackBerry® 10.  Developers are highly encouraged to re-package their application content using the brand new BlackBerry 10 WebWorks SDK and port to use new APIs in order to take advantage of the features and capabilities of the new platform.  Doing so will ensure all features within your application behave as expected on BlackBerry 10.

 

However in many cases, these existing BlackBerry Tablet OS applications will run without requiring a recompile. The reason for this is because both BlackBerry 10 and BlackBerry Tablet OS support the Adobe® AIR® runtime.  As you may remember, the BlackBerry WebWorks SDK for Tablet OS produced an application that was actually an AIR container, surrounding your application content (HTML, CSS, JavaScript®).  Since both OS’s support the same runtime, your application can run on both devices.

 

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

 

However, it is important to highlight that there are hardware and software differences between the two environments and these differences may have significant impact on the look and feel of your application. Although your application may run on both devices, they may not behave the same. 

 

In fact, the BlackBerry App World™ team has completed their own initial round of testing and is proactively notifying developers of their feedback. Some developers are being informed that their applications are already approved for BlackBerry App World distribution for BlackBerry 10, while others are being encouraged to update their BlackBerry Tablet OS applications using the new BlackBerry 10 WebWorks SDK.

 

The following are recommendations that developers can use to rapidly identify and repair common issues.

 

 

Quick Fixes (Porting BlackBerry WebWorks apps from BlackBerry Tablet OS to BlackBerry 10):

 

  1. Scaling issues
  2. Home screen icons
  3. Loading screen background color
  4. Using BlackBerry 10 WebWorks APIs
  5. Changes of WebWorks APIs between Tablet OS and BlackBerry 10
  6. Invoke APIs
  7. Orientation
  8. Adobe® Flash® support

 

 

 

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.  Content designed for the larger 7” screen on the BlackBerry PlayBook tablet may not be as user-friendly on the 4.2” BlackBerry 10 Dev Alpha device (e.g. interacting with buttons, hyperlinks, input fields). Page content can appear incorrect zoomed in or out.

 

Developers are encouraged to design their page content to scale appropriately for the given screen resolution.  This can be done correctly using CSS or by defining a viewport.  See How to set up the viewport for a BlackBerry WebWorks application for BlackBerry 10.

 

BlackBerry Tablet OS:

 

  • Screen resolution: 1024 x 600 (BlackBerry PlayBook tablet)
  • Pixel density: 169 dpi

 

BlackBerry 10: 

 

  • Screen resolution: 1280 x 768 (BlackBerry 10 Dev Alpha device)
  • Pixel density: 355 dpi

 

 

2. Home screen icons

 

Due the richer screen density of the BlackBerry 10 Dev Alpha device, home screen icons may need to be resized in order to achieve the highest quality of screen resolution.

 

BlackBerry Tablet OS:

 

  • Dimensions: 86 x 86

 

BlackBerry 10:

 

 

 

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 Tablet OS:

 

<rim:loadingScreen backgroundColor="#ff0000" />

 

BlackBerry 10:

 

<feature id="blackberry.app">
    <param name="backgroundColor" value="0xffff0000" />
</feature>

 

 

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 Tablet OS:

 

  • Add a <feature> to config.xml for the API to be used.
  • Start using API.

 

BlackBerry 10:

 

  • Add a <feature> to config.xml for the API to be used.
  • Include a reference to webworks.js in your project. This file is located in the <SDK install>/Framework/clientFiles folder.
  • Start using the API after the webworksready event has occurred.
  • See the Getting started with BlackBerry 10 documentation for more info.

Example config.xml:

<feature id="blackberry.app" required="true" version="1.0.0.0"/>

 

Example source.js: 

//register ready event after window has loaded
window.addEventListener("load", function (e) {
    document.addEventListener("webworksready", function() { 
    	console.log("webworksready: " + blackberry.app.name);
    })
}, false);

 

 

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

 

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:

 

 

Before (BlackBerry Tablet OS) Now (BlackBerry 10) What has changed?

blackberry.app.event and 

blackberry.system.event

blackberry.event Use blackberry.event. addEventListener("eventname", function) to register  for application or system events
  blackberry.bbm.platform New API
blackberry.invoke. * Arguments n/a "Arguments" classes no longer supported (see following section - Invoke APIs - for more details)
blackberry.invoke.invoke blackberry.invoke.invoke New invocation framework (see following section - Invoke APIs - for more details)

blackberry.media.camera and

blackberry.media.microphone

HTML5 Use HTML standard navigator.getUserMedia() for camera and microphone access
blackberry.system blackberry.connection New API for getting device radio information
blackberry.ui.dialog blackberry.ui.dialog Not all formatting constants are supported

blackberry.io.dir and

blackberry.io.file

HTML5 Use HTML standard FileReader for file system access
blackberry.identity.PIN blackberry.identity.uuid PIN property changed to uuid
  blackberry.push New API

 

 

 

 

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.

 

BlackBerry Tablet OS:

 

var args = new blackberry.invoke.BrowserArguments('http://www.blackberry.com');
blackberry.invoke.invoke(blackberry.invoke.APP_BROWSER, args);

 

BlackBerry 10:

 

 

blackberry.invoke.invoke({
   uri: "http://www.blackberry.com"
}, onInvokeSuccess, onInvokeError);

 

 

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 Tablet OS:

 

<rim:orientation mode="portrait" />

 

BlackBerry 10:

 

<feature id="blackberry.app.orientation">
   <param name="mode" value="portrait" />
</feature>

 

 

8. Adobe Flash support

 

The mobile Flash player was enabled by default within BlackBerry WebWorks applications running on BlackBerry Tablet OS. This has changed in BlackBerry 10. Flash Player is disabled by default but can be enabled by the developer by defining a feature in config.xml.

 

BlackBerry Tablet OS:

 

No action required by developers. Flash Player is enabled by default.

 

BlackBerry 10:

 

Add the following feature to config.xml:

 

<feature id="enable-flash"/>