Welcome to the official BlackBerry Support Community Forums.

This is your resource to discuss support topics with your peers, and learn from each other.

inside custom component

Web and WebWorks Development

Fundamentals Guide: From jQuery to WebWorks

by Retired ‎02-07-2012 04:16 PM - edited ‎02-07-2012 04:22 PM (12,525 Views)

Applies To


  • BlackBerry® Device Software 5.0+
  • BlackBerry® PlayBook™ OS 2.0+
  • BlackBerry® Tablet OS 1.0+



This article is intended to guide BlackBerry® WebWorks™ developers who are considering jQuery™ within their application, or jQuery developers who are considering branching out to one of the available BlackBerry platforms.


This article starts with a brief overview of what jQuery and WebWorks can offer, followed by the steps to configure your PC for WebWorks development along with instructions for launching a basic Hello World jQuery sample.


Following WebWorks configuration, we dive deeper into jQuery: it's advantages and limitations, as well as additional considerations when leveraging JavaScript® frameworks.


What is jQuery?


At the core, jQuery is a JavaScript library that simplifies many complex actions such as DOM manipulation or web service calls via JSON or Ajax. This allows a developer to minimize the amount of code they write, reducing development cycles, and eases the future maintenance/update of their applications as well.


If you haven't yet, now would be a good time to get acquainted with the jQuery website:



One key thing to remember is that since jQuery is built on top of JavaScript, what will or will not work becomes dependent on a platform's support of JavaScript. If you have a desktop browser-based solution already implemented with jQuery, there is a very good chance that newer platforms will simply run your code.


jQuery can be used under the MIT or GPL licenses and is available for use within commercial applications.


Why WebWorks?


When you hear WebWorks, think HTML5. The best starting point for WebWorks development related would the following microsite:



Here you can find samples, guides, as well as a detailed API reference for WebWorks specific functionality.


For developers who already have a jQuery solution hosted on the web, they may be asking, why do I need a WebWorks application, can't I just direct users to my website?


This is a valid question and really depends on the project you're providing.




The difference between existing within an end-user's browser bookmarks, or on the home screen can be a big deal. Even if you're not planning on making any changes to your application, a Launcher Icon can ensure that your application stays visible to the user and minimizes the steps it takes to access your application.


Getting onto devices are now simpler than ever too as you can distribute your application via BlackBerry App World™ to the millions of subscribers who are downloading applications every day. No registration fees, no submission fees.


Finally, the option to make the resources of your application local to the device can not only reduce load times, but allow your content to be accessed without the requirement of a data connection.




jQuery is great at many things, but at the end of the day it is a JavaScript framework and limited to what JavaScript can do. If you're looking for a solution that deeply integrates with the platform it is on, a WebWorks application will give you access to the BlackBerry OS that JavaScript/jQuery simply can not. Some examples include:


Platform Services


There are a number of BlackBerry-specific services that are offered as a part of the WebWorks platform.


  • Advertising - Earn additional revenue with in-app advertising.
  • BlackBerry Messenger - Integration with BBM™ has driven application downloads to new levels.
  • Payment - Leverage the business model that's right for your application.
  • Push - Allows content to be delivered directly to end-users in real-time.

Hardware Integration


WebWorks APIs give you access to GPS and device movement information. Combined with camera and microphone support, truly unique products can be created.


Leverage Native Apps


Direct access to the device's messaging capabilities (email, SMS), phone, and media applications allows you to integrate directly with the functionality that users have come to expect.


Filesystem Access


Server-side storage is a boon in many cases, but the cloud isn't a one-size-fits-all solution. Client-side access to the filesystem gives new opportunities for data storage, retrieval, and presentation.


More information on leveraging these APIs can be found within the WebWorks API reference.


Packaging and Testing a WebWorks Sample With Ripple


First, let's take a look at what our tools can do. If you have an existing jQuery solution already hosted on the internet, I'll show you how to give it a go through Ripple. If you don't already have a project to test, we'll use a local, jQuery-flavoured Hello World sample as a starting point.


System Requirements


