Dojo Toolkit


The Dojo Toolkit is a JavaScript toolkit for creating cross-platform JavaScript/AJAX applications. It contains a rich collection of lightweight and independent modules. The toolkit enables you to use its lightweight solution for DOM manipulation and AJAX services by allowing you to choose only the modules you need for your application. It also allows you to create complex JavaScript classes with multiple inheritance.

Support for Dojo on the BlackBerry Application Platform

BlackBerry smartphones running BlackBerry Device Software version 6 and later and also BlackBerry PlayBook tablets support applications that are built using the Dojo Mobile module. The support is dependent on the WebKit-based BlackBerry Browser. The BlackBerry Browser has been WebKit-enabled since BlackBerry 6.

The Dojo Mobile module in Dojo 1.8 provides significant performance improvements on BlackBerry devices compared to Dojo 1.7. If you are using the Dojo Mobile module from Dojo 1.7, you can port your app to Dojo 1.8 using the Migration Assist module included with Dojo 1.8. The Migration Assist module detects and informs you of deprecated functions through the browser console and even fixes some issues.

Benefits of using the Dojo Mobile module

Dojo Mobile is a lightweight module that contains widgets (also known as components) for developing mobile apps. The widgets contain HTML, CSS, and JavaScript code, and you can use them to make your applications robust and user friendly. It contains an automatic theme loader and also comes with a predefined theme for the BlackBerry OS. This enables you to automatically apply a look and feel to your apps that is native to the BlackBerry OS, in addition to your own styles. The widgets in the Dojo Mobile module enable you to display grids, charts, forms, and data that are optimized for viewing and interaction on a mobile device. Some of the widgets available in the Dojo Mobile module include:
  • Date/time picker
  • Accordion views
  • Pop up menu with icons
  • TabBar views
  • Image/content carousel
  • Transition effects

Using modules from other packages

DojoX package

You are not limited to using only the widgets in the Dojo Mobile module of the DojoX package. There are many widgets in other modules of the DojoX package that you can use (for example, widgets for dynamic charts, enhanced grid displays, cross-platform graphics, mapping using OpenLayers, and so on).

Dijit package

You can also add functionality from the Dijit package. The Dijit package includes an extensive library of UI controls and other useful widgets that are not available in the Dojo Mobile module, such as a color palette or a calendar. While the widgets in Dojo Mobile are specifically tailored for mobile devices, you might still want to explore the widgets available in Dijit. As of version 1.8, most widgets in Dijit support mobile device events such as touch and gesture events.

There are plenty of GUI widgets in the DojoX package and there are other packages, such as dgrid ( ), which offer a high-performance grid that works on mobile and desktop browsers.

Using Dojo in BlackBerry WebWorks apps

Using the AMD module loader

Asynchronous Module Definition (AMD) is an API for defining reusable modules that you can load asynchronously in your application. Using asynchronous loading of AMD modules in your application reduces application load time by up to ten times when compared to synchronous loading of modules, making it suitable for mobile applications.

To use asynchronous loading of AMD modules, set the "async" property of the Dojo Toolkit to true. It switches Dojo into baseless Dojo (async mode or AMD mode). With baseless Dojo, your application loads the module loader first, so that you can pick only the modules that you need in your application. This keeps your BlackBerry WebWorks application lightweight. Include the following code in your BlackBerry WebWorks application's index.html file to use the AMD module loader:

<script data-dojo-config="async:true" 

While you can include the Dojo loader using a protocol-less URL in desktop applications, in a BlackBerry WebWorks application, you must include the “http” or “https” protocol identifier to properly locate the external resource. If you do not specify a protocol, the location that is local to your BlackBerry WebWorks application becomes the location of the resource by default.

Due to the large number of modules that the Dojo Toolkit provides and the dependencies of some of the modules, it is suggested that you call the Dojo loader from an online resource. This also means that your application will require an active Internet connection.

With the AMD module format, module identifiers look like paths (for example: dojox/mobile). Without AMD, the syntax looks like object references (for example:

Using the mobile parser

It is suggested that you explicitly include dojox/mobile/parser and call parser.parse() in your application. The mobile parser is significantly more lightweight compared to the base parser, which results in a faster loading time. The mobile parser parses your application's pages once the DOM and initial dependencies have been loaded, and it converts all widgets that you created declaratively to enable them to work with the Dojo Toolkit.

Automatically applying the BlackBerry theme

The Dojo Mobile module can detect a BlackBerry device and automatically apply a BlackBerry OS theme to your application. This functionality is called automatic device detection and theme loading. To apply the BlackBerry theme in your application automatically, include the following resource: dojox/mobile/deviceTheme. You can save development time and effort needed to create a separate style sheet by using automatic device detection and theme loading.

Resources to help you get started

Code sample

The following code shows how to structure the modules and the AMD syntax:

"dojox/mobile/parser", /* This mobile app uses 
                       declarative programming with 
                       fast mobile parser. (Optional) */

"dojox/mobile", /* This is a mobile app. (Required) */

"dojox/mobile/deviceTheme" /* Detects the device’s OS and  
                           formats styles accordingly. 
                           [we can use this to automatically 
                           detect the BlackBerry device] 
                           (Optional) */

function(parser, mobile, compat)
    parser.parse(); /* Parse the page for widgets 
                    and instantiate them. */

Sample application

Visit the WebWorks-Samples repository on GitHub and check out the DojoAppDetails sample. It's a sample application that displays the application's details by retrieving the details from the application's configuration file (config.xml).

Packaging, testing, and debugging

Once your sample application is ready, you can package, test, and debug using the Ripple emulator tool or the BlackBerry WebWorks SDK. You can run your application on a BlackBerry simulator or a device.

Last modified: 2013-10-02