Hide Table of Contents
esri/dijit/util
esri/layer/pixelFilters
esri/process
esri/workers
Object: esri/arcgis/utils

require(["esri/arcgis/utils"], function(arcgisUtils) { /* code goes here */ });

Description

(Added at v2.0)
Utility methods to work with content from ArcGIS.com.

When coding legacy (non-AMD) style, there is no need to require the module. All methods and properties are available in the namespace. For example, esri.arcgis.utils.createMap().

Samples

Search for samples that use this class.

Properties

NameTypeSummary
arcgisUrlStringSpecify the domain where the map associated with the webmap id is located.

Methods

NameReturn typeSummary
createMap(itemIdOrItemInfo, mapDiv, options?)DeferredCreate a map using information from an ArcGIS.com item.
getItem(itemId)DeferredGet details about the input ArcGIS.com item.
getLayerList(createMapResponse)Object[]Can be used with LayerList widget to get the layers list to be passed into the constructor.
getLegendLayers(createMapResponse)Object[]Can be used with esri.dijit.Legend to get the layerInfos list to be passed into the Legend constructor.
Property Details

<String> arcgisUrl

Specify the domain where the map associated with the webmap id is located. The default value is http://www.arcgis.com/sharing/rest/content/items
Known values:
Default value: http://www.arcgis.com/sharing/rest/content/items
Sample:
arcgisUtils.arcgisUrl = "http://mydomain/sharing/rest/content/items";
Method Details

createMap(itemIdOrItemInfo, mapDiv, options?)

Create a map using information from an ArcGIS.com item. The information included in the response object returned to the callback depends on the version.

Note:
  • If working with an item whose basemap layer does not have a geographic or Web Mercator spatial reference, you will need to make certain the createMap method projects the item's extent using a geometry service or by passing in an extent using options.mapOptions. If using a geometry service, it will either create a new GeometryService using the options.geometryServiceURL or it will use the GeometryService at esriConfig.defaults.geometryService (if it exists).
  • It is recommended to use usePopupManager:true if working with popups within the web map. One thing to note about this is that the clickEventHandle and clickEventListener will be undefined. Instead, use the Map.setInfoWindowOnClick to control visibility of the popup.
{
  map: <esri.Map>,
  clickEventHandle, <undefined>
  clickEventListener, <undefined>
  itemInfo:{
    item: <Object>,
    itemData:<Object>,
    errors: [<Object>]
  }
}

The returned object contains the following properties.

{
  map: <esri.Map>,
  clickEventHandle, <Event Handler>
  clickEventListener, <Function>
  itemInfo:{
    item: <Object>,
    itemData:<Object>,
    errors: [<Object>]
  }
}

clickEventHandle: handle to the map event connection registered by createMap to display popups. Use this if you need to disconnect the handle at runtime.

require(["dojo/_base/connect", ... ], function(connect, ... ) {
  connect.disconnect(response.clickEventHandle);
});

clickEventListener: Use this function to reconnect the popup event handler.

map.on("click", function(response) {
  console.log(response.clickEventListener);
});
Return type: Deferred
Parameters:
<String | Object> itemIdOrItemInfo Required An itemId for an ArcGIS.com item or the response object obtained from calling the arcgisUtils.getItem method. You can discover the item's unique ID by browsing to the item in ArcGIS.com then extracting the id from the item's URL.
<String> mapDiv Required Container ID for referencing map.
<Object> options Optional Optional parameters that define the map functionality. See the Object Specifications table below for the structure of the options object.
Object Specifications:
<options>
<String> bingMapsKey Optional The Bing Maps key, required if working with Microsoft Bing Maps.
<Boolean> editable Optional Whether to allow layers in the created web map to be editable. If set to false, createMap() will create FeatureLayers where FeatureLayer.isEditable() returns false. This will override layers that would have otherwise been editable. This allows the FeatureLayer to load features optimally. Added at v3.11
<String> geometryServiceURL Optional URL to the ArcGIS Server REST resource that represents a geometry service. If not using a geometry service from esriConfig.defaults.geometryService, you will need to specify this if the basemap layer is not geographic or Web Mercator. For more information on constructing a URL, see the Services Directory and the REST API.
<Boolean> ignorePopups Optional When true, webmap define popups will not display.
<Object[]> layerMixins Optional An optional array of objects which identify the layer using either matching id or url properties. It also has a Object mixin property that is mixed into the layer. Added at 3.14
<Object> mapOptions Optional See the optional parameters for the esri.map constructor for more details.
<Boolean> usePopupManager Optional If true and a map click event occurs, it may show the map's infoWindow. If the infoWindow supports showing more than one feature, it will search for all features in all layers of the map that have an infoTemplate configured, including the sublayers of a ArcGIS tiled or dynamic map service. When false, disables the Map.showInfoWindowOnClick behavior. The default value is false. (Added in version 3.10) See also: Map.setInfoWindowOnClick(enabled).
Sample:
var map, bingMapsKey;

require([
  "esri/arcgis/utils",
  "esri/map", "dojo/domReady!"
  ], function (arcgisUtils, Map) {
    var deferred;
    var createMapOptions = {
      mapOptions: {
        slider: true
      },
      usePopupManager: true, // since version 3.10
      bingMapsKey: bingMapsKey,
      geometryServiceURL: "http://sampleserver3.arcgisonline.com/ArcGIS/rest/services/Geometry/GeometryServer"
    };
    var webMapItemID = "c41d5f3b4e304806a047702fbfc2759e";
    deferred = arcgisUtils.createMap(webMapItemID, "ui-map", createMapOptions);

    deferred.then(function (response) {
      map = response.map;
    }, function (error) {
         console.log("Error: ", error.code, " Message: ", error.message);
         deferred.cancel();
    });
});

getItem(itemId)

Get details about the input ArcGIS.com item. An object with the following specification is passed to the callback:
{
  item: <Object>,
  itemData: <Object>
}
The information included in the response object returned to the callback depends on the version. View the Working with web maps help topic for details on the response object.
Return type: Deferred
Parameters:
<String> itemId Required The itemId for a publicly shared ArcGIS.com item. You can discover the item's unique ID by browsing to the item in ArcGIS.com then extracting the id from the item's URL.

getLayerList(createMapResponse)

Can be used with LayerList widget to get the layers list to be passed into the constructor. (Added at v3.14)
Return type: Object[]
Parameters:
<Object> createMapResponse Required The object created from the resolved promise returned by createMap().
Sample:
    arcgisUtils.createMap("df8bcc10430f48878b01c96e907a1fc3", "map").then(function(response){
        var myWidget = new LayerList({
           map: response.map,
           layers: arcgisUtils.getLayerList(response) 
        },"layerList");
        myWidget.startup();
    });
});

getLegendLayers(createMapResponse)

Can be used with esri.dijit.Legend to get the layerInfos list to be passed into the Legend constructor. It will honor show/hide legend settings of each layer and will not include the basemap layers. See also: Legend layerInfos constructor option. (Added at v3.4)
Return type: Object[]
Parameters:
<Object> createMapResponse Required Object returned by .createMap() in the .then() callback.
Sample:
require(["esri/arcgis/utils"], function(arcgisUtils) {
  arcgisUtils.createMap(webmapid, "map").then(function(response){
    var legendLayers = arcgisUtils.getLegendLayers(response);
  });
});