Featured White Papers

• Measuring Risk to Improve Java Software Quality
• Do You Really Get Classloaders?
• Pragmatic Continuous Delivery with Jenkins, Nexus, and LiveRebel
• Your Next Java Web App: Less XML, No Long Restarts, Fewer Hassles
• Coding with JRebel, Java Forever Changed
• 2012 Developer Productivity Report: Java Tools, Tech, Devs, and Data

Sponsored Links

• Graph databases are 1000x faster than relational.

  Learn More!

• Career opportunities at Harman- Careers That'll Rock Your Socks Off.

  Learn More!

• Developer-friendly Java PDF libraries by Qoppa Software

  Live Demos

• Stop blaming your app! Diagnose Java performance issues.

  Free tool >

• UrbanCode: Go From Continuous Integration to
  Continuous Delivery

  Learn More!

Sponsored Links

Optimize with a SATA RAID Storage Solution
Range of capacities as low as $1250 per TB. Ideal if you currently rely on servers/disks/JBODs

Introduction to the Dojo toolkit, Part 1: Setup, core, and widgets

Object-oriented JavaScript programming for Java developers

By Sunil Patil, JavaWorld.com, 01/20/09

Page 4 of 6

Configuring the Dojo runtime

Dojo allows you to configure the runtime using the djConfig object. The default values of djConfig options are okay for most cases, but you might want to change them to enable debugging, for example, or to inform Dojo that you want to use the Dijit widget library. (It can check if any of the form controls has a dojoType attribute and if it does it will convert the control to a Dijit widget.) I'll explain ways to configure the djConfig object and discuss what each of the various configuration options means.

Configuring djConfig

Dojo creates the djConfig object when the framework initializes -- that is, when Dojo.js loads. If you want to make any changes in djConfig, you should do so before dojo.js is loaded. Any changes that you make in djConfig are ignored after dojo.js is loaded.

You can configure the djConfig object in one of three ways:

1. The easiest and most commonly used approach is to add the djConfig attribute to the <script> element that refers to dojo.js:
   
   

   <script type="text/JavaScript" src="js/dojo/dojo.js"
               djConfig="parseOnLoad: true, isDebug: true" /script>
   

   
   The djConfig attribute's value is a comma-separated list of name/value pairs. The name is the name of the attribute; the value is the value that you want to set.
2. If you need to set lots of attributes in the djConfig object or prefer not to use Dojo's nonstandard attributes, you can create the djConfig object explicitly before the main dojo.js library included in the document:
   
   

   <script type="text/JavaScript">
      var djConfig = {
               parseOnLoad: true,
               isDebug: true,
               locale: 'en-us',
               extraLocale: ['jp-jp']
           };
   </script>
   <script type="text/JavaScript"  src="js/dojo/dojo.js" />
   

   
   This example creates a djConfig hashmap before dojo.js gets included in the page.
3. You can include djConfig in the Dojo Toolbox builder. When creating a custom build you include the djConfig object into the build via the scopeDjConfig parameter. See the online Dojo documentation on "The package system and custom builds" for further information on custom builds.

While developing your Web application, you might want to create a separate include file that contains logic to create djConfig using one of these methods and has a dojo.js script tag. You'd then include that file in every page. The benefit is that you can change the Dojo configuration for the entire application -- for example, to enable debugging -- by changing the one include file.

Configuration options

The djConfig object provides quite a few configuration options. So far our sample code has used two of them: isDebug and parseOnLoad. Let's take a closer look at all of the djConfig options:

• isDebug: This flag turns debugging on or off. Its default value is false. When you turn this flag on, Firefox generates extended debugging information in Firebug. If you're using some other browser, it includes the Firebug Lite script files in the page and starts displaying the Firebug Lite console.
• debugAtAllCosts: When you use dojo.require() to declare dependency, it makes an asynchronous call to load the necessary resources and also makes sure that the resource is not loaded twice. This is approach is efficient but has a downside: when there is an error in the loaded resource -- for example, in one of the classes -- Firebug shows an incorrect line number for the error. When you turn the debugAtAllCosts flag to true, it includes a <script> tag in the page markup for each resource instead of loading them asynchronously. Once the resources are loaded using the <script> tag, Firebug shows the .js file name where the error occurred along with the line number for that error, which makes debugging your code easier. Don't use this option in a production environment, because it adds a lot of overhead
• debugContainerId: When this option is set, Dojo searches the document's DOM for an element with the specified ID and puts the Firebug Lite console inside that element.
• locale: Dojo simplifies internationalization by providing an infrastructure for loading localized resources in the page. By default it uses the locale of the user agent, but you can override that by setting the locale option.
• extraLocale: This option, which has no default value, specifies additional locales whose resources should also be loaded alongside the default locale when calls to dojo.requireLocalization() are processed.
• baseUrl: Dojo downloads required .js files on demand. By default it downloads the dependencies from the same location that dojo.js was downloaded from. If you want to change this for some reason, set the baseUrl property to the location from which the dependency .js files should be downloaded.
• modulePaths: You can extend the Dojo framework by creating your own classes and putting them under a custom directory structure. When you do that, you must map the namespace name to directory name so that dojo.require() can find it. Setting the modulePaths option allows you to map the namespace to the directory name. (I'll talk more about this later in this article.).
• afterOnLoad: This option indicates that Dojo was added to the page after the page load. In this case Dojo doesn't wait for the page DOMContentLoad/load events and fires its dojo.addOnLoad callbacks after making sure all outstanding dojo.required modules have loaded.
• parseOnLoad: Dojo has an HTML parser that parses the document's DOM structure to find the nodes with dojoType attribute and convert them into Dojo widgets. When you set the parseOnLoad flag's value to true, Dojo parses the DOM document on loading and converts the nodes to Dijit widgets.
• addOnLoad: You can set name of a function or an array of names of the functions that should be called once the page is loaded.