We recently added support for the HTML5 File system API in our web rendering engine and BlackBerry WebWorks.  With this release, you can now emulate the file system, both sandboxed and unsandboxed.  Ripple will create an area your application can write to, and mimics the file system layout of the device.

A really cool piece of Ripple is the emulation of geolocation.  We recently added the live map view that allows you to select a new location on a map, and inject the location into your app code.  With this release, we received a great community contribution that really takes geolocation emulation to the next level.  Mark Dineen provided a patch that allows you to specify a route to follow by providing a GPX file.  Ripple will read the file and inject location update events into your code based on the route provided! Now you can better emulate end-user navigation and movement.

To better reflect the relationship between Cordova and PhoneGap – and due to the fact their core is the same – they are now both under the same entry in the Platforms window, and are represented by version number.

Quite often an application will wish to know when the virtual keyboard is displayed and closed, so that it can react accordingly.  You can now fire the relevant keyboard events into your application to test out your logic.  In the Events panel when you are emulating the BlackBerry 10 platform, you should now see the blackberry.event.keyboard… events.

HTML5 being inherently cross-platform in nature, there are many applications built using web technologies that are designed to target multiple form factors.  Part of designing a cross-platform application is ensuring that your application appears and lays out in a useful way depending on the capabilities of the target platform.  CSS media queries are a powerful tool in this regard, and Ripple now emulates media queries based on the target platform you have currently chosen to emulate.  Try it out and have some fun with this one.

So, be sure to visit our HTML5 developer site to get all the most recent updates, and particularly the downloads page.  Get Ripple, and the latest WebWorks SDK, and start building!

We have to start with a huge shout-out to the BlackBerry WebWorks dev team for some truly remarkable work preparing for this blockbuster. I have been with RIM® for just over 10 years — been there, done that, thought I had seen it all. But I can honestly say that the energy, passion, and dedication to make BlackBerry 10 truly astonishing is unmatched by anything that has come before.

And the passion is company-wide. Don’t take my word for it — this from one of the devs on the BlackBerry WebWorks team:

But back to what you came here for: the low-down on what this release of BlackBerry WebWorks has to offer. Hope you already have your coffee ready (or perhaps adult beverage of choice).

It would be remiss not to lead with the news that the first portion of PIM integration is now supported! With this release, you can create, find, modify, and delete Contacts in your address book. Just like the native application, you can get information on news related to your contact, as well as what instant messaging and social networks you are connected with them on. It’s everything you need to interact with the user’s social graph. Of course, be sure to add the new permissions to your config.xml so the user can opt in, and ensure you elegantly handle it if the user does not allow you access to their PIM data.

var name = new blackberry.pim.contacts.ContactName(); 

name.familyName = “Wallis”;
name.givenName = “Ken”;

var contact = blackberry.pim.contacts.create({
 	“displayName”: “Ken Wallis”,
 	“name”: name });

contact.save(onSaveSuccess, onSaveError);

Drafted a close second (certainly a case could be made for this being selected number 1) is the first stage of support for the BBM Social Platform. In this release, you can register your application with BBM, interact with the user’s profile, be notified of changes to user or friend’s profiles (that also have your app installed), and allow the user to invite friends to download your application. Again, there is a new permission that you will need to include to allow your app to connect:

blackberry.bbm.platform.self.setStatus("busy",
"Building BlackBerry 10, DND!", 
function (accepted) {
    		if(accepted) {
        			// User allowed the change
    		} else {
// User denied the change
    		}
});

BlackBerry Flow is all about leveraging existing functionality – both system and third-party provided – to accomplish tasks in a consistent way, but without having to jump between applications. You can embed what you need from others inside your own application experience, and cards are what drive this experience. Think of a card as a screen that gets layered on top of your application that provides some common functionality to the user. When the user is finished interacting with the card, it animates off the stack of screens and returns any relevant data back to you. The Invocation Framework (which we introduced in a previous release of BlackBerry WebWorks) orchestrates all of this underneath the covers, so you can launch cards using invoke. With this release of BlackBerry WebWorks, you can leverage system and third-party developed cards inside your BlackBerry WebWorks application. You can also implement a card inside your BlackBerry WebWorks application and provide it for use by others! Check out the Invoked namespace in the API Reference for more details on creating your own card.

