BlackBerry 10 WebWorks SDK Released!

Announcements

We are super excited to announce that the BlackBerry® 10 WebWorks™ SDK is now available for download! This is the first of many Beta releases to come over the summer as we head towards the official release of the BlackBerry 10 WebWorks SDK. Eager web application developers should head right to the developer site, download the SDK, and see how we are continuing to provide a best-in-class web developer platform for BlackBerry 10.

The BlackBerry 10 WebWorks SDK allows web developers to create first class BlackBerry applications using familiar web technologies such as HTML5, CSS, and JavaScript®, and extend their application with deep integration into the full device platform. It is the evolution of the BlackBerry WebWorks SDK, built on the foundations of the BlackBerry WebWorks SDK for smartphones and the BlackBerry WebWorks SDK for Tablet OS.

First introduced on the BlackBerry® 5 OS and supported on all OS versions and devices since, BlackBerry WebWorks allows a developer to package their web content into the native application format, leveraging all the benefits of the BlackBerry platform including security and distribution through the BlackBerry App World™ storefront. With the WebKit-based HTML5 browser environment provided by the platform, BlackBerry WebWorks developers have full access to many powerful HTML5 APIs and CSS3. Further, BlackBerry WebWorks provides a set of JavaScript APIs that allow the developer to extend their web content out of the browser with platform functionality such as BlackBerry® Messenger SDK, Payment Service, PIM (email, contacts, and calendars), file access, and so on.

For the BlackBerry smartphone, the BlackBerry WebWorks APIs were built on the native Java platform, and for Tablet OS, on top of the Adobe® AIR® SDK. With BlackBerry 10, it was obvious that BlackBerry WebWorks needed to leverage the full power of the new BlackBerry 10 Native platform built on C/C++ and Cascades™. This gave us an opportunity to look at BlackBerry WebWorks with fresh eyes and determine the best route forward. Let’s take a look at the different pieces that make up BlackBerry WebWorks and how we have been able to improve on the platform with the power of BlackBerry 10.

The Packager

This is the piece of the SDK that takes you application content and packages it up into a .BAR file for distribution in BlackBerry App World™, and is the file that is installed onto the device. For BlackBerry OS and Tablet OS, the packager was implemented in Java, which required the developer to have the JDK installed on their machine. For BlackBerry 10 WebWorks SDK, we have re-implemented the packager in pure JavaScript, which runs in an instance of Node.js included with the SDK. BlackBerry WebWorks developers have minimal external dependencies required to get their development environment setup.

One thing to note is that the packager now creates two binary outputs, one for the device and one to be used in the BlackBerry 10 simulator. This is because the BlackBerry WebWorks runtime is now backed by the native platform, and there are different instruction sets for the OS on desktop environments versus the device platform.

The Framework

The framework is the code that wraps around your web content, and is run on the device in order to orchestrate the platform and provide your runtime environment. For BlackBerry OS, the framework was in Java, and for Tablet OS it was Adobe AIR. Similar to the packager, and enabled by the underlying platform providing in essence a JavaScript runtime environment, we have re-written the framework in JavaScript.

Since the framework is in JavaScript, developers will need to include this JavaScript code into their web content for their application. Just add a very simple script tag to all your pages:

<script type=”text/javascript” src=”webworks.js”></script>

Webworks.js is the framework code that handles all of the BlackBerry WebWorks whitelisting logic and injection of allowed APIs for the current domain into the current page. The webworks.js file is included in the BlackBerry WebWorks SDK in the framework\clientfiles directory and should be copied into your application content.

Since script loading can occur asynchronously, we have provided an event that you must listen to before accessing any BlackBerry WebWorks APIs. The framework will trigger this event once it is done initializing the BlackBerry WebWorks framework and APIs. Here is an example of the webworks script file definition and webworksready event in action:

<html>
<head>
<script type=”text/javascript” src=”webworks.js”></script>
<script type=”text/javascript”>