Prior to installing the WebWorks tools, please be sure you meet the requirements for Ripple, as well as both the WebWorks SDKs (Smartphone and Tablet OS.)


It is also recommended to have a local web server (i.e. Apache, IIS, etc.) installed on your PC that will host your HTML files for access by Ripple.


Configuring Your Environment


In this example, I have installed a WAMP Server instance on my Windows® XP machine. Ripple, as well as both Smartphone and Tablet OS SDKs, have been installed.


To start, I've configured the main HTML source folder of my WAMP Server (c:\wamp\www) as follows:




_out is the folder I will be using when packaging my application and will hold the compiled resources.


BatBerry is an open-source project designed for BlackBerry Smartphones and a part of the larger BatBerry project.


bbUI.js is a UI toolkit for BlackBerry Smartphones, aimed at providing a native look-and-feel to WebWorks applications.


sandbox is an empty folder that I will use for testing/development.


WebWorksQNXWidgets is a UI toolkit for the Tablet OS, aimed at providing a native look-and-feel to WebWorks applications.


The remaining folders are WebWorks sample projects available from the BlackBerry GitHub page.


index.php is a basic PHP script used to provide an indexed list of all WebWorks projects contained in this folder; for use with Ripple. Full source for this script is attached as index.php.zip.


This folder/file configuration is completely optional and is intended simply as an example.


The Ripple Emulator


Ripple is an emulator that will render content with the same engine you would find in OS 6.0+ Smartphones as well as the Tablet OS. The difference between an emulator and a simulator is that, under the hood, the emulator software is designed to behave like a regular device; but it is not the actual OS software driving that behaviour.


For a quick guide to installing and navigating around within Ripple, please refer to this article. A more in-depth guide on the various features of Ripple can be found here.


Configuring Ripple


Clicking the  icon in the top-right corner of Ripple allows us to display the Settings... dialog where we can uniquely configure our currently active platform: WebWorks (Smartphones) or WebWorks-TabletOS (PlayBook.)


A detailed guide on the various settings, including SDK Paths, can be found here. In our case, we will configure our project-specific settings as follows.


Item Value
Project Root c:\wamp\www\sandbox
Archive Name sandbox
Output Folder C:\wamp\www\_out


Once complete, click the icon in the top-right corner to save your settings and close this dialog.


Configuring Signature Keys


Detailed information on configuring and backing up signing keys, can be found in this article


For the WebWorks SDK for Smartphones, once your keys are registered and backed-up, you can copy the sigtool.db and sigtool.csk files to the bin sub-folder of your SDK Path to associate Ripple with your signing privileges. Example:


C:\Program Files\Research In Motion\BlackBerry WebWorks SDK\bin

For the WebWorks SDK for Tablet OS, you can copy the author.p12, barsigner.db, and barsigner.csk files to the default folder as outlined here. Example:


C:\Documents and Settings\eoros\Local Settings\Application Data\Research In Motion


Let's Test a Sample!


First, switch to your desired Platform (WebWorks or WebWorks-TabletOS) and Device.


If you have already deployed a publicly available jQuery solution, type the URL into the address bar and give it a go. This will give you an initial idea for how your application will look and behave within your selected platform.


If you don't already have a jQuery solution hosted, feel free to try an official jQuery sample page.


Note: On devices where all of the content is not displayed onscreen, you can scroll vertically using the mouse wheel and scroll horizontally by holding alt and using the mouse wheel.


Also, while Ripple will render it as a real device would, simply browsing to a page will not allow you to package a website into a WebWorks application. To test a proper WebWorks sample from your local machine, we'll need to perform additional steps.


First, we will need to create a config.xml file. You can think of this file as a description of your application. Depending on your target platform and the APIs being leveraged, there may be some differences between what does or does not go into your config.xml file. A detailed sample for each platform can be found in this article. A very basic config.xml might look like this:


<?xml version="1.0" encoding="UTF-8"?>
<widget xmlns="http://www.w3.org/ns/widgets" version="" >
	<author>Erik Oros</author>
	<content src="index.html"/>
	<access subdomains="true" uri="*"/>


