ArcGIS API for JavaScript ^3.26

The information below is provided as a guide to address common issues when updating a 2.8 application to version 3.0 of the ArcGIS API for JavaScript.

Version 3.0 of the ArcGIS API uses Dojo 1.7, which made significant changes to several parts of Dojo. Notably, the loader supports AMD and continues to support module loading with the older dojo.require style. The organization of Dojo modules has changed as well.

Referencing Objects and Properties in the esri Namespace

All code that references the esri namespace needs to run after all modules loaded. Using dojo.ready/addOnLoad (as shown in all samples) guarantees that all modules are loaded. This includes setting properties on esri.config, like a proxy URL. Error messages like "Uncaught ReferenceError: esri is not defined" or "ReferenceError: esri is not defined" are likely a result of referencing the esri object before all modules have loaded.

Explicitly Requiring Modules

In some cases, it may be required to load additional modules to maintain the same functionality in an application when migrating from a 2.x release of the ArcGIS API for JavaScript to 3.0. For instance, the InfoWindow - Custom sample uses dojo.fx.Toggler to show and hide the custom info window. Pre-Dojo 1.7, this class was loaded automatically when dojo.fx was loaded. This is not the case at 1.7 and dojo.fx.Toggler must be explicitly required. This is shown in the JavaScript that defines the custom InfoWindow module.

Configuring Dojo to Load Custom Modules

Dojo's configuration for module loading is still specified as a data-dojo-config attribute on the script tag that references dojo or with a global variable named dojoConfig (or djConfig). Pre-1.7, the baseUrl and modulePaths properties were used to tell Dojo where to find custom modules. Again, using the InfoWindow - Custom sample, here is how dojoConfig looked pre-1.7:

dojoConfig = {
  parseOnLoad: true,
  baseUrl: "./",
  modulePaths: {
    "myModules": "./myModules"
  }
};
  

At 1.7, baseUrl and modulePaths are replaced by the packages property. The value for packages is an array of objects and each object maps a name to a location. When using a CDN hosted version of Dojo (which includes the ArcGIS API for JavaScript), the easiest way to specify a package's location is to use a regular expression to grab the path used by the application and reference your JavaScript files relative to that. This trick was pulled from the "Using Custom Modules with a CDN" Dojo tutorial linked below. Here's how dojoConfig looks for the InfoWindow - Custom sample when using version 3.0 of the ArcGIS API for JavaScript:

dojoConfig = {
  parseOnLoad: true,
  packages: [{
    "name": "myModules",
    "location": location.pathname.replace(/\/[^/]+$/, "") + "/myModules"
  }]
};
  

For more information on loading custom modules, please refer to these Dojo Tutorials:

• Introduction to AMD Modules
• Configuring Dojo with dojoConfig
• CDN

Using dojo.declare

Using dojo.declare in JavaScript that's not loaded by the loader (meaning a class is declared in a file referenced directly by a script tag, or inside a script tag in an html page) and not wrapped in a function called by dojo.ready does not work at Dojo 1.7. While this worked pre-1.7, it was never recommended. There are two recommended ways to address this:

• Re-factor application code to use the loader to load custom classes
• Wrap uses of dojo.declare in a function called by dojo.ready

Below is an example of wrapping a call to dojo.declare in a function called by dojo.ready:

dojo.ready(function() {
  dojo.declare("esri.layers.WebTileLayer", [esri.layers.TiledMapServiceLayer], {
    ...custom code here...
  });
});
  

For additional info on changes made at Dojo 1.7, please refer to the Dojo 1.7 release notes.