- 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.
What is jQuery?
If you haven't yet, now would be a good time to get acquainted with the jQuery website:
jQuery can be used under the MIT or GPL licenses and is available for use within commercial applications.
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.
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.
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.
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.
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.
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.
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.
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 184.108.40.206\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="220.127.116.11" > <name>Sandbox</name> <author>Erik Oros</author> <content src="index.html"/> <access subdomains="true" uri="*"/> </widget>
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:
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 itself supports the majority of the more popular browsers and a reference guide for this can be found here:
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.
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.
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.
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.
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.
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.
- Accessing a project from the file system in Ripple
- How to use Ripple instead of the BlackBerry WebWorks Plug-ins for Eclipse and Visual Studio
- tneil/BatBerry - bbUI.js sample implementation.
- tneil/bbUI.js - UI framework for BlackBerry Smartphones.
- TheMarco/WebWorksQNXWidgets - UI framework for Tablet OS.
- blackberry/WebWorks-Samples - Sample WebWorks applications.