Migrating from 3.x to 4.31

Version 4.x is a substantial overhaul of the ArcGIS Maps SDK for JavaScript and its mapping components. Consider rewriting applications instead of simply trying to update them.

This topic is designed to provide developers with existing apps using the 3.x API help in doing just this. Although there is a long list of updates made to the API, we have listed a few notable ones:

• Handling properties
• Using views
• Map and layer specific
• Module and package updates
• WebMap support
• Localization
• AMD only
• Deprecation note

Significant changes were made for version 4.0. These changes were made to aid our developers in working more efficiently and effectively on whatever application they create. These changes can be seen in how constructors, properties, and events are handled.

Properties

Prior to 4.0, some properties could be get (read) or set (write) by calling getMethodName or setMethodName. These types of methods are no longer needed as the API supports a simple and consistent way of getting and setting all properties.

• Set the property directly on the object, for example map.basemap = "oceans".
• Get the property directly from the object, for example map.basemap.title.

For example, in 3.x, setting a feature layer's definitionExpression looks similar to,

1
myFeatureLayer.setDefinitionExpression(expression);

whereas the following line shows how to set a feature layer's definitionExpression in 4.0,

1
myFeatureLayer.definitionExpression = expression;

Using 4.0, it is possible to use .get() to access deep properties similar to the following snippet,

1
var basemapTitle = map.get("basemap.title");

Watching property changes

Prior to 4.0, property changes were handled with events. In 4.x, watching for property changes has become much easier. This is handled using the reactiveUtils.watch() method. The ReactiveWatchCallback is called each time the property changes and allows you to work with the property's new value and old value.

1
2
3
4
5
6
7
8
9
10
// Creates a new Map with a "streets-vector" basemap
var map = new Map({
  basemap: "streets-vector"
});

// watch handler: the callback fires each time the title of the map's basemap changes
var handle = reactiveUtils.watch(()=> map.basemap.title, (newValue, oldValue)=>{
  // Prints out the new value of the property along with it's previous value before it changed.
  console.log(`New value: ${newValue}<br>Old value: ${oldValue}`);
});

Views

At 4.0, a Map can be displayed in 2D or 3D. Because of this, the drawing logic was revised. The Map and Layers no longer handle the drawing logic, instead it is now handled by Views.

Views are a concept introduced at version 4.0. A view can be one of two types:

• MapView, applicable if working in 2D, or
• SceneView, applicable if working in 3D

Views are used specifically to visualize the data within your map or scene. A map contains the actual data or layers to display, whereas the view handles displaying this data. How this data is visualized, or displayed, varies depending on whether you're working in 2D or 3D. The view has a reference to the map, e.g. view.map. But the map does not have a reference to the view. It is important to note that a single map can be consumed by multiple views.

Here's another way to think of this: the map describes the basemap and features in the world, whereas the view is the window to that map that allows it to be viewed.

The syntax below shows how to create and work with both a 2D view (MapView) and a 3D view (SceneView).

The following snippet shows 2D mapping using a MapView,

1
2
3
4
5
6
7
8
9
10
function (Map, MapView){
  map = new Map({
    basemap: "topo-vector"
  });
  view = new MapView({
    container: "viewDiv",
    map: map,
    scale: 2400000
  });
}

This snippet shows 3D mapping using a SceneView,

1
2
3
4
5
6
7
8
9
10
function (Map, SceneView){
  map = new Map({
    basemap: "topo-vector"
  });
  view = new SceneView({
    container: "viewDiv",
    map: map,
    scale: 2400000
  });
}

Map and layer specifics

Some significant updates were made to the Map and Layers; a few of these are listed below:

• Starting with 4.0, the basemap is separated from the operational layers in the map.
• It is also now possible to rotate a view, either in 2D or 3D.
• Graphic layers can be added anywhere in a map's layer collection. Prior to 4.0, they always had to be on top of non-graphics layers.
• A GroupLayer class has been added.

Module and package updates

See the module updates topic for details, below are a few notable ones:

• Changed package names, e.g. esri/dijit is now esri/widgets/.
• Shorter, clearer module names, e.g. TileLayer instead of ArcGISTiledMapServiceLayer.
• Consistently cased module names, all modules now start with an uppercase letter, incl Map, Graphic and Query.
• Support classes have been moved into support folders to keep the API reference more organized, for example esri/layers/support and esri/rest/support.
• The structure of esri/config changed. The properties of esriConfig.defaults are now located in esriConfig. For example, to set the default geometry service:

1
2
3
4
5
// 3.x
esriConfig.defaults.geometryService = new GeometryService("http://yourdomain.com/geometryService");

// 4.x
esriConfig.geometryService = new GeometryService("http://yourdomain.com/geometryService");

• The 3.x defaults.io object is now esriConfig.request.

1
2
3
4
5
// 3.x
esriConfig.defaults.io.timeout = 30000;

// 4.x
esriConfig.request.timeout = 30000;

• The three *-all legacy modules have been removed. This is better handled in a build or using the web optimizer.
• Constructors no longer support JSON, use the fromJSON() method instead. For example, Graphic.fromJSON(). (Note: Beta 3 still contains some constructors that use the 3.x style).
• There are no graphics on the FeatureLayer. LayerView now renderers graphics representing features in FeatureLayer.

WebMap support

It is possible to read version 2.x WebMaps. Working with the WebMap is partially supported. This means it relies on capabilities already available in the API. For example, it is possible to read WebMaps even if they contain layer types that are not yet implemented. In these instances, only layer types supported by the API will display. Saving webmaps is supported as of version 4.14.

Localization

At 4.x, right-to-left (RTL) is no longer a side effect of setting the locale to "ar" or "he".

• You can now opt-in to RTL for any locale. See RTL support.
• You specify the direction on the <html> or <body> tag. See RTL support.

Modules

The 4.x API is available as AMD, ES modules and components. Prior to 4.0, you could use AMD as well as dojo.require legacy modules. Beginning with 4.0, support was only provided for the AMD model. At 4.18 the ES modules were introduced, and at 4.30 components were introduced. See the Getting started with npm Guide page.

Deprecation note

• The Geocoder widget has been deprecated as of version 3.13. It is not part of 4.x. Please use the Search widget instead.