As indicated, raw invoke functionality can be used to launch cards. However, cards can be accessed in a number of other ways as well:

• A couple of cards provided by the system are the File picker and Camera cards. File picker allows you to provide the user with UI to select a file from the filesystem, and you will get the path back. The Camera Card allows the user to capture pictures or video, and again you get the path back. We felt that these cards might get a lot of use, and are a little more complex to interact with directly using invoke, so we have wrapped an API around them. Check out the blackberry.invoke.card namespace.
• You can also leverage the File picker and Camera cards using the new support for Media Capture in the browser – just include the capture attribute on an field. If you specify “camera” or “camcorder”, you will get the Camera card; otherwise specifying anything else will invoke the File picker. Note that an input field with capture type “microphone” is currently not supported.

<input type=”file” accept=”image/*” capture=”camera”>

In the last major release, we provided the built-in Context Menu with standard system options. This context menu is displayed when the user long presses on an item in your application. In this release, you now have the ability to customize the menu for different contexts in your application. You can remove items from the list, and even provide your own menu items for a given context (such as Image, link, and so on). In future releases, we are looking at ways to allow you to define your own custom context in your application content.

Context Menu

User experience is a prime focus for BlackBerry 10. The user should feel at home no matter where they are, and be able to customize their device for accessibility reasons as well. For example, the user can set a language, as well as a region used for formatting of dates, and so on. Font size can also be adjusted for preference or for accessibility reasons. Applications should strive to adhere to these preferences as well, so with this release, we have provided APIs and events that will allow you to know what the language, region, font, and font size are as defined in the global settings. You can adjust your applications accordingly to have a seamless experience.

An oft-requested feature is to be able to lock your application in a specific orientation. Good news — you can do it now. Check out our documentation on the config.xml file to find out how.

In order to improve memory overhead and load times, the underlying web rendering engine no longer loads the Adobe® Flash® plug-in be default. If you need to support Flash rendering in your application, you can enable it by adding the following feature element to your config.xml (note that this will be application wide, and will be ignored if found inside an <access> element):

<feature id=”enable-flash”>

If you are building a multi-page application, and even on application initial load, you may notice flickers on page transitions if your pages have any background color other than white. We have introduced the ability to specify in config.xml what your page color is, and we will use this to display between page loads to hide the flicker. Give it a try.

<feature id="blackberry.app">
    <param name="backgroundColor" value="0xffffff" />
</feature>

Be sure to check out the API Reference to get the low down on everything our Web Platform can offer to build not just web applications, but integrated web apps showcasing everything that makes BlackBerry 10 unique and powerful. And if you haven’t already, download the tools and get started — there is no better time!

Hopefully you aren’t getting tired of me yet, and I’m sure you are not tired of the updates to the BlackBerry® WebWorks™ SDK. We’ve just posted a new release, and it squarely falls in the high-value realm. While incremental, it empowers a significant feature of the BlackBerry WebWorks platform: custom API extensions. That’s right, like previous BlackBerry WebWorks platforms, you can now write your own extensions to enable native capabilities not yet exposed by the pre-packaged BlackBerry WebWorks APIs!

First, let’s quickly mention the other major item in this release: Now, when you build your application, you can pass a configuration file to bbwp.exe – the main command line tool for BlackBerry WebWorks – which will pass parameters on to the other downstream command line tools that bbwp.exe leverages. bbwp.exe is your main command line tool to create your applications for BlackBerry WebWorks: it will give you your .BAR file and even sign it for you. However, under the covers, it uses a couple of other command line tools that are part of the BlackBerry tool chain to perform these actions such as creating the .BAR and signing it. These other tools sometimes have parameters that are not exposed by bbwp.exe. With this release, we have provided a parameter (-p or –param) on bbwp.exe to provide a file on the bbwp.exe command line that you can use to pass on to the downstream tools any additional parameters you choose. It is a simple json structure that you can mark up. The main use case we hear quite often is providing the signing tool with proxy settings. Check out the params-example.json file in the root of your BlackBerry® 10 WebWorks SDK installation for an example. It contains the framework for providing parameters to the other two tools, the native packager that creates the .BAR, and the signing tool which signs the .BAR.

OK, now back to custom extensions. As a quick recap, BlackBerry WebWorks APIs are conceptually comprised of two different things: an API or service in the native platform, and a JavaScript® front-end to this native service. All of the APIs that are part of the official BlackBerry WebWorks SDK take advantage of this architecture and a system called jNext. jNext is what binds the JavaScript layer to the native layer. You can now build your own API extensions in exactly the same way we do.

To get started, you will first need to download our BlackBerry 10 Native SDK and configure it. This will give you access to all that the native environment offers. Go do that now and come back here for the next step.

All right, you’re back. Next step is to visit our GitHub Community API repo and download the sample BlackBerry 10 Native SDK project we have provided. This sample project is a working example of an extension that monitors memory usage on the device. Everything you need to create your own extension is modeled here. A full walk-through of the project and its components can be found in the README associated with the project in the GitHub repository, so check that out next, and get working on your extension.

Once you are done, I highly recommend that you check out our Community API repository, and seriously consider contributing your extension to the repository so that others can take advantage of your awesome work. To contribute the extension you will need to apply the ASL 2.0 license, and complete a few other administrative things, but then the whole BlackBerry WebWorks community can benefit.

One thing to bear in mind with your extension: we really didn’t want to hold back on releasing this feature to our community, but we do know that one thing will change in our next BlackBerry WebWorks SDK release. When you completed your extension, you would have had to create/modify a file called manifest.json. This file provided metadata regarding your extension. Moving forward, we will very likely model the format of this file after the CommonJS package.json file format (used by npm modules). This should not constitute very much refactoring, as the current file format is very concise, and the community alignment is valuable in itself.

OK, that’s it for this release. As always the team is working on some exciting stuff for the next release. I can’t wait for the next release! Until then, head over to our download page and our GitHub repo to start working on your custom extensions!

As I am sure you are aware by now, we released a major update of the BlackBerry® 10 WebWorks SDK last week. This brought some awesome features for web developers on the BlackBerry® platform, such as Invoke framework, Push, context menus, and file transfer. Probably one of the biggest was the file API, using the HTML5 File API with support for both a sandboxed (default) and unsandboxed file system.

Thanks to your feedback, we identified an issue where the sandboxing logic was not working as we documented. The default for the file system should be sandboxed, but it was actually unsandboxed. Further, the blackberry.io.sandbox property could not be set, so you could never actually get a sandboxed file system.

We have fixed the issue and pushed up a patch to the BlackBerry® WebWorks™ SDK so that you can continue working with the File system API as you would expect. Please head on over to the download page to get the latest SDK, and keep working on your BlackBerry WebWorks application for BlackBerry 10!

When we released our first Betas of the BlackBerry® 10 WebWorks™ SDK and Ripple Emulator at the BlackBerry 10 Jam conference in May, we spoke about our desire to bring frequent updates of these tools to you, our dedicated developer community. We want to keep fueling your creativity and desire to build the best BlackBerry 10 applications leading up to the official release. So, here is your next BlackBerry WebWorks and Ripple fix.

This update brings a few new APIs (and emulation thereof in Ripple) along with a host of fixes and a slight change to how we handle whitelisting of events.

First up is the addition of the blackberry.ui.dialog APIs that will be very familiar to existing BlackBerry WebWorks developers. This API provides two methods that allow you to launch asynchronous dialogs requesting feedback from the user. These dialogs leverage the standard system level dialogs so you can get a consistent look and feel for your application with the rest of the system. standardAskAsync provides a predefined set of buttons for your dialog, whereas customAskAsync allows you to customize the dialog buttons.

We have also added an API that, in conjunction with the standard HTML5 onLine API, will let you know just how connected you really are. The standard navigator.onLine property and online/offline events are supported to let you know if your application has connectivity in general. If you would like to know what type of connection you have and when the type of connection changes, check out our blackberry.connection.type property, and listen for the connectionchange event. This will tell you if you are on VPN, BlackBerry® Bridge™, WiFi®, etc.

Speaking of events, we have adjusted how these work slightly from the first release. In the initial beta, all events were defined in the blackberry.event namespace. Without getting into gory details, this proved to be somewhat inefficient on the final code size, so we have moved the event definitions into the namespace that contains the functionality related to that event – i.e. the battery events are now defined in the blackberry.system namespace. Note that you no longer need to whitelist blackberry.event, since it only has the add and remove listener functions (these will always be available to call), but you will have to whitelist any namespace that has an event you are specifically interested in. Please check out the API reference.

In terms of bug fixes, there are a couple of key ones that I want to call out. If you use a module loader, you can now also use BlackBerry WebWorks, hooray! In the first release, the last one included into your app would work but break the first. Now webworks.js and module loaders play nicely together.

In the first release, you also could not sign your application at the same time as enabling remote web inspector. You can now do this so you can test your application on secure devices without needing to worry about debug tokens. That said, be sure to turn off web inspector before you submit your application to the BlackBerry App World™ storefront.

The team here at Research In Motion® (RIM®) is hard at work on the next Beta refresh, currently slated to land in early July. If you are really eager/curious/have lots of free time, feel free to check out our progress in GitHub, and let us know whether we are heading in the right direction on new features and APIs.

For BlackBerry WebWorks SDK work, check out:

https://github.com/blackberry/BB10-Webworks-Packager

https://github.com/blackberry-webworks/BB10-Webworks-API

Ripple? Check out:

https://github.com/blackberry/Ripple-UI

Looking forward to a great summer of BlackBerry 10 and BlackBerry WebWorks coding!

Hot on the heels of the release of the BlackBerry® 10 WebWorks™ SDK, we have posted a new Ripple Emulator with support for BlackBerry® 10. All the power of Ripple can now be put to use developing and testing your BlackBerry 10 applications over the summer to get into the BlackBerry App World™ storefront right out of the gates!

Inside Ripple, you can now select the BlackBerry 10 Platform and target the BlackBerry 10 Dev Alpha device for emulation. The tool will configure the API emulation interface to reflect the current available APIs delivered in the BlackBerry 10 WebWorks SDK Beta. And once you install and configure the BlackBerry 10 WebWorks SDK with Ripple, you can build you application, sign it, and even deploy it to the simulator or, if you were a lucky attendee of BlackBerry 10 Jam, to your shiny new BlackBerry 10 Dev Alpha developer device.

With this release, you will find two different versions of the Ripple Emulator on our developer site. The reason for this is that Ripple is moving back to the future. Starting with this release, Ripple is returning to its roots as a Chrome Browser Extension. While we believe this gives us the best path forward, there are still a few things to clean up, coming in new beta refreshes through the summer. Until that time, the current version of Ripple will remain the primary tool for supporting all platforms.

For this first beta release, after you complete the install process, you will need to manually install the extension .crx file into Google Chrome by dragging and dropping it onto the browser. After that you just need to click on the Ripple icon to the right of the URL bar and enable Ripple, and you are good to go.

If you would like to leverage the BlackBerry 10 WebWorks SDK build/sign/deploy functionality within Ripple, you will also need to manually start the Build and Deploy Node.js-based services. Closing the command prompt window will stop the services. For more information on this and the install process, please review our Getting Started guide.

An additional feature that we have added in this release is the addition of dynamic mapping for the emulation of geolocation features. You can now click-drag, and zoom in and out of the map in the geolocation panel and the latitude/longitude information will dynamically update. Give it a try for testing your location based service applications.

No need to fret though – we are hard at work abstracting the manual setup so that this is all seamless as soon as possible. We are aiming to deliver Beta refreshes to both Ripple and the BlackBerry 10 WebWorks SDK on a monthly basis, in order to get the latest and greatest into our community’s hands as frequently as possible.

Check our BlackBerry WebWorks development site frequently through the summer in order to ensure you always have the latest tools to develop the best BlackBerry 10 WebWorks applications.

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.