Articles and samples about developing for BlackBerry 10 using WebWorks or the BlackBerry Browser.


    • WebWorks to Android migration guide for Apache Cordova

      Published Feb 09 2018, 2:17 PM by ctetreault

      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




      Upgrade Cordova and WebWorks

      Update Plugins

      Install Android SDK, and Android Studio

      Install SDK Packages


      Splash Screens
      Plugins and APIs

      Testing Your App

      Building for Release

      Test Case

      API Mapping





      Backup your code!


      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.


      For additional information, Tim Windsor wrote a great blog post on upgrading your project to Cordova 5.x and WebWorks 3.8. I highly recommend you read it before continuing past this point.


      Update Cordova:

      $ npm update –g cordova




      Update WebWorks (From your project’s root folder):

      $ cordova platform update blackberry10



      Update Plugins


      As of Cordova 5.x, the plugin naming convention has changed for the better. Any old plugins should be replaced with their updated versions. For example:


      Old Plugin ->

      New Plugin -> cordova-plugin-bb-app


      A full list of renamed Cordova plugins can be found.



      Install the Android SDK, and Android Studio


      Now that your project’s running the latest plugin, let’s look at adding the Android platform to the mix.


      First, install the Android SDK and its dependencies. I highly recommend doing this by installing Android Studio so you can take advantage of the native tools for debugging, plugin development, etc.



      Install SDK Packages


      Next, install additional Android SDK packages. Do this by opening the Android SDK Manager.


      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





      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.


      Refer to the official Cordova Config.xml documentation for in-depth platform specific configurations.




      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.


      1. Remove the BlackBerry specific API

        $ cordova plugin remove cordova-plugin-bb-camera

      2. Add the Cordova plugin:
        $ cordova plugin add cordova-plugin-camera
      3. 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.


      Check your environment setup:

      $ cordova requirements



      If you’re still stuck, head on over to the Cordova documentation and see the official Cordova Android Platform Guide.

    • jQuery Deferred

      Published Feb 09 2018, 2:17 PM by aviyehuda

      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.


      Deferred lets you add multiple callbacks to long lasting operation calls like Ajax requests.


      Long lasting operations without JQuery Deferred


      If you haven’t used deferreds, this is probably how you do long lasting actions like Ajax calls.

      $.get("/myservice/x/1",function(data,status){alert ('example')})



      Long lasting operations like Ajax require a callback function.
      In this case, the callback is given as a parameter to the caller.

      This is fine, but there is a way to add a callback separately from the call.

      var myPromise = $.get("/myservice/x/1");
      myPromise.done(function(data,status){alert ('ok')}),status){alert ('failed')}) 

      Try it



      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.notify()   Triggered
      deferred.notifyWith()   Triggered
      deferred.reject()Triggered Triggered 
      deferred.rejectWith()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.

      These are the steps:

      1. Create a Deferred inside your function.
      2. Use the Deferred to trigger events.
      3. Return the Promise object.

      See this simple example:

      myLongLastingOperation = function(time) {
        var myDeferred = $.Deferred();
        setTimeout(myDeferred.resolve, time);
        return myDeferred.promise();
      myPromise = myLongLastingOperation(1000);

      Try it


      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.



      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.

      myLongLastingOperation = function(time,numOfCount) {
       var  myDeferred = $.Deferred();
         function wait(counter){

      Try it


      Not impressed yet? Meet ‘when’

      We saw that you can add multiple callbacks to Deferreds and Promises.
      ‘when’ lets you do the same thing but it can do it for multiple Deferreds all at once.

      myLongLastingOperation = function(time) {
       var  myDeferred = $.Deferred();
       setTimeout(function(){myDeferred.resolve();}, time);
       return myDeferred.promise();
      myPromise = $.when( 

      Try it


      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:

      var myPromise = $.get('non_exiting.php');
      myPromise = myPromise.then(
          function(){return $.Deferred().resolve("ok")},
          function(){return $.Deferred().resolve("ajax failed but still we pass")});
      myPromise.done(function(message){document.write('done: '+message);});{document.write('error: '+message);});

      Try it


      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( quite successfully.

    • HeadlessService template fails to build functioning headless app.

      Published Feb 09 2018, 2:17 PM by oros


      You will not be able to deploy a functioning headless app.



      The HeadlessService template project generated by "webworks create-headless" is currently missing two Makefiles. For the project to build please do the following:


      1. Download the following file into the HeadlessService folder:


      2. Download the following file into the HeadlessService/translations folder:

    • How To - Create a URL Launching Application for BlackBerry 10

      Published Feb 09 2018, 2:17 PM by oros

      Applies To


      • BlackBerry® 10.1+
      • BlackBerry® WebWorks SDK

      For information on creating a launcher application for the BlackBerry® PlayBook™ tablet, please refer to this document:


      For information on creating a launcher application for legacy BlackBerry® OS devices, please refer to this document:




      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.



      BlackBerry WebWorks SDK


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


      During the installation, be sure to install start menu shortcuts for ease of access. Once installed, you will need to download and configure your Code Signing keys.


      Code Signing


      Create a BlackBerry ID (if you haven't already) and download your BlackBerry 10 Code Signing token to your PC from the following location:


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


      Start > BlackBerry > BlackBerry WebWorks SDK

      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 Token Location 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.


      Creating Your Launcher Application


      Click the + icon in the Recent Projects pane to create a new project.




      Fill in the fields as follows:

      • Project ID: A unique, reverse-domain URL that will identify your application.
      • Project Name: The user-friendly version of your application name.
      • Project Path: The path where you want your application to be created.

      Once complete, click the Create button.


      Under your newly created application, select the Configuration pane.




      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:



      Access List > Origin

      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.


       This would whitelist:

      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.

    • Porting Your Existing Construct 2 Application to BlackBerry 10 (WebWorks SDK 2.0+)

      Published Feb 09 2018, 2:17 PM by oros

      If any errors are found or questions arise, please feel free to comment on this KB or contact directly.


      The information within assumes familiarity with Construct 2, up to the point that you are able to develop your application and are now ready to export your project for various platforms.


      For information on developing with Construct 2, please refer to the following.


      BlackBerry WebWorks SDK 2.0


      You can download the most recent version of the BlackBerry® WebWorks™ SDK 2.0 here:


      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.


      Code Signing Keys


      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.


      In either case, instructions can be found here:


      Exporting For BlackBerry 10


      At this point, there are three assumptions. You have:

      1. Installed the latest BlackBerry WebWorks SDK 2.0.
      2. Configured your BlackBerry 10 Code Signing keys.
      3. Developed your Construct 2 application.

      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


      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



      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.




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


      File > Export Project... > Web (HTML5 Website)


      The export option for Mobile (BlackBerry 10) refers to the legacy BlackBerry 10 WebWorks SDK 1.0.


      In the Export Options dialog, for Export Files To, choose the www sub-folder of your WebWorks project; this is the same folder from which we previously deleted the default files.




      The remaining items can remain as they are, though you may wish to enable Minify Script for production releases. Once configured, click Next.


      In the HTML Export Options dialog, you can choose the option that best fits your project. If you are unsure, choose Embed Style. Once configured, click Export.


      This should generate your Construct 2 application within your BlackBerry 10 WebWorks project folder; specifically the www sub-folder.


      Update config.xml


      Before you can build your project, we will need to make a few changes to the config.xml file in our root www folder. Example:





      You can open this file with any standard text editor. The default values that will need to be changed are highlighted in blue below.



      webworks.default" version="0.0.1" xmlns="" xmlns:cdv="">
          WebWorks Application
              A sample Apache Cordova application that responds to the deviceready event.
" href="">
              Apache Cordova Team


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


      Building and Deploying a Debug Version


      To test your newly exported project on a BlackBerry 10 device:

      1. Switch your device to Development Mode by navigating: Settings > Security and Privacy > Development Mode > Development Mode: On.
      2. Connect your device to your PC via USB.
      3. 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.


      C:\webworks\C2Sample>webworks build --release --keystorepass 123456 --buildId 25

      Where 123456 should 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.xml version is 1.0.0 and your buildId is 25, the full version of your application will be 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 is a higher version number than


      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:

    • Local JavaScript files are blocked when loaded from within an iframe.

      Published Feb 09 2018, 2:17 PM by anzor_b


      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:


      [blocked] The page at ran insecure content from local:///js/custom.js"


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


      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 ( === "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.

      More on window.postMessage on Mozilla's Developer Network


      Attached is a sample, where a button inside the iframe triggers a function which is loaded locally.

    • Client-Side Push Initiator

      Published Feb 09 2018, 2:17 PM by oros

      See the basic client/initiator sample implementation on Github here:


      Feel free to ask any questions.


      In this sample, the device will send the push back to itself for the purpose of being received by another application on the device, but it can be modified to send to other devices as well.


      The client-side Push Receiver is implemented in the same way as we've always done. For more information, please see:




          Push Initiator
          Erik Oros
" subdomains="true" />


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




              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.


              • dataThe 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 
               element to allow us to initiate a push.

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

      Published Feb 09 2018, 2:17 PM by astanley

      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:



      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.
      • Start using the API after the webworksready event has occurred.
      • See the Getting started with BlackBerry 10 documentation for more info.

      Example config.xml:


      Example source.js: 

      //register ready event after window has loaded
      window.addEventListener("load", function (e) {
          document.addEventListener("webworksready", function() { 
           console.log("webworksready: " +;
      }, 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? and 


      blackberry.eventUse blackberry.event. addEventListener("eventname", function) to register  for application or system events
       blackberry.bbm.platformNew API
      blackberry.invoke. * Argumentsn/a"Arguments" classes no longer supported (see following section - Invoke APIs - for more details)
      blackberry.invoke.invokeblackberry.invoke.invokeNew invocation framework (see following section - Invoke APIs - for more details) and

      HTML5Use HTML standard navigator.getUserMedia() for camera and microphone access
      blackberry.systemblackberry.connectionNew API for getting device radio information
      blackberry.ui.dialogblackberry.ui.dialogNot all formatting constants are supported and

      HTML5Use HTML standard FileReader for file system access
      blackberry.identity.PINblackberry.identity.uuidPIN property changed to uuid
       blackberry.pushNew API
      blackberry.audioHTML5Use HTML standard audio element 




       n/a APIs not available.
      blackberry.phonen/aLaunch the phone application using invoke link





      blackberry.pim.calendarThe 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.menun/aMenu hardware button no longer available. See UI guidelines for designing your own overflow menus or tab bars.
      blackberry.pushblackberry.pushUse 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.contactsUse new contacts object.  Example
      blackberry.messageNotificationUse 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('');
      blackberry.invoke.invoke(blackberry.invoke.APP_BROWSER, args);


      BlackBerry 10:



         uri: ""
      }, 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:



      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.


      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:




      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 event to listen for when the user has minimized the application.
      • Use the 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'.






      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:









      function moveTo(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.



    • How to enable FDB with WebWorks

      Published Feb 09 2018, 2:17 PM by haagmm

      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:

      • Call amxmlc -compiler.debug

      Normally you just call without the flag.


      • Once you have an SWF file, call blackberry-airpackager -target bar-debug -connect [YOUR COMPUTER'S IP ADDRESS]

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


      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.


      You will then see trace statements as your applications progresses.



      I hope that someone found that helpful.


      Thank you.

    • Parent element's CSS :active pseudo class does not trigger due to touch events not propagating down in CSS.

      Published Feb 09 2018, 2:17 PM by anzor_b


      When creating custom controls that expect touch input, touching on a child element does not trigger the :active pseudo class on the parent container.




      Some more text

       If you click on the


      , the button's CSS :active pseudo class will NOT get triggered, while the JavaScript® event propagates without issues.


      This issue has been logged and is being investigated internally.


      Note: this does not affect the touch event propagation in JavaScript, only in CSS.


      This issue has been logged and is being investigated internally.



      Add a CSS :after pseudo class.



       Note: for this trick to work, the buttons position needs to be explicitly specified as "relative":


      .myButton {
       position: relative;
      .myButton:active {
       background: blue;
      .myButton:after {
       content: "";
              position: absolute;
              left: -10px;
              right: -10px;
              top: -10px;
              bottom: -10px;

       This will create an empty element that spans across the parent element, but is located "after" the element itself and its children, which will trigger the :active pseudo class without issues.

    11 pages