Working with Dojo

Dojo is an open source toolkit that helps you write robust and efficient JavaScript code. JavaScript is a language that runs within the Web browser, and there are various flavors of Web browser that interpret the JavaScript in slightly different ways. Toolkits such as Dojo, YUI, Prototype, and many others are designed to abstract away the browser idiosyncrasies so that you don't have to learn them all and handle them in your code.

There are often several ways to code the same thing using JavaScript. Toolkits like Dojo provide functions you can use to do things in easier or more efficient ways. Using libraries from a toolkit can reduce the lines of code you write and make your JavaScript applications quicker and more stable.

What does it mean that the ArcGIS JavaScript API is built on top of Dojo?

The ESRI developers who created the ArcGIS JavaScript API used Dojo to simplify their development process and to ensure that the applications you build behave the same in different browsers. For example, the map zoom and panning animations use Dojo, as does the graphics layer.

Furthermore, the zoom level slider and info windows that you see in your JavaScript API maps are Dojo widgets (dijits). The slider dijit is provided with Dojo, and the info window is a custom dijit created by ESRI for the ArcGIS JavaScript API.

How much Dojo do I need to know in order to use the ArcGIS JavaScript API?

The amount of Dojo you use when you work with the ArcGIS JavaScript API is up to you, but at a minimum you'll need to use several common functions:

dojo.require: Similar to the <script> include tag on an HTML page. It imports resources into your JavaScript page.

dojo.require("esri.map");

For the JavaScript API, the most commonly imported resources are:

Resource	Use for:
esri.map	Map, geometry, graphics, and symbols
esri.layers.agsdynamic	ArcGISDynamicMapServiceLayer
esri.layers.agstiled	ArcGISTiledMapServiceLayer
esri.tasks.find	Find task
esri.tasks.geometry	Geometry task
esri.tasks.gp	Geoprocessing task
esri.tasks.identify	Identify task
esri.tasks.locator	Locator task
esri.tasks.query	Query task
esri.toolbars.draw	Draw
esri.toolbars.navigation	Navigation

dojo.addOnLoad: Similar to <body onload="">. It registers an initializing block after the page has finished loading.
```
dojo.addOnLoad(init); 
```
dojo.connect: Similar to Element.addEventListener and Element.attachEvent JavaScript functions. It registers a listener to listen to specific events on an Object or element on the page and returns results from a function.
```
dojo.connect(myMap, "onLoad", myLoadHandler); 
```
dojo.byId: Similar to the document.getElementById(id) JavaScript function. The function searches and returns the first HTML element with the argument ID.
```
dojo.byId("myInputField").value = myMap.id; 
```

When writing your ArcGIS JavaScript applications, you can take advantage of the full Dojo toolkit, which includes buttons, grids, tree views, charts, and other widgets. The toolkit is divided into three parts:

Core - Essential functions like those listed above
Dijit - Themeable widgets such as trees, menus, and buttons
DojoX- Extension projects in various stages of development, such as graphics, grids, and charts

How do I get Dojo? Do I have to install it?

Dojo is included with the ArcGIS JavaScript API. When you include the script tag referencing the ArcGIS JavaScript API, you get access to the full Dojo tookit version. The chart below shows the version of Dojo corresponding to each version of the ArcGIS JavaScript API:

ArcGIS JavaScript API version	Dojo version
1.0	1.1.0
1.1	1.1.0
1.2	1.2
1.3	1.2.3 with vml patch
1.4	1.3.1
1.5	1.3.2
1.6	1.4.1

Many Dojo users download Dojo and host it themselves, or they reference the publicly available Dojo hosted on the AOL Content Delivery Network (CDN). When building ArcGIS JavaScript applications, there is no need to download or host Dojo.

What if I'm already hosting Dojo or I want to reference a newer version of Dojo?

In general you should use the Dojo included with the ArcGIS JavaScript API, although you can reference a local deployment of Dojo if needed. If you are using version 1.6 of the ArcGIS JavaScript API the recommended approach is to rename the dojo namespaces to avoid conflicts with another version of Dojo. In the code below Dojo 1.2.3 from the AOL CDN is used with version 1.6 of the ArcGIS JavaScript API. To rename the namespace use djConfig.scopeMap to map dojo,dijit and dojox to different names, in this case esriDojo,esriDijit and esriDojox.

