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,
myFeatureLayer.setDefinitionExpression(expression);
whereas the following line shows how to set a feature layer's definitionExpression in 4.0,
myFeatureLayer.definitionExpression = expression;
Using 4.0, it is possible to use .get()
to access deep properties similar to the following snippet,
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.
// 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:
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,
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,
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 nowesri/widgets/
. - Shorter, clearer module names, e.g.
Tile
instead ofLayer ArcGIS
.Tiled Map Service Layer - Consistently cased module names, all modules now start with an uppercase letter, incl
Map
,Graphic
andQuery
. - Support classes have been moved into support folders to keep the API reference more organized, for example
esri/layers/support
andesri/rest/support
. - The structure of
esri/config
changed. The properties ofesri
are now located inConfig.defaults esri
. For example, to set the default geometry service:Config
// 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 nowesri
.Config.request
// 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
from
method instead. For example,JSO N() Graphic.from
. (Note: Beta 3 still contains some constructors that use the 3.x style).JSO N() - There are no graphics on the
Feature
. LayerView now renderers graphics representing features in FeatureLayer.Layer
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.