Applies to:
- BlackBerry Device Software 5.0
Summary:
BlackBerry Device Software 5.0 supported Gears™ API and some HTML5 functionality . BlackBerry 6 supported more HTML5 APIs but deprecated Gears API functionality. This article demonstrates how Web and WebWorks developers can support BlackBerry 6 HTML5 features on OS 5.0 Smartphones through the use of including an HTML5 to-gears JavaScript toolkit in their Web content.
The BlackBerry WebWorks SDK for Smartphones version 2.1.1 automatically builds the HTML5 to-gears JavaScript toolkit into every WebWorks application it creates, so developers do not need to explicitly include this toolkit in each of their pages.
Background:
The BlackBerry® Web platform in BlackBerry® 6 was updated to be the WebKit rendering engine. This greatly enhanced the level of rendering fidelity due to enhanced support for web standards and performance enhancements. The improved browser provided support for the HTML5 standard and officially dropped support of Gears much like the rest of the industry. BlackBerry Web and WebWorks developers who have leveraged the Gears APIs in their applications will need to update their code to support this change.
How it works?
To assist in making this transition as easy as possible, a JavaScript toolkit is provided as an attachement to this article. This toolkit will allow you to consistently use HTML5 in your BlackBerry Web and WebWorks applications and not have to worry about managing two different versions of your source code (one Gears one HTML5). What his means is that you can choose to create your BlackBerry WebWorks application using HTML5 syntax and it will be compatible with both BlackBerry® Device Software 5.0 and BlackBerry 6. When running BlackBerry Device Software 5.0, which has support for Gears but limited support for HTML5, the JavaScript toolkit will map the HTML5 API calls to underlying Gears APIs. When running on BlackBerry 6, pure HTML5 will be used. The overall result is reduced code fragmentation in your BlackBerry WebWorks applications.
The JavaScript® toolkit provides the following HTML5 interfaces as a simple layer on top of the Gears API’s currently available in BlackBerry Device Software 5.0:
- Geolocation
- Timer
- Database
- Worker
- XMLHttpRequest
We realize that you obviously don’t want to have to do all of the leg work to detect what’s available, so inside the toolkit, we’ve built in the logic to determine if it’s needed or not. If the BlackBerry Browser is the BlackBerry Device Software 5.0 version, the toolkit will be used, and if the BlackBerry device user is using the more powerful WebKit engine included in BlackBerry 6, the toolkit will simply not be leveraged.
This toolkit will save a lot of time and code management since you’ll be able to run your BlackBerry WebWorks application on either BlackBerry Device Software version with no worry about compatibility.
Getting Started
Here are the steps on how to install and leverage the toolkit:
- Save the .zip file attached to this article named "HTML5-to-Gears.zip"
- Extract the contents of this file to the root folder or to a subfolder of your BlackBerry WebWorks or web application.
- Ensure that the html5_init.js and html5_worker.js files are in the root folder or in a subfolder of your BlackBerry WebWorks or web application.
- In your source code, reference the html5_init.js extension file by including it in a script tag.For example: <script type="text/javascript" src="<path to file>/html5_init.js" id="html5_init"></script>
- Update your BlackBerry WebWorks application, replacing any calls to Gears APIs with their corresponding HTML5 functionality.
- If you are using workers, also reference the html5_worker.js file in a script tag. You do not need the id tag for this file. For example: <script type="text/javascript" src="<path to file>/html5_worker.js"></script>
- For a BlackBerry WebWorks application, package the application in a .zip file and compile it.
- Test your BlackBerry WebWorks application functionality on both BlackBerry Device Software 5.0 and BlackBerry 6.
For more details please read the BlackBerry WebWorks SDK Release Notes.
BlackBerry 6 Simulator
Use a BlackBerry® Smartphone Simulator running BlackBerry 6 to accurately test and verify how well the changes provided in this article improve your BlackBerry WebWorks applications. You can download a BlackBerry 6 Smartphone Simulator from the BlackBerry 6 home page.