<script type="text/javascript" src="http://o.aolcdn.com/dojo/1.2.3/dojo/dojo.xd.js" ></script> 

<link rel="stylesheet" type="text/css" href="http://serverapi.arcgisonline.com/jsapi/arcgis/2.0/js/dojo/dijit/themes/tundra/tundra.css">
<script type="text/javascript">
 djConfig = {
    scopeMap: [
      [ "dojo", "esriDojo" ],
      [ "dijit", "esriDijit" ],
      [ "dojox", "esriDojox" ]
    ]
  };
</script>
<script type="text/javascript" src="http://serverapi.arcgisonline.com/jsapi/arcgis/?v=2.0"></script>

After you rename the dojo namespace the ArcGIS JavaScript API will use the dojo version included with the API. Developers can use the ESRI version or load and use a different version of dojo for portions of the page. Click here to view a sample that renames the Dojo namespaces.

If you are using versions 1.2 through 1.5 of the ArcGIS JavaScript API use the following approach. Please note that if you use a version other than the one delivered with the API you may run experience issues. Place the script tag referencing Dojo above the script tag referencing the ArcGIS JavaScript API. When you do this, the Dojo you referenced will be used instead of the Dojo normally included with the ArcGIS JavaScript API.

For example, the code below shows Dojo 1.2.0 from the AOL CDN used with the ArcGIS JavaScript API 1.2. You could replace the path to the CDN with the path to your local Dojo.

<link rel="stylesheet" type="text/css" href="http http://o.aolcdn.com/dojo/1.2.0/dijit/themes/tundra/tundra.css">
<script type="text/javascript" src="http://o.aolcdn.com/dojo/1.2.0/dojo/dojo.xd.js"></script>
<script type="text/javascript" src="http://serverapi.arcgisonline.com/jsapi/arcgis/?v=1.2"></script>

If you're using version 1.0 or 1.1 of the ArcGIS JavaScript API, the code is a bit different. You need to explicitly reference the esri.js and jsapi.js files. The following example uses Dojo 1.1.1 from the AOL CDN with version 1.1 of the ArcGIS JavaScript API:

<link rel="stylesheet" type="text/css" 
    href="http://serverapi.arcgisonline.com/jsapi/arcgis/1.1/js/dojo/dijit/themes/tundra/tundra.css">
<script type="text/javascript" src="http://o.aolcdn.com/dojo/1.1.1/dojo/dojo.xd.js"></script>
<script type="text/javascript" src="http://serverapi.arcgisonline.com/jsapi/arcgis/1.1/js/esri/esri.js"></script>
<script type="text/javascript" src="http://serverapi.arcgisonline.com/jsapi/arcgis/1.1/js/esri/jsapi.js"></script>

What are dijits and why are they useful?

You can use Dojo widgets, or "dijits", to add prepackaged user interface components to your applications. Dojo has many existing dijits you can choose from such as text boxes, buttons, menus, calendars, color pickers, and so on. The online Book of Dojo has a nice overview of the Dijit library that you can use to browse the dijits.

Dijits have been tested to behave consistently in different browsers and comply with accessibility and localization requirements. The dijit framework is extensible, so with a little ambition you can even create your own dijits.

You can also combine several dijits into one for easy re-use. Suppose your company has multiple Web designers that want to embed maps in their pages. You can wrap up a map and some other elements inside a dijit, which the Web designers can then add to their pages without having to learn how to use the ArcGIS JavaScript API.

Dijits can also help users accomplish focused workflows, such as finding nearby dentists, selecting a site for a business, or generating a route. In this way, dijits are similar to "tasks" in the Web ADF.

If you have dijits that appear in your page when the application loads, you should include this line before adding the script tag that references the ArcGIS JavaScript API (version 1.1 or 1.2):

<script type="text/javascript">djConfig = { parseOnLoad: true }</script>

How do I get help with Dojo?

The Dojo Web site, www.dojotoolkit.org contains the official Dojo documentation. Documentation may be sparse, especially for projects in DojoX. Depending on what you're doing, you may find more information in one of the various Dojo books that have recently become available. The Dojo forums and the #dojo chat room on the IRC server irc.freenode.net are other good ways to get help.

The ArcGIS Server Blog also has periodic posts about working with Dojo and dijits in ArcGIS JavaScript API applications.