How to: Migrate your BlackBerry WebWorks application from BlackBerry 7 to BlackBerry 10

by Retired on ‎09-16-2013 01:58 PM (2,238 Views)

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.

 

 

Quick Fixes (Porting BlackBerry WebWorks apps from BlackBerry 7 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 BlackBerry 7 and BlackBerry 10
  6. Invoke APIs
  7. Orientation
  8. System memory
  9. Code signing
  10. Background start pages
  11. Page transition effects
  12. Focus mode (cursor) navigation

 

 

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).

 

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

 

  • Screen resolution:
    • 480 x 640 (BlackBerry® Bold™ 9900 smartphone)
    • 640 x 480 (BlackBerry® Torch™ 9810 smartphone)
  • Pixel density: 188 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 7:

 

  • Dimensions: 92 x 92 pixels

 

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

 

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

 

  • 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 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:

 

 

Before (BlackBerry 7) 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
blackberry.audio HTML5 Use HTML standard audio element 

blackberry.pim.category

blackberry.pim.memo

blackberry.pim.task

 n/a  APIs not available.
blackberry.widgetcache n/a  
blackberry.phone n/a Launch the phone application using invoke link

blackberry.invoke.CalendarArguments

blackberry.pim.appointment

blackberry.pim.attendee

blackberry.pim.reminder

blackberry.pim.calendar The new Calendar object can be used to create and find date objects. Example.
blackberry.focus  n/a  Focus mode navigation is no longer supported
blackberry.ui.menu n/a Menu hardware button no longer available. See UI guidelines for designing your own overflow menus or tab bars.
blackberry.push blackberry.push Use PushService object now to leverage the BlackBerry push architecture (BIS or BES)
blackberry.url  n/a  url API no longer supported
blackberry.utils  n/a  utils API no longer supported

blackberry.pim.contact

blackberry.pim.address

blackberry.pim.contacts Use new contacts object.  Example
blackberry.message Notification Use new Notifcation object.  Example

 

 

 

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

 

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

 

<rim:orientation mode="portrait" />

 

BlackBerry 10:

 

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

 

 

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.

 

Review the documentation for instructions on how to sign BlackBerry smartphone applications.

 

BlackBerry 10:

 

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.

 

Review the documentation for instructions on how to sign BlackBerry 10 applications.

 

 

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:

 

<content>
   <rim:background src="listener.html" runOnStartup="true" />
</content>

 

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.
  • Use the blackberry.app.pause event to listen for when the user has minimized the application.
  • Use the blackberry.app.resume event to listen for when the user has maximized the application.

 

 

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:

 

<rim:loadingScreen backgroundColor="#AAA000" onLocalPageLoad="true">
   <rim:transitionEffect type="zoomIn" />
</rim:loadingScreen>

 

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:

 

<widget>
    <rim:navigation mode="focus"/>
    <feature id="blackberry.ui.dialog"/>
</widget>

 

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.