window.addEventListener(“load”,
function() {
document.addEventListener(“webworksready”, start);
}, false);

function start() {…}

While the webworks.js file did not exist and is not required for BlackBerry OS or Tablet OS WebWorks SDKs, you can leave the script inclusion line in your application even on these platforms. If your application is not running on the BlackBerry 10 platform, the webworksready event will fire almost right away, and none of the rest of the BlackBerry 10 framework logic will execute; your app will run in the context of the standard BlackBerry OS and Tablet OS WebWorks frameworks.

Config.xml

For this first Beta of the BlackBerry 10 WebWorks SDK, we have implemented most of the existing elements of the configuration document. There are a few elements that will come in the future along with some new additions required to support some new BlackBerry 10 features. Not to worry if you use new elements or have elements that are not yet supported in BlackBerry 10 WebWorks, as the packagers for all platforms will ignore elements they don’t recognize. Please check the documentation for details on the config document.

APIs

APIs for BlackBerry WebWorks have two components to them: JavaScript that runs in the browser environment, and a “native” component that interfaces with the rest of the platform, allowing for the deep integration that provides the full power of BlackBerry WebWorks. Again: Java for smartphones, Adobe AIR for BlackBerry® PlayBook™ tablets. For BlackBerry 10, of course, native is C/C++. So we have to re-implement all the APIs, and will be delivering them incrementally with Beta refreshes over the summer.

In this initial Beta release, we have been able to provide a core sub-set of the full WebWorks API, which is documented on the BlackBerry HTML 5 site, including Identity, Application and App events, System and system events. On a monthly cadence, we will be releasing new Beta bundles of BlackBerry WebWorks with net new APIs, such as Push, File and File Transfer, Audio/Video Capture, etc.

Apache Cordova

The nature of HTML5 is that it is prevalent on most platforms and devices. Apache Cordova (which is the basis of the well-known PhoneGap) is an industry-leading cross-platform framework very similar to BlackBerry WebWorks. We are striving to bring BlackBerry WebWorks and Cordova closer together, and are actively part of the Cordova open source project providing contributions. To begin down this road, we are aligning some of our BlackBerry 10 WebWorks API signatures with Cordova API signatures. Existing WebWorks applications may require some refactoring to target BlackBerry 10, but Cordova/PhoneGap is supported on BlackBerry OS and Tablet OS, so you can take advantage of these APIs on older operating systems.

For example, event APIs have changed. For BlackBerry smartphones or Tablet OS, if you wanted to listen for battery level changes, you would do something like this:

function onBatteryLevelChange(level) {
alert("Battery Level: " + level);
}
blackberry.system.event.deviceBatteryLevelChange(
onBatteryLevelChange);

For BlackBerry 10 WebWorks SDK, we have introduced an Event API with a signature like your typical add/removeEventListener:

function onBatteryStatus(status) {
alert("Battery Level: " + status.level +
“ isPlugged: “ + status.isPlugged);
}
blackberry.event.addEventListener(“batterystatus”, onBatteryStatus);

The “blackberry.event” feature id would be used in your config.xml file for whitelisting purposes. You will notice that, if you replaced “blackberry.event” with “document” or “window”, you have the Cordova/PhoneGap API signature.

Please check out the BlackBerry WebWorks development site to learn more about how you can be part of the first wave of applications for the BlackBerry 10 OS by leveraging your web technology skills, while continuing to target our over 75 million smartphone subscribers and BlackBerry PlayBook tablet users.

About Ken W

Ken is the Senior Product Manager for the WebWorks group at BlackBerry. He is responsible for WebWorks tooling and is heavily involved in the Open Source projects at github.com/blackberry and the Apache Cordova community. Ken has a particular interest in trying to bring the internal and external BlackBerry development communities closer together.

Join the conversation

Show comments Hide comments
+ -
blog comments powered by Disqus