Intro to layers

This tutorial will walk you through using layers.

The layer is the most fundamental component of a Map. It is a collection of spatial data in the form of graphics or images that represent real-world phenomena. Layers may contain discrete features that store vector data or continuous cells/pixels that store raster data.

Maps may contain different types of layers. For a broad overview of each layer type available in the API, see this table in the class description for Layer.

All layers inherit properties, methods and events from Layer. Some of these common properties are discussed in this tutorial. To learn about properties specific to different layer types, search the samples for that layer type (e.g. TileLayer).

Prior to completing the following steps, you should be familiar with views and Map. If necessary, complete the following tutorials first:

1. Create a Map, a MapView and a checkbox input HTML element.

Create a basic Map and add it to a MapView instance. Your JavaScript may look something like the code below:

Use dark colors for code blocksCopy
require(["esri/Map", "esri/views/MapView"], (Map, MapView) => {
  // Create the Map
  const map = new Map({
    basemap: "oceans"
  });

  // Create the MapView
  const view = new MapView({
    container: "viewDiv",
    map: map
  });
});

Add a checkbox element to the body of your HTML. The purpose of this element will be discussed later in the tutorial.

Use dark colors for code blocksCopy
<body>
  <div id="viewDiv"></div>
  <span id="layerToggle" class="esri-widget"> <input type="checkbox" id="streetsLayer" checked /> Transportation </span>
</body>

2. Create two layers using TileLayer

Create two instances of TileLayer prior to the code you wrote for creating a map and view. To do this, you must require the esri/layers/TileLayer module and specify the url property on the layer. The url property must point to a cached map service either hosted on ArcGIS Server or Portal for ArcGIS.

All layers used for accessing ArcGIS services have the url property, which must be set to render features in the view. In this sample we'll create layers for streets and highways using the Esri World Transportation service and a service containing data about housing density in New York City.

Use dark colors for code blocksCopy
require([
  "esri/Map",
  "esri/views/MapView",
  "esri/layers/TileLayer" // Require the TileLayer module
], (Map, MapView, TileLayer) => {
  const transportationLayer = new TileLayer({
    url: "https://server.arcgisonline.com/arcgis/rest/services/Reference/World_Transportation/MapServer"
  });

  const housingLayer = new TileLayer({
    url: "https://tiles.arcgis.com/tiles/nGt4QxSblgDfeJn9/arcgis/rest/services/New_York_Housing_Density/MapServer"
  });

  /*****************************************************************
   * The code to create a map and view instance in the previous step
   * should be placed here.
   *****************************************************************/
});

3. Set additional properties on the layers

You may set additional properties on the layers including an id, minScale, maxScale, opacity, and visible. These may either be set in the constructor or directly on the instance at another point in your application.

We'll add an id to each layer and set the opacity on the transportation layer.

Use dark colors for code blocksCopy
const transportationLayer = new TileLayer({
  url: "https://server.arcgisonline.com/arcgis/rest/services/Reference/World_Transportation/MapServer",
  id: "streets",
  opacity: 0.7
});

const housingLayer = new TileLayer({
  url: "https://tiles.arcgis.com/tiles/nGt4QxSblgDfeJn9/arcgis/rest/services/New_York_Housing_Density/MapServer",
  id: "ny-housing"
});

The id uniquely identifies the layer, making it easy to reference in other parts of the application. If this isn't set directly by the developer, then it is automatically generated when the layer is created.

The minScale and maxScale properties control the visibility of the layer at various scales. Using these properties can improve app performance at certain scales and enhance the cartography of the map. The visible property is true by default.

4. Add the layers to the map

Layers may be added to the map in several ways. These are all discussed in the documentation for Map.layers. In this sample we'll add each layer to the map in a different way.

Add the housing layer to the map's constructor.

Use dark colors for code blocksCopy
// Both layers were created prior to this code snippet
const map = new Map({
  basemap: "oceans",
  layers: [housingLayer] // layers can be added as an array to the map's constructor
});

Add the transportation layer to the map using map.layers.add().

Use dark colors for code blocksCopy
map.layers.add(transportationLayer);

Now both layers should be visible in the view.

5. Work with a layer's visibility

Use the addEventListener method to listen to a change event on the checkbox element created in the first step. When the box is checked on and off it will toggle the visibility of the transportation layer on and off. Like visible, any property of any layer may be set directly on the layer instance. This is accomplished in the snippet below.

Use dark colors for code blocksCopy
require(["esri/Map", "esri/views/MapView", "esri/layers/TileLayer"], (
  Map,
  MapView,
  TileLayer
) => {
  /*****************************************************************
   * All code previously written in the steps above should be placed
   * before the following code
   *******************************************************************/

  // Create a variable referencing the checkbox node
  const streetsLayerToggle = document.getElementById("streetsLayer");

  // Listen to the change event for the checkbox
  streetsLayerToggle.addEventListener("change", () => {
    // When the checkbox is checked (true), set the layer's visibility to true
    transportationLayer.visible = streetsLayerToggle.checked;
  });
});

Even though the layer is not visible to the view in this sample, it still exists as part of the map. Therefore, you can still access all of the properties of the layer and use them for analysis even though the user may not see the layer rendered in the view.

6. Understanding LayerViews

The Layer object manages geographic and tabular data published as a service. It does not handle rendering the layer in the View. That is the job of the LayerView. A Layer's LayerView is created just before it renders in the view. When working with FeatureLayers, the corresponding FeatureLayerView can provide the developer with access to the graphics rendered in the view related to that layer's features.

In this step, we'll listen for the view's layerview-create event and print the LayerViews of the housing and the transportation layers so you can explore their properties in the console. Notice that we'll use the id we created for each layer in step 3 to get the desired layers. In addition to a map's operational layers, this event fires for basemap layers and elevation layers.

Use dark colors for code blocksCopy
require(["esri/Map", "esri/views/MapView", "esri/layers/TileLayer"], (
  Map,
  MapView,
  TileLayer
) => {
  /*****************************************************************
   * All code previously written in the steps above should be placed
   * before the following code
   *******************************************************************/

  // This event fires each time a layer's LayerView is created for the
  // specified view instance
  view.on("layerview-create", (event) => {
    if (event.layer.id === "ny-housing") {
      // Explore the properties of the housing layer's layer view here
      console.log("LayerView for New York housing density created!", event.layerView);
    }
    if (event.layer.id === "streets") {
      // Explore the properties of the transportation layer's layer view here
      console.log("LayerView for streets created!", event.layerView);
    }
  });
});

7. Using Layer.when()

A layer returns a promise that resolves when loaded, or when all its properties are available to the developer. In this sample, we want to animate the view to the fullExtent of the housing layer since we may not know a good extent (or center and zoom) to use for initializing the view.

We cannot get the layer's fullExtent until it has loaded. So we must handle the animation once the promise resolves. This is handled using when().

Use dark colors for code blocksCopy
// When the layer's promise resolves, animate the view to the layer's fullExtent
housingLayer.when(() => {
  view.goTo(housingLayer.fullExtent);
});

8. Summary

There are many more properties of Layer that have not been discussed here. To learn more about additional properties related to specific layers, see the API documentation and samples listed in the table of contents on this page. The final code for this tutorial can be reviewed in the sandbox.

MapView

layers