In the above sample, we've defined an application name, author, and the initial content page to load when our WebWorks application is started. We've also indicated that we want our application to be able to access all public URLs (including sub-domains) in case we're pulling in external resources. This value can be fine-tuned to specific domains.


In this case I've selected a local file (index.html) for our initial content but could also reference an external website as outlined in the creating your first WebWorks application guide. The external approach would be ideal for those developers that already have a complete solution hosted and simply want to distribute a launcher to that website within a WebWorks package.


Once we have our config.xml file, we'll want to save it to our Project Root folder as defined in Ripple's settings.


The next step is to create index.html; our default page when the application is launched. The following is a sample jQuery page based on the code available here:


<!DOCTYPE html>
		<script type="text/javascript"

		<script type="text/javascript">
			$(document).ready(function() {
				$("a").click(function() {
					alert("Hello World!");

		<a href="">Go jQuery Go!</a>


And there you have it. For already completed jQuery solutions, our sample config.xml file should likely suffice. If your application does request resources from external URLs, domain white-listing will be required, but no additional features should have to be specified until you start looking at BlackBerry-specific APIs.


For larger applications, you'll want to place all of your resources into the sandbox folder (keeping the required sub-folder structure). This might look something like:



Once you've tested your project within Ripple and are ready for a live device, the instructions in this article can be used to package and sign your application for deployment.


Considerations When Using jQuery


Now that we've covered the basics of putting together a WebWorks application, let's dig a little deeper into jQuery itself and some considerations for its use.


Browsers: Desktop, BlackBerry (5.0), and WebKit (6.0+)


jQuery is a JavaScript framework and thus is subject to the features that the underlying browser specifically supports. If you've already written a web solution for PCs that leverages jQuery, you've likely gone through a variety of testing scenarios on some of the more popular browser (i.e. Windows® Internet Explorer®, Mozilla® Firefox®, Google Chrome™, Opera®, Safari, etc.)


jQuery itself supports the majority of the more popular browsers and a reference guide for this can be found here:



Chrome and Safari are both WebKit-based Browsers, as is the BlackBerry Browser since BlackBerry OS 6. This shared baseline provides a lot of commonality in support for HTML5/JavaScript functionality, however not all features that work on one will automatically work on the other.


BlackBerry Software


For its part, the WebKit implementation of the BlackBerry Browser does inherently have a high level of JavaScript support and the majority of jQuery APIs will simply work. For a full break-down of supported HTML, JavaScript, and CSS features by BlackBerry Browser, please visit the Browser Documentation page here.


One of the issues with any JavaScript framework is that the underlying implementations are obscured from immediate sight; so if something isn't supported it is more difficult to immediately identify. This tends to be more prevalent on the BlackBerry OS 5 Browser, where JavaScript support is less comprhensive than its successors. The key reason being that prior to BlackBerry OS 6 the BlackBerry Browser was a proprietary implemenation, as opposed to being based on the WebKit engine.


BlackBerry Hardware


Nowadays, most Desktop PCs have multiple cores, at least 2.0Ghz of processing power, and enough RAM to accomodate the most inefficient of developers. Smartphones have come a long way but will fall short of many PC benchmarks. The hardware-gaps between BlackBerry OS 5, 6, and 7 Smartphones alone can lead to visible performance differences.


If you're porting an existing jQuery solution from the Desktop-space, even if all features are supported, you may still need to take a closer look at optimization for a platform with less resources available. jQuery itself is not designed to be a light-weight framework (not to the same extent as some other frameworks such as jQuery Mobile, jq.Mobi, zepto.js, or others) and thus will come with a slight overhead in performance; even in its minified form. On the latest BlackBerry Smartphones, this has become much less of an issue.


Which OS Versions Should I Support Then?


This is a question that will come down to the developer and project they are working on. One of the primary considerations is who is your target?


If you have a specific customer in mind, it would be best to take an inventory of the devices they use and the lowest platform you need to support. The newer your minimium platform can be, the more features you can include, and the faster the hardware will be. For more generic applications, your decision may be based on how prevalent specific platforms are in the market and which platforms you are comfortable going after.


With respect to BlackBerry platforms, BlackBerry OS 5 is still a very real target for consideration, consisting of 47% of the subscriber-base as of November 30, 2011.


Some developers prefer to implement only the most basic functionality of jQuery, or implement a pure JavaScript version of their application for BlackBerry OS 5 specifically. The fact of the operating system and hardware remains that if your jQuery solution does make use of functionality beyond the most basic features, simplification of code may be a requirement. Generally, there will be ways to implement your own pure JavaScript to recreate the more common jQuery functionality.


The important point to keep in mind when considering jQuery and BlackBerry OS 5 is that the requirements of jQuery and the capabilities of the platform do create a technical gap. If BlackBerry OS 5 is going to be a target platform of yours, it is best to make it a part of your development cycles right from the start and not an after-thought (i.e. after you've developed your application based on the newest available BlackBerry Smartphones.) This is not only a consideration with jQuery, but with many JavaScript frameworks that leverage newer HTML5 functionalty.


UI Considerations


Another topic that is common among jQuery developers is the user-interface that is available to them out-of-the-box. WebWorks leverages all aspects of HTML5, including JavaScript and CSS, giving developers the opportunity to get as creative (or minimal) with their application design as they want.


However, there are times when a developer will simply want to focus on development, and not spend too much time laying out, skinning, and tweaking various UI components.


To help developers on this front, jQuery does have its own UI Library available to simplify this process. This library provides easy to use, powerful components to developers. However this flexbility does come with the same strings as the jQuery framework in general. Specifically, some additional performance overhead coupled with shrinking support on older platforms.


Getting That Native Feeling


Developers can use any number of UI libraries and extensions to meet their needs for performance and style. A common concern though is that many of these libraries lack that native BlackBerry look-and-feel. There are primarily two open-source projects underway to address this.


On the BlackBerry Smartphone side, the bbUI.js project is aimed at bringing the BlackBerry Java® design to WebWorks applications. At present, the focus is aimed at BlackBerry OS 6 and 7, but a back-port to BlackBerry OS 5 is planned. For more information and to access resources, please visit the bbUI.js GitHub page here:



For the BlackBerry Playbook, a similar community-driven project is underway to bring the PlayBook's native look-and-feel to WebWorks applications. This project is open for use by anyone and is worth checking out if you are looking for a CSS framework for the Tablet OS:



There other projects that aim to bring this native design to a wider range of platforms but at the time of writing the these two have seen the most progress on the BlackBerry platform.


Debugging and Investigation


Inevitably, developers are bound to run into issues. With any luck, it's a missing semi-colon that hasn't caused you too much heartache yet; othertimes you may not be so lucky. Eventually, you may come to the conclusion that something is simply broken. Let's take a look at how we come to that conclusion.


JavaScript Validation


Before you even run your code, you should have a fairly high level of confidence that it will in fact run; JSLint is a great tool for this. Depending on your HTML/text editor, there will often be a JSLint plug-in that you can leverage as well. Running JSLint validation will pick out the most common errors for you (syntax, formatting, etc.) Everyone misses a semi-colon from time to time.


Web Inspector


if you have developed a web solution for desktops, chances are you've come across some form of Web Inspector tool to let you examine what is happening. As of BlackBerry OS 7 (and the Tablet OS), this same functionality is available for WebWorks applications. For a detailed guide, please see this article.


This same functionality is also available within Ripple, by right-clicking on the background-space and launching the Inspect tool.


Community Support


With a liberal use of if statements and try/catch blocks, the above should help narrow down a large percentage of problems. From time to time, most developers will find themselves at a point where no matter their efforts they can not narrow down an issue. The BlackBerry Support Community, as well as the jQuery Forums are both two great resources to leverage.


Reporting Bugs


If you do find something that is likely a bug, these can be reported at the following sites (depending on the category they fall under):


If you do have any feedback regarding your experiences with WebWorks and jQuery, I would also highly recommend visiting the following Web and WebWorks Development forum post to share your insight, or see what other developers are saying.




The following is a compilation of select articles, grouped by category for easier traversal.




Code Signing


GitHub Repositories

Other Resources

Users Online
Currently online: 40 members 3,228 guests
Please welcome our newest community members: