ArcGIS API for JavaScript ^3.26

Dojo and Asynchronous Module Definition(AMD)

The ArcGIS API for JavaScript is built using Dojo, which fully supports creating classes and modules using Asynchronous Module Definition (AMD) style code. The older style of using dojo.provide(), dojo.require() and dojo.declare() is still supported as well. It is up to the developer to choose which style to use, but for new applications, developers should use AMD as the older style will not work with Dojo 2.0 and beyond. For more general information on AMD, refer to the AMD API page on Github.

As of version 3.4 of the ArcGIS API for JavaScript, all Esri modules are written in the AMD style using define() and dojo/_base/declare.

The benefits of using AMD are outlined on the github page linked above as well as in the Dojo tutorial on defining modules. Rather than re-hash those points, this page will stick to the specifics in writing AMD style code versus the older dojo.declare style.

To create and use AMD style modules, changes need to occur both in the JavaScript file(s) that define modules as well as in the application JavaScript that loads modules.

To begin, let's look at module definitions. Modules no longer begin with dojo.provide. Instead, modules are created by calling define(). While there are multiple ways to create modules with define(), to mimick the classes in the Writing a Class tutorial, it is recommended to include dojo/_base/declare as a dependency of a module and return the value of calling declare(). This is illustrated in the AMD code used below in the two examples. Before talking more about dojo/_base/declare, let's look at class names/module identifiers.

Class names can still be explicitly created using the first argument passed to define, but this is optional. If define is not passed a string as the first argument, the module identifier will be built using the module's path and file name. For instance, using the same file structure as used in the Writing a Class tutorial, the module name for EmptyLayer would be "extras/EmptyLayer". This is how the modules in the examples below are created.

Instead of using dojo.require() to load dependencies, dependencies are specified as an array passed to define. Once those dependencies are loaded, they are passed to a callback function. The recommended pattern for usage of define() is to have define's callback function return the value returned by declare. This way, the result of declare (which is loaded by specifiying dojo/_base/declare as a dependency) is cached as the module's value.

The two examples used in the Writing a Class tutorial, one using a Seat Geek search class and the other to create an empty layer, have been converted to use AMD style define() and require() calls to create and load custom modules:

• SeatGeekSearch (AMD version)
• EmptyLayer (AMD version)

The JavaScript doing the actual work is the same in both the older style of modules with dojo.declare and the newer AMD style. The big differences between legacy and AMD modules are how they are defined (dojo.declare() vs. define()) and how they are loaded (dojo.require() vs. require()).