Overview of PhoneGap BlackBerry WebWork - original revision by filmaj

blackberry-webworks.md

BlackBerry WebWorks & PhoneGap

WebWorks is a BlackBerry SDK that leverages Web technologies to create applications for BlackBerry 5.0, 6.0, and QNX. An application that is built with WebWorks uses HTML, CSS, and JavaScript and is called a Web widget. The structure of the application is similar to a thick-client JavaScript Web application, where JavaScript manages the model, view, and logic.

WebWorks enhances the JavaScript API to allow any Web widget application to access any Blackberry Java API. RIM includes a small WebWorks JavaScript API that allows access to some BlackBerry device features, such as invoking third-party applications. However, more importantly, WebWorks allows developers to create an Java extension that binds JavaScript and Java. This means any Java API can be accessible to JavaScript.

The WebWorks SDK uses a command-line tool called bbwp.exe (Windows-only) to create a BlackBerry-compatible application binary (.cod). Since a WebWorks application is partially based on the W3C Web Widget spec, the packaging tool uses a config.xml define your application's name, author, version, and permissions. For developers that do not want to use the command-line, there are WebWorks plugins for the Eclipse and Visual Studio IDE.

PhoneGap takes WebWorks two steps further. First, the full PhoneGap JavaScript API is available on top of RIM's WebWorks JavaScript API. Second, an ANT build script is provided to quickly generate, build, and deploy the application. While extending WebWorks, PhoneGap continues to allows developers to create standard WebWorks Java extensions.

Installation and Setup

There are two options:

• GitHub README
• PhoneGap Wiki - Getting Started with BlackBerry WebWorks

Known Issues

• WebWorks Packager:

  • Filenames cannot contain dashes (-) or begin with a dot (.). This can be frustrating for .git directories.
    • Other non-alphanumeric characters are probably not allowed either.
    • Keep it to letters, numbers and underscores for now.
  • As of 01/10/2011, please use the latest WebWorks SDK version and command-line bbwp utility.
    • Previous versions had major problems with stability.

• Debugging Applications:

  • There is no simple way to debug your own custom Java-to-JavaScript extensions.
  • Adam Stanley has provided the following instructions on how to do this:

  Currently, the best way to debug JavaScript extensions is to build the WebWorks application using the /s command line argument. This will dump out the full source code of the compiled app as well as the COD files. Then take this source code and open it in a new Java project in Eclipse (BlackBerry Java Plug-in for Eclipse). It is the source code for a fully functional (Java) application at this point which can be debugged using Eclipse. It's not the most efficient way to do debugging, but certainly the most complete.

• Web Browsers:

  • Fragmentation:
    • OS 5.0 uses BlackBerry 5 browser engine
    • OS 6.0 uses WebKit browser engine
    • QNX uses WebKit browser engine

• Memory:

  • BlackBerry 5 browser suffers from low memory resources
    • Deep callback stacks will crash the application (or reboot the BlackBerry)
    • SQL database queries can crash the application (or reboot the BlackBerry)
  • It is difficult to manage memory within JavaScript
    • Wrapping a function in setTimeout(fn, 10); will reset the call stack and allocate a new memory stack.
    • We have found that a setTimeout under 10 milliseconds can cause erratic behaviour
    • Be careful where you use setTimeout, because it will cause the function to execute asynchronously, which can introduce race conditions.

• Gears Support:

  • In order to modernize the BlackBerry 5 browser, RIM has implemented the Google Gears API
    • This adds Geolocation, SQL database storage, among other APIs
  • RIM has deprecated the API, although it still appears to work.