Upgrading from WebWorks 1.0

As of BlackBerry 10 OS version 10.2, the BlackBerry WebWorks platform has aligned with the Apache Cordova project. Although BlackBerry WebWorks 1.0 apps are forward-compatible and will continue to run, 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 the latest BlackBerry 10 WebWorks SDK

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

The signing process has changed as of BlackBerry WebWorks 2.0. Unlike BlackBerry WebWorks 1.0, 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 BlackBerry WebWorks project

Use the BlackBerry 10 WebWorks SDK web tool to create a 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, 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 for BlackBerry WebWorks 2.0 and later. 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

As of BlackBerry WebWorks 2.0, WebWorks apps use plugins to add APIs to your app. A plugin provides a set of APIs, and includes the bindings between JavaScript and the native C/C++ layer of the BlackBerry 10 OS. You 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 that it is functioning as expected.

Use the BlackBerry 10 WebWorks SDK web tool to build your app in debug mode.

BlackBerry WebWorks 2.0 introduced a number of improvements to the build and deploy process used in BlackBerry WebWorks 1.0. 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-12-04

Got questions about leaving a comment? Get answers from our Disqus FAQ.

comments powered by Disqus