DEVELOPERS BLOG
  1. Developers Blog
  2. Porting your apps to BlackBerry 10 using WebWorks SDK 2.0

Porting your apps to BlackBerry 10 using WebWorks SDK 2.0

OPEN SOURCE / 12.03.13 / adamstan1

As Ken recently announced, the BlackBerry 10 WebWorks SDK is now powered by the Apache Cordova engine. For existing WebWorks developers, this means that there are some changes they need to be aware of to update their applications with the new SDK.

This article describes these changes in detail and provides a walkthrough on how to repackage an existing WebWorks application using the newly released version 2.0 of the BlackBerry 10 WebWorks SDK. I will show you how to port a hypothetical “Bacon Recipes” application, and I encourage you to follow along with these steps and port your own application in tandem. In fact, these instructions were used to update the 40+ sample applications in the BB10-WebWorks-Samples Github repository to the new WebWorks 2.0 SDK format.

Ready?  Here we go …

Step 1: Create a new project

  1. From your Start menu click on the “BlackBerry WebWorks 2.0.0.51” menu item. A new browser window will be launched showing the WebWorks SDK.
  2. Enter baconRecipes in the project name field.
  3. Enter your own <workspace path> in the project path field.
  4. Click the Create button.

Figure 1 Creating a project using the WebWorks SDK

Figure 1: Creating a project using the WebWorks SDK

If you look at your file system, you will notice the create command produced a baconRecipes project in your workspace folder. This project contains a number of subfolders that are used by the SDK to manage the assembly and packaging of your application. The most important folder for you to note is /www since it is where your application assets are stored. The create command produced a /www folder containing assets for a default application.

Figure 2 The folder structure produced by webworks create

Figure 2: The folder structure produced by WebWorks create

Step 2: Test the default application

From the WebWorks SDK, click on the Build menu under baconRecipes project listing

  1. Connect a BlackBerry 10 device to USB and enable development mode.
  2. Enter your device password and code signing keystore password.
  3. Click build & install.

Or

  1. Start a BlackBerry 10 simulator.
  2. Change the build target from Device to Simulator.
  3. Click build & install.

Figure 3 The default application produced by webworks create

Figure 3: The default application produced by WebWorks create

Step 3: Move your existing application assets into the newly-created project

  1. Replace the contents of baconRecipes/www with your own application’s source.
    • First delete all files found within baconRecipes/www
    • Copy your existing application assets into baconRecipes/www

Figure 4 Example of actual application assets for baconRecipes now in www folder

Figure 4: Example of actual application assets for baconRecipes now in /www folder

Step 4: Update the application source code to support the new SDK

The most common changes a developer may need to make are the following:

1. Find and replace all references of webworks.js with cordova.js in your app.

  • Before:  <script src=”local:///chrome/webworks.js”></script>
  • After:  <script src=”cordova.js”</script>

2. Find and replace all references of the webworksready event with deviceready in your app.

  • Before: document.addEventListener(‘webworksready’, onReady, false);
  • After: document.addEventListener(‘deviceready’, onReady, false);

3. Update any access elements in config.xml to use the origin attribute instead of uri.

  • Before: <access uri=”http://domain.com”></access&gt;
  • After: <access origin=”http://domain.com”></access&gt;

I would also encourage you to review the “Differences between WebWorks and WebWorks 2.0” documentation for any further changes that may need to be made, such as feature <params> defined in config.xml are now declared as <preference> elements.

Step 5: Add plugins for any APIs used in your application

The WebWorks SDK is now powered by the Cordova engine which means that the application packaging process for WebWorks has been aligned with how applications are packaged for Cordova.  Existing WebWorks developers will notice a major difference in how <feature> elements are integrated into your application during the packaging process. All APIs must now be configured first by adding a corresponding plugin to the project.

For every <feature> element defined in baconRecipes/www/config.xml

<feature id=”blackberry.app” />

<feature id=”blackberry.invoke” />

<feature id=”blackberry.ui.toast” />

You must run the following commands from within the baconRecipes folder. Note: in the BETA version of the WebWorks SDK, you are required to add plugins manually. However the dev team is hoping to include a plugins page in a future version of the browser-based SDK.

  1. Open a command prompt (windows) or terminal window (mac).
  2. cd <workspace path>baconRecipes
  3. webworks plugin add com.blackberry.app
  4. webworks plugin add com.blackberry.invoke
  5. webworks plugin add com.blackberry.ui.toast

That should be it for porting your app. Now repeat Step 2 to re-build and test your application on a device/simulator. You should see your application successfully launch. If you notice any errors within your application, I would suggest troubleshooting using Web Inspector. There may be additional changes required, as mentioned in step 4.

Figure 5 The finished product, repackaged using the new WebWorks SDK

Figure 5: The finished product, repackaged using the new WebWorks SDK

If you get stuck, ask us in the comments here, at @BlackBerryDev on Twitter, or the Official BlackBerry Developer Facebook page! We’re here to help. Good luck and happy coding.

About adamstan1

Back