Working with properties

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

All properties in each class may be set in the constructor. For more information about how this works, please refer to the Constructors section in the Programming Patterns topic.

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.

Use dark colors for code blocks
     
1
2
3
4
5
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.

Use dark colors for code blocks
 
1
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.

Use dark colors for code blocks
   
1
2
3
 view.center = [ -100, 40 ];
 view.zoom = 6;
 map.basemap = 'oceans';

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

Use dark colors for code blocks
     
1
2
3
4
5
var viewProperties = {
  center: [ -100, 40 ],
  zoom: 6
};
view.set(viewProperties);

Prior to 4.x, 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, consistent way of getting and setting all properties.

Watching properties

Prior to 4.x, watching property changes were handled via events.

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.

Use dark colors for code blocks
            
1
2
3
4
5
6
7
8
9
10
11
12
// 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 = 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:

Use dark colors for code blocks
 
1
map.basemap = "topo-vector";

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

Use dark colors for code blocks
    
1
2
3
4
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:

Your browser is no longer supported. Please upgrade your browser for the best experience. See our browser deprecation post for more details.