Working with properties

The ArcGIS JavaScript API supports a simple, consistent way of getting and setting all properties.

Getting properties

One way to access a property value is to reference it directly from the object. See the example below regarding how to get the title of a map's basemap using this method.

var basemapTitle = null;
// Check for the existence of basemap prior to getting the basemap's title
if (map.basemap) {
  basemapTitle = map.basemap.title;
}

You may also get properties using the get() function. The get() function automatically checks to see if the object exists prior to getting the desired property, so there's no need to check it yourself. In the prior example we checked this using if (map.basemap). In the snippet below, get() does this work for you.

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

Setting properties

To set a property value, it is possible to directly set it on the object as shown below.

 view.center = [ -100, 40 ];
 view.zoom = 6;
 map.basemap = 'oceans';

It also possible to set multiple properties at once by calling the set() method.

var viewProperties = {
  center: [ -100, 40 ],
  zoom: 6
};
view.set(viewProperties);

Watching properties

Watching property changes are handled with the .watch(property, callback) method. The callback is called each time the watched property changes. For convenience, it is also possible to watch for a nested property, such as basemap.title.

For example, in the snippet below, we set up a handler to watch for changes to the title of the map's basemap.

// Creates a new Map with a 'streets' basemap
var map = new Map({
  basemap: 'streets'
});

// watch handler: the callback fires each time the title of the map's basemap changes
var handle = map.watch('basemap.title', function(newValue, oldValue, property, object) {
  console.log("New value: ", newValue,      // The new value of the property
              "<br>Old value: ", oldValue,  // The previous value of the changed property
              "<br>Watched property: ", property,  // In this example this value will always be "basemap.title"
              "<br>Watched object: ", object);     // In this example this value will always be the map object
});

If the user changes the basemap to the following:

map.basemap = "topo";

The console will log the following information based on the watch handler:

New value: Topographic
Old value: Streets
Watched property: basemap.title
Watched object: // This will log the map object

Not all properties can be watched. This is true for any property of type Collection. Instead of watching, developers can register an event handler to be notified of changes to the collection. See the change event documentation for more details.

Additional information

Please refer to these additional links for further information:

• Migrating from 3.x to 4.9
• Accessor class