Upgrading to WebWorks 2.0

With the introduction of BlackBerry 10.2, the BlackBerry WebWorks platform has aligned with the Apache Cordova open source project. Although BlackBerry WebWorks apps created for earlier versions of BlackBerry 10 will be forward-compatible, there will be no additional updates to the APIs. Moving forward, you should plan to migrate your app to BlackBerry WebWorks 2.0.

But don't worry. Migrating your app to the new Cordova-based WebWorks world is pretty simple. Migrating your app involves the following steps:

Step 1. Download and install BlackBerry 10 WebWorks SDK 2.0

You can find the SDK here. For additional information about the tools you need and how to set them up, see Setting up your tools.

The signing process has changed for BlackBerry WebWorks 2.0. Unlike previous versions, where a separate token was required to create the developer certificate (used for code signing) and debug token (used for testing unsigned apps on the device), now a single token is required. This token is associated with your BlackBerry ID.

Step 2. Create a new BlackBerry WebWorks 2.0 project

Use the BlackBerry WebWorks GUI tool to create a new project. Once created, the new project includes a default app with all the basic resources required to function as a complete app. The folder structure of your new project includes a /www folder. This folder is the working directory for your application.

For more information about creating a new BlackBerry WebWorks 2.0 project, see Creating a WebWorks project.

Step 3. Replace the template resources in your new project with your existing resources

Delete the template project resources in your new BlackBerry WebWorks 2.0 project folders and paste your application resources in their place. All your HTML files should be placed in the /www folder; your CSS, JavaScript, and image files can be placed in the appropriate subfolders of the /www folder.

You can choose to copy over your existing config.xml file, or build a new one based on the template config.xml. However, in either case, you should be aware that the structure of the config.xml file has changed slightly in BlackBerry WebWorks 2.0. As a result, you may need to make some manual modifications to your config.xml file. For more information on changes to the config.xml file, see Changes to the config.xml file.

Step 4. Add plugins to your project

Unlike previous versions of BlackBerry WebWorks, BlackBerry WebWorks 2.0 uses plugins to add APIs to your app. A plugin is a set of APIs you can use to access features of the platform. You'll need to add a plugin for each of the BlackBerry WebWorks APIs you use in your app. These plugins correspond to the <feature> elements you added to your old config.xml file.

For more information about plugins, including which you should add and how to add them, see Changes to the way you add APIs to your app.

Step 5. Update your source code

Once you have copied over your resources and added the necessary plugins to your project, there are a few minor code changes that may be required so that your code is compatible with the new architecture:

  • Include cordova.js instead of webworks.js.
  • Listen for the deviceready event instead of the webworksready event.

To get all the details on updating your code, see Coding differences.

Step 6. Build and test

With the previous steps completed, you can begin building and testing your app to make sure it is functioning as expected.

Use the BlackBerry WebWorks GUI tool to build your app in debug mode.

BlackBerry WebWorks 2.0 includes a number of improvements to the build process. Now, with a single command, you can create and install a debug token on a BlackBerry 10 device, and build, install, and launch your app on the device.

See Building and Testing to get all the details.

Last modified: 2014-03-10

comments powered by Disqus