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

Working with the Dojo Toolkit

by Retired on ‎09-13-2012 04:10 PM (4,483 Views)

What is Dojo?


Dojo™ is a JavaScript® toolkit used to create cross-platform, JavaScript/AJAX applications. It provides a lightweight solution for DOM manipulation and AJAX services by allowing you to pick and choose only the modules needed for your application. Dojo is created with minimal dependencies while offering thousands of lightweight plugins. Dojo also provides a way to create complex JavaScript classes with multiple inheritance.


You can use Dojo under the AFL or BSD license for use in commercial applications.


The new Dojo 1.8 release supports both BlackBerry® OS 6 and 7. Since BB10 uses an improved webkit browser, Dojo 1.8 components should run even better on BB10.


The Dojo 1.8 release introduces new components and provides performance updates from the previous release for many Dojo features.


For mobile developers using previous versions of Dojo Mobile, Dojo 1.8 introduces the Mobile Migration Assist module to help migrate your app to Dojo 1.8 by detecting and informing the developer of deprecated functions through the browser console and even fixing them where possible.


BlackBerry mobile development with Dojo


Developing for a BlackBerry device is easy with Dojo as it has a set of widgets optimized for a better mobile experience. This functionality is provided by the Dojo Mobile extension. It is lightweight and minimized to provide only what you need for your mobile application. It offers widgets comprised of HTML, CSS, and JavaScript capabilities which allow your mobile web application to be even more robust and user friendly. Core widgets (also known as components) are even offered with a BlackBerry OS theme so you can have that native look to your apps in addition to your own styles.  Widgets also allow you to display grids, charts, forms and data optimized for viewing and interaction on a mobile device.


The following is a small sampling of the widgets offered in the mobile module:

  • Date/Time Picker
  • Accordion Views
  • Pop up Menu with Icons
  • TabBar views
  • Image/content carousel
  • Transition effects

Other widgets available in other Dojo modules:

  • Dynamic charts
  • Enhanced grid displays
  • Cross Platform graphics
  • Mapping using OpenLayers
  • Many, many, more


Using Dojo in your WebWorks application


The previous release (Dojo 1.7) introduced full support for the Asynchronous Module Definition (AMD) API. AMD allows modules to be loaded asynchronously which greatly reduces page load time by up to 10 times when compared to the legacy synchronous loading mode. This is especially useful for mobile applications.


To find out how AMD works, check out AMD: the Definitive Source.


Setting Dojo’s “async” property to “true” switches Dojo into “baseless” (“async mode” or “AMD mode”), which is the mode that allows you to load only what you need. When enabled, only the module loader is loaded allowing you to pick and choose the modules needed for your application thus keeping your BlackBerry application lightweight.


To create a Dojo app for BlackBerry® WebWorks™, include the lightweight AMD loader in your webpage:


<script data-dojo-config="async:true" src="http://ajax.googleapis.com/ajax/libs/dojo/1.8.0/dojo/dojo.js"></script>


While the Dojo loader can be included using a Protocol-less URL in desktop applications, in a WebWorks app, the “http” or “https” protocol must be included in order to properly locate the external resource. When no protocol is specified, the default location will be local to the WebWorks app.


Note: Due to the vast amount of modules the Dojo Toolkit provides and the dependencies required by some modules, it is suggested to call the Dojo loader from an online resource. This will require the app to have internet connection. To reduce the number of modules loaded,  Dojo provides a way to create customized builds.


With AMD, module identifiers look like paths, for example: dojox/mobile. Prior to AMD, the syntax looked like object references, for example: dojox.mobile.


When creating mobile applications, Dojo recommends developers should explicitly include dojox/mobile/parser and call parser.parse(). The mobile parser is much more lightweight with much less code than the base parser and therefore reduces your app’s loading time. With Dojo, you can create widgets declaratively or programmatically. The parser converts all your mobile widgets that are created declaratively and allows them to work with the Dojo framework.


When included, the page gets parsed with the dojox/mobile/parser module when the DOM and initial dependencies have been loaded.


Automatic device detection


To use Dojo mobile’s ability to automatically detect your BlackBerry device and apply a BlackBerry OS theme, the resource to include is:




Automatic BlackBerry device detection means you can get your app coded and ready much faster without having to worry about creating a separate style sheet.




If the element you are looking for is not in the dojox/mobile module, you may find it within the Dijit utilities. Dijit offers an extensive library of UI controls and other useful control widgets such as a color palette or a calendar. While the dojox/mobile components are specifically tailored for better performance and responsiveness on mobile devices, you may want to explore the other widgets available in Dijit and use them in your BlackBerry WebWorks application. As of 1.8, most Dijits support mobile device events such as touch and gesture events. There are still more user interface widgets in the larger DojoX package, and there are additional packages like dgrid, which offers an amazing, high-performance grid that works well on mobile and desktop.


Getting Started


Here is an example that shows how modules and the AMD syntax are structured for the Dojo Toolkit. The following is a modified example from Dojo’s mobile guide:



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

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

  “dojox/mobile/deviceTheme” // (Optional) detects the device’s OS and formats styles accordingly

  )], function(parser, mobile, compat){

    parser.parse(); // Parse the page for widgets and instantiate them




Creating a Dojo and WebWorks App


To create your first Dojo app, head over to the WebWorks Sample Apps repository on github and check out the DojoAppDetails sample application. This sample app will show your app details using the information in the configuration (config.xml) file.


Once your Dojo WebWorks app is ready you can test it on the Chrome™ browser using the Ripple™ extension. To get your app on a BlackBerry simulator or device, check out these links to package, test and debug your application.


BlackBerry Devices


Dojo 1.8 currently supports BlackBerry devices with OS 6 and 7. With the brand new QNX® operating system on BlackBerry 10, and already existing on the BlackBerry® PlayBook™ OS 2.0, Dojo’s features will work with ease on these platforms.


Dojo Resources


Dojo Toolkit

Modern Dojo Syntax

Getting Started with dojox/mobile

DOM and event handling

Dynamic content loading

Users Online
Currently online: 18 members 2,254 guests
Please welcome our newest community members: