Porting apps from the PlayBook OS to BlackBerry 10

Because of the differences in hardware features and the differences in some of the BlackBerry WebWorks APIs between BlackBerry PlayBook OS and BlackBerry 10 OS, and because of the availability of new BlackBerry WebWorks APIs for BlackBerry 10, you might need to port your existing app for the PlayBook OS to make it work on BlackBerry 10. If your app runs, you don't need to read this guide and are ready to distribute your app. If your app runs but you make changes to your application other than the source code (eg, change app icon image file), all you need to do is Repackage your app.

If you need to port your app, here are some tasks that you might need to complete:
  • Modify the UI and other design elements to adjust the look and feel of your app.
  • Update your source code to support changes in the BlackBerry WebWorks APIs.
  • Enable Adobe Flash support in the config.xml file, if your app uses Flash.
  • Repackage your app using the BlackBerry 10 WebWorks SDK.

Modify the UI and other design elements

Here are some differences between the PlayBook OS and BlackBerry 10 that you should consider as you adjust the look and feel of your app for BlackBerry 10. Note that any configuration specified using XML elements are done in the config.xml file.

  PlayBook OS BlackBerry 10
Display resolution 1024 x 600 pixels 1280 x 768 pixels
Pixel density 169 ppi 355 ppi
App icon on home screen 86 x 86 pixels 114 x 114 pixels
Screen orientation
Specified using the rim:orientation element. The following modes are supported:
  • auto
  • portrait
  • landscape
  • north

Example:

<rim:orientation mode="portrait"/>

Specified using the param element. The following modes are supported:
  • auto
  • portrait
  • landscape

Example:

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

Splash screen background color

Specified using the rim:loadingScreen element. Color must be expressed in the RGB pixel format using 6 hexadecimal digits prefixed with #.

Example:

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

Specified using the param element. Color must be expressed in the ARGB pixel format using 8 hexadecimal digits prefixed with 0x.

Example:

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

Splash screen image

Specified using the rim:loadingScreen element.

Example:

<rim:loadingScreen foregroundImage="filename" />

Specified using the rim:splash element.

Example:

<rim:splash src="filename" />

Further reading

Update your source code

If you have not used any BlackBerry WebWorks APIs in your app and you make changes to your source code, all you need to do is Repackage your app. If you used BlackBerry WebWorks APIs in your app and you make changes to your source code, you must perform some required updates to your source code before you repackage your app.

In terms of apps that use BlackBerry WebWorks APIs, there are two differences related to the API usage between PlayBook OSand BlackBerry 10: One difference is in the way you include the APIs in your app through config.xml, and the other is how the APIs are invoked in your code.

To illustrate, let's assume that you want to invoke the blackberry.app.name property to retrieve the name of your app (which you specified in the config.xml file).
  • In this example, in the config.xml file you add the following feature element (same as you would for PlayBook OS):
    <feature id="blackberry.app" required="true" version="1.0.0.0"/>
  • Include a reference to the webworks.js file in your project. (The webworks.js file is located at <BlackBerry 10 WebWorks SDK installation location>/Framework/clientFiles folder).
  • Invoke BlackBerry WebWorks APIs only after the webworksready event occurs.
    In this example, in your JavaScript source you invoke blackberry.app.name after you add an event listener for the webworksready event, similar to the following:
    //register ready event after window has loaded
    window.addEventListener("load", function (e) {
        document.addEventListener("webworksready", function() { 
        	console.log("webworksready: " + blackberry.app.name);
        })
    }, false); 

The table below lists the APIs that have changed significantly and summarizes the differences. If you used any BlackBerry WebWorks APIs that have changed, update your code accordingly.

PlayBook OS BlackBerry 10 Summary of change

blackberry

.app.event

and

blackberry

.system.event

blackberry

.event

To register for application or system events, use the following:

blackberry.event .addEventListener("eventname", callbackfunction)

blackberry

.invoke.*Arguments

Not available

*Arguments classes are no longer supported.

blackberry

.invoke.invoke

blackberry

.invoke.invoke

The format for invoking other applications is different. For example, in PlayBook OS, you invoke the BlackBerry Browser and open the www.blackberry.com website as follows:

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

For BlackBerry 10, you invoke the BlackBerry Browser and open the www.blackberry.com website as follows:

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

blackberry

.media.camera

and

blackberry

.media.microphone

Not available

Camera and microphone access is now supported through the HTML5 standard navigator.getUserMedia()

blackberry

.system

blackberry

.connection

A new API exists for getting device radio information.

blackberry

.ui.dialog

blackberry

.ui.dialog

Not all formatting constants are supported.

blackberry

.io.dir

and

blackberry

.io.file

Not available

File system access is now supported through the HTML5 standard FileReader.

blackberry

.identity.PIN

blackberry

.identity.uuid

PIN property changed to uuid.

Enable Flash support

By default, the mobile Adobe Flash Player is enabled for BlackBerry WebWorks apps on the PlayBook OS. On BlackBerry 10, the Adobe Flash Player is disabled by default. So if your app uses Flash, you must enable support for it. To do this, add the following line to your config.xml:
<feature id="enable-flash"/>

Repackage your app

After you make the necessary changes to the config.xml file and to your application's source code, you must repackage your app using the BlackBerry 10 WebWorks SDK. You package your app using the BlackBerry 10 WebWorks SDK the same way you package your app using the BlackBerry WebWorks SDK for PlayBook OS.

Last modified: 2013-09-19