require(["esri/layers/support/Sublayer"], function(Sublayer) { /* code goes here */ });
Class: esri/layers/support/Sublayer
Inheritance: Sublayer Accessor
Since: ArcGIS API for JavaScript 4.1

Represents a sublayer in a MapImageLayer. MapImageLayer allows you to display, query, and analyze layers from data defined in a map service. Map services contain sublayers with properties such as renderer, labelingInfo, and definitionExpression, and others that are defined on the server. The properties of each sublayer on the map service may be dynamically changed by the user or developer.

Dynamic layers

Sublayers may be rendered on the fly as dynamic layers. Dynamic layers are created using the source property of the sublayer. There are two types of dynamic layers: dynamic map layers and dynamic data layers.

Dynamic map layers allow you to override sublayers in the map service with new renderers, definition expressions, opacity, scale visibility, etc. Multiple dynamic map layers may exist for a single map service layer.

Dynamic data layers provide the ability to create sublayers on the fly from data inside registered workspaces. The data may be tables with or without geometries, feature classes, or rasters. These data sources are not directly visible to the services directory, but may be published and configured with the ArcGIS Server Manager. Data from tables may be joined to other tables or dynamic map layers.

See also:
Example:
// defines the properties of various sublayers in a map service
var layer = new MapImageLayer({
  url: "https://sampleserver6.arcgisonline.com/arcgis/rest/services/USA/MapServer",
  sublayers: [
    {  // sets a definition expression on sublayer 3
      id: 3,
      definitionExpression: "pop2000 > 40000000"
    },
    {  // sublayer 2 will be rendered as defined in the map service
      id: 2
    },
    {  // sublayer 1 will be included in the layer, with visibility off
      id: 1,
      visible: false
    },
    {  // sublayer 0 will have new renderer and label
       // expressions applied in the view on the fly
      id: 0,
       renderer: {
         type: "class-breaks"  // autocasts as new ClassBreaksRenderer()
         // set renderer properties here
       },
       labelingInfo: [ new LabelClass ( ... ) ]
     }
   ]
});

Constructors

new Sublayer(properties)

Parameter:
properties Object
optional

See the properties for a list of all the properties that may be passed into the constructor.

Example:
// typical usage
var layer = new MapImageLayer({
  url: "https://sampleserver6.arcgisonline.com/arcgis/rest/services/USA/MapServer",
  sublayers: [  // autocasts as a Collection of Sublayers
    { // sets a definition expression on sublayer 0
      id: 0,
      definitionExpression: "pop2000 > 40000000"
    },
    {  // creates a dynamic data layer
      source: {
        type: dynamic-layer,
        dataSource: {
          type: "table",
          workspaceId: "MyDatabaseWorkspaceIDSSR2",
          dataSourceName: "ss6.gdb.Railroads"
        }
      }
    }
  ]
});

Property Overview

Any properties can be set, retrieved or listened to. See the Working with Properties topic.
NameTypeSummaryClass
String

The name of the class.

more details
more detailsAccessor
String

A SQL where clause used to filter features in the image.

more details
more detailsSublayer
Number

The sublayer's layer ID.

more details
more detailsSublayer
LabelClass[]

The label definition for this layer, specified as an array of LabelClass objects.

more details
more detailsSublayer
Boolean

Indicates if labels for the sublayer will be visible in the view.

more details
more detailsSublayer
MapImageLayer

The MapImageLayer to which the sublayer belongs.

more details
more detailsSublayer
Boolean

Indicates whether the layer will be included in the legend.

more details
more detailsSublayer
Number

The maximum scale at which the layer is visible in the view.

more details
more detailsSublayer
Number

The minimum scale at which the layer is visible in the view.

more details
more detailsSublayer
Number

The level of opacity to set on the sublayer on a scale from 0.0 - 1.0 where 0 is fully transparent and 1.0 is fully opaque.

more details
more detailsSublayer
PopupTemplate

The popup template for the sublayer.

more details
more detailsSublayer
Renderer

The renderer to apply to the sublayer.

more details
more detailsSublayer
DynamicMapLayer | DynamicDataLayer

An object that allows you to create a dynamic layer with data either from the map service sublayers or data from a registered workspace.

more details
more detailsSublayer
Collection<Sublayer>

If a sublayer contains sublayers, this property is a Collection of Sublayer objects belonging to the given sublayer with sublayers.

more details
more detailsSublayer
String

The title of the sublayer used to identify it in places such as the LayerList and Legend widgets.

more details
more detailsSublayer
String

The URL to the REST endpoint of the sublayer.

more details
more detailsSublayer
Boolean

Indicates if the layer is visible in the view.

more details
more detailsSublayer

Property Details

declaredClassStringreadonly inherited

The name of the class. The declared class name is formatted as esri.folder.className.

definitionExpressionString

A SQL where clause used to filter features in the image. Only the features that satisfy the definition expression are displayed in the View. Definition expressions may be set when a sublayer is constructed prior to it loading in the view or after it has been added to the MapImageLayer.

See also:
Examples:
var countiesLyr = layer.sublayers.find(function(sublayer){
  return sublayer.title === "States";
});
countiesLyr.definitionExpression = "STATE = 'Nebraska'"
// add a definition expression to sublayer when
// it is created in MapImageLayer constructor
var layer = new MapImageLayer({
  url: "https://sampleserver6.arcgisonline.com/arcgis/rest/services/USA/MapServer",
  sublayers: [{
    id: 0,
    definitionExpression: "STATE = 'Nebraska'"
  }]
});
// Set a definition expression on the sublayer with ID of 0
layer.findSublayerById(0).definitionExpression = "STATE = 'Nebraska'";

The sublayer's layer ID. When a source is not defined on the layer, this value represents the id of the sublayer defined by the map service. If creating a DynamicDataLayer or a MapDataLayer and adding it to the source property of the sublayer, the value of this property can be anything set by the developer.

See also:
Examples:
// Creates a MapImageLayer instance containing only the sublayers defined below.
var layer = new MapImageLayer({
  url: "https://sampleserver6.arcgisonline.com/arcgis/rest/services/USA/MapServer",
  // this service has four sublayers, but we're only going to include three.
  sublayers: [ { id: 2 }, { id: 1 }, { id: 0 } ]
});
// Creates a MapImageLayer instance containing only the sublayers defined below.
var layer = new MapImageLayer({
  url: "https://sampleserver6.arcgisonline.com/arcgis/rest/services/USA/MapServer",
  sublayers: [{ // sets a new renderer on this sublayer
    id: 2,
    renderer: {
      type: "class-breaks"  // autocasts as new ClassBreaksRenderer()
      // set renderer properties here
    }
  }, { // sets new labelingInfo on the sublayer
    id: 1,
    labelingInfo: [ new LabelClass( ... ) ]
  }, { // retains properties defined by the service, but makes sublayer not visible
    id: 0,
    visible: false
  }]
});

labelingInfoLabelClass[]

The label definition for this layer, specified as an array of LabelClass objects. Use this property to specify labeling properties for the layer such as label expression, placement, and size. For labels to display in the view, the labelsVisible property of the sublayer must be true.

See also:
Example:
var layer = new MapImageLayer({
  url: "https://sampleserver6.arcgisonline.com/arcgis/rest/services/USA/MapServer",
  sublayers: [{
    id: 3,
    labelsVisible: true,
    // labelingInfo autocasts to an array of LabelClass objects
    labelingInfo: [{
      labelExpression: "[name]",
      labelPlacement: "always-horizontal",
      symbol: {
        type: "text",  // autocasts as new TextSymbol()
        color: [255, 255, 255, 0.7],
        haloColor: [0, 0, 0, 0.85],
        haloSize: 1,
        font: {
          size: 11
        }
      },
      minScale: 2400000,
      maxScale: 73000
    }]
  }]
});

labelsVisibleBoolean

Indicates if labels for the sublayer will be visible in the view.

Default Value: false
See also:
Example:
// turns on labels defined for sublayer 0
layer.findSublayerById(0).labelsVisible = true;

The MapImageLayer to which the sublayer belongs.

legendEnabledBoolean

Indicates whether the layer will be included in the legend. When false, the layer will be excluded from the legend.

Default Value: true

maxScaleNumber

The maximum scale at which the layer is visible in the view. If the map is zoomed in beyond this scale, the layer will not be visible. A value of 0 means the layer does not have a maximum scale.

The user or developer can only set minScale and maxScale if the new values are within the scale range defined in the map service.

// the service specifies minScale = 10000 and maxScale = 500000
// this is valid
sublayer.minScale = 30000;
sublayer.maxScale = 100000;

// this is not valid because the values are
// outside the range specified by the service
sublayer.minScale = 5000;
sublayer.maxScale = 1000000;
See also:
Example:
var layer = new MapImageLayer({
  url: "https://sampleserver6.arcgisonline.com/arcgis/rest/services/USA/MapServer",
  sublayers: [
    {
      id: 0,
      minScale: 5000000,
      maxScale: 24000
    },
    {
      id: 1
      minScale: 24000,
      maxScale: 100
    }
  ]
});

minScaleNumber

The minimum scale at which the layer is visible in the view. If the map is zoomed out beyond this scale, the layer will not be visible. A value of 0 means the layer does not have a maximum scale.

The user or developer can only set minScale and maxScale if the new values are within the scale range defined in the map service.

// the service specifies minScale = 10000 and maxScale = 500000
// this is valid
sublayer.minScale = 30000;
sublayer.maxScale = 100000;

// this is not valid because the values are
// outside the range specified by the service
sublayer.minScale = 5000;
sublayer.maxScale = 1000000;
See also:
Example:
var layer = new MapImageLayer({
  url: "https://sampleserver6.arcgisonline.com/arcgis/rest/services/USA/MapServer",
  sublayers: [
    {
      id: 0,
      minScale: 5000000,
      maxScale: 24000
    },
    {
      id: 1
      minScale: 24000,
      maxScale: 100
    }
  ]
});

opacityNumber

The level of opacity to set on the sublayer on a scale from 0.0 - 1.0 where 0 is fully transparent and 1.0 is fully opaque. If the MapImageLayer.opacity is set, the actual opacity value of the sublayer will be the value of MapImageLayer.opacity multiplied by the sublayer's opacity.

See also:
Example:
// Set the opacity of the layer to 0.5
layer.findSublayerById(0).opacity = 0.5;

popupTemplatePopupTemplate

The popup template for the sublayer. When set, the popupTemplate allows users to access attributes and display their values in the view's popup when the user clicks the image.

Sublayers with a RasterDataSource cannot be queried and therefore do not support PopupTemplate.

See also:
Example:
var layer = new MapImageLayer({
  url: "https://sampleserver6.arcgisonline.com/arcgis/rest/services/USA/MapServer",
  sublayers: [{
    id: 0,
    popupTemplate: {
      title: "{COUNTY}",
      content: "{POP2007} people lived in this county in 2007"
    }
  }]
});

The renderer to apply to the sublayer. This value overrides the renderer read from the map service.

Known Limitations

  • 3D symbols are not supported in renderers set on MapImageLayer sublayers.
  • visual variables are not supported in renderers set on MapImageLayer sublayers.
See also:
Example:
var layer = new MapImageLayer({
  url: "https://sampleserver6.arcgisonline.com/arcgis/rest/services/USA/MapServer",
  sublayers: [{
    id: 0,
    renderer: {
      type: "simple",  // autocasts as new SimpleRenderer()
      symbol: {
        type: "simple-marker",  // autocasts as new SimpleMarkerSymbol()
        color: "black",
        size: 8
      }
    }
  }]
});

An object that allows you to create a dynamic layer with data either from the map service sublayers or data from a registered workspace. See DynamicMapLayer for creating dynamic layers from map service layers for on the fly rendering, labeling, and filtering (definition expressions). To create dynamic layers from other sources in registered workspaces such as tables and table joins, see DynamicDataLayer.

Example:
// Creates two sublayers that point to the same map service layer.
// Each layer presents different features in the data using
// definition expressions and renderers.
var mapImageLayer = mew MapImageLayer({
  sublayers: [{
    id: 10,
    definitionExpression: "POP < 100000",
    renderer: {
      type: "simple",  // autocasts as new SimpleRenderer()
      symbol: smallMarker
    },
    source: {
      type: "map-layer",
      mapLayerId: 0
    }
  }, {
    id: 11,
    definitionExpression: "POP > 100001",
    renderer: {
      type: "simple",  // autocasts as new SimpleRenderer()
      symbol: largeMarker
    },
    source: {
      type: "map-layer",
      mapLayerId: 0
    }
  }]
});

If a sublayer contains sublayers, this property is a Collection of Sublayer objects belonging to the given sublayer with sublayers.

Example:
// test function for determining if a MapImageLayer's sublayers
// contain at least one dynamic data layer
function hasDynamicDataLayer (layer){
  if (layer.sublayers && layer.sublayers.sublayers){
    return layer.sublayers.sublayers.some(function(sublayer){
      return sublayer.source.type === "data-layer";
    });
  } else {
    console.log("layer does not have sublayers or nested sublayers");
    return false;
  }
}

titleString

The title of the sublayer used to identify it in places such as the LayerList and Legend widgets. This value can be defined in the map service or programmatically by the developer. It can also be useful for finding a specific sublayer.

Example:
var radarSublayer = layer.sublayers.find(function(sublayer){
  return sublayer.title === "radar";
});

The URL to the REST endpoint of the sublayer. This allows you to view the schema of fields and query tables located in registered workspaces.

visibleBoolean

Indicates if the layer is visible in the view.

See also:
Example:
var layer = new MapImageLayer({
  url: "https://sampleserver6.arcgisonline.com/arcgis/rest/services/USA/MapServer",
  sublayers: [{
    // this sublayer is visible by default
    id: 0
  }, {
    // this sublayer will be added to the layer but not visible
    id: 1,
    visible: false
  }]
    // all other sublayers in the service are excluded from the layer
});

Method Overview

NameReturn TypeSummaryClass
Sublayer

Creates a deep clone of the sublayer.

more details
more detailsSublayer
Query

Creates a Query object with default values representing the layer's state, including filters (definition expression) on the layer's features.

more details
more detailsSublayer
Promise<FeatureSet>

Executes a query against features in the sublayer.

more details
more detailsSublayer

Method Details

clone(){Sublayer}

Creates a deep clone of the sublayer.

Returns:
TypeDescription
SublayerA deep clone of the sublayer instance that invoked this method.

createQuery(){Query}

Creates a Query object with default values representing the layer's state, including filters (definition expression) on the layer's features.

Returns:
TypeDescription
QueryThe default query object including the definitionExpression for the sublayer.

queryFeatures(params){Promise<FeatureSet>}

Executes a query against features in the sublayer.

Parameter:
params Query
optional

Specifies the attributes and spatial filter of the query. If no parameters are specified, then all features satisfying the layer's configuration/filters are returned.

Returns:
TypeDescription
Promise< FeatureSet>Returns a promise that resolves to a FeatureSet containing the features that satisfy the query.

Type Definitions

DynamicDataLayer

A dynamic data layer is a layer created on-the-fly with data stored in a registered workspace. This is data that can be rendered and queried on the fly, but that isn't explicitly exposed as a service sublayer. Depending on the type of data source, these layers are classified as one of the following:

Data sourceDescription
TableDataSourceA feature class with geometries or table without geometries. When a table data source does not contain geometries, it may be used as one of the sources in a join operation. Feature class tables may be used on their own since they contain a geometry field.
QueryTableDataSourceA feature class or table that may be queried on the fly with a SQL where clause. This data source is useful for scenarios where you have a table containing unique geometries and another table with multiple records that match to each geometry. You can use the QueryTableDataSource to select only a subset of those matching records (so records in both tables have a one-to-one relationship with each other) and join them to the table with geometries.
RasterDataSourceA raster dataset used for visualization purposes only.
JoinTableDataSourceThis data source consists of two data sources joined by a common attribute or key. The left table data source typically contains geometries, while the right source may be a table or query table without geometries.
Properties:
type String

This value is always data-layer and is inferred when the dataSource property is set.

A table, feature class, or raster that resides in a registered workspace (either a folder or geodatabase). The data sources are not visible in the Services Directory by default. They may be viewed, published, and configured using the ArcGIS Server Manager.

fields Object[]

Controls field visibility in the layer. Only specified fields will be visible. If null, all fields are visible in the dynamic layer. The specification for a field object is provided below.

Specification:
name String

The name of the field.

alias String

The alias of the field.

See also:
Example:
var layer = new MapImageLayer({
  url: "https://sampleserver6.arcgisonline.com/arcgis/rest/services/Census/MapServer",
  sublayers: [{
    id: 0,
    renderer: renderer,
      opacity: 0.9,
      source: {
        type: "data-layer",
        dataSource: {
          type: "join-table",
          leftTableSource: {
            type: "map-layer",
            mapLayerId: 3
          },
          rightTableSource: {
            type: "data-layer",
            // references a table in a registered workspace that doesn't have geometries
            dataSource: {
              type: "table",
              workspaceId: "CensusFileGDBWorkspaceID",
              dataSourceName: "ancestry"
            }
          },
          leftTableKey: "STATE_NAME",
          rightTableKey: "State",
          joinType: "left-outer-join"
        }
      }
    }
  ]
});

DynamicMapLayer

A dynamic map layer refers to a layer published in a map service that has dynamic layers enabled. This layer type may be used to create multiple sublayers that point to the same service layer, but are assigned different definition expressions, renderers, and other properties.

Properties:
type String

This value is always map-layer and is inferred when the mapLayerId property is set.

mapLayerId Number

The id of the service sublayer.

gdbVersion String

An optional property for specifying the GDB version.

See also:
Example:
// Creates two sublayers that point to the same map service layer.
// Each layer presents different features in the data using
// definition expressions and renderers.
var mapImageLayer = new MapImageLayer({
  sublayers: [{
    id: 10,
    definitionExpression: "POP < 50000",
    renderer: {
      type: "class-breaks"  // autocasts as new ClassBreaksRenderer()
      // set renderer properties here
    },
    source: {
      type: "map-layer",
      mapLayerId: 0
    }
  }, {
    id: 11,
    definitionExpression: "GRADUATED_HS > 0.449",
    renderer: {
      type: "class-breaks"  // autocasts as new ClassBreaksRenderer()
      // set renderer properties here
    },
    source: {
      type: "map-layer",
      mapLayerId: 0
    }
  }]
});

JoinTableDataSource

The result of an on-the-fly join operation at runtime. Nested joins are supported. To use nested joins, set either leftTableSource or rightTableSource to join-table.

Properties:
type String

This value is always join-table and is inferred when other join table properties of this object are set.

leftTableKey String

The field name used for joining or matching records in the left table to records in the right table.

rightTableKey String

The field name used for joining or matching records in the right table to records in the left table.

The left table for joining to the right table source. This can either be a dynamic map layer or a dynamic data layer. The dynamic data layer may contain another join data source used for nested joining.

The right table for joining to the left table source. This can either be a dynamic map layer or a dynamic data layer. The dynamic data layer may contain another join data source used for nested joining.

joinType String

The type of join that will be performed.

Possible ValueDescription
left-outer-joinUnmatched records in the left table source are preserved and joined with null values in the right table source.
left-inner-joinRecords in the left table source are discarded if they are unmatched with records in the right table source.
See also:
Example:
var layer = new MapImageLayer({
  url: "https://sampleserver6.arcgisonline.com/arcgis/rest/services/Census/MapServer",
  sublayers: [{
    id: 0,
    renderer: renderer,
    opacity: 0.9,
    source: {
      type: "data-layer",
      dataSource: {
        type: "join-table",
        leftTableSource: {
          type: "map-layer",
          mapLayerId: 3
        },
        rightTableSource: {
          type: "data-layer",
          dataSource: {
            type: "table",
            workspaceId: "CensusFileGDBWorkspaceID",
            dataSourceName: "ancestry"
          }
        },
        leftTableKey: "STATE_NAME",
        rightTableKey: "State",
        joinType: "left-outer-join"
      }
    }
  }]
});

QueryTableDataSource

A query table is a feature class or table defined by a SQL query on the fly. Query layers allow both spatial and nonspatial information stored in a database to be easily integrated into map service operations. Since a query table uses SQL to directly query database tables and views, spatial information used by a query table is not required to be in a geodatabase.

This data source is useful for scenarios where you have a table containing multiple records that match to a single geometry in either another table or a map service layer. You can use the QueryTableDataSource to select only a subset of those matching records and join them to the table with geometries so records in both tables have a one-to-one relationship with each other.

Properties:
type String

This value is always query-table and is inferred when the query property of this object is set.

workspaceId String

The workspace where the data resides (defined in ArcGIS Server Manager).

query String

The SQL query used to filter records.

oidFields String

The field name(s) containing the unique IDs for each record in the table. This can be a comma separated list if the query table is used in a JoinTableDataSource.

spatialReference SpatialReference

The spatial reference of the geometry of each feature in the table source.

geometryType String

The geometry type of each record in the table.

Possible Values: point | multipoint | polyline | polygon | multipatch

See also:
Example:
var layer = new MapImageLayer({
  url: "https://sampleserver6.arcgisonline.com/arcgis/rest/services/USA/MapServer",
  sublayers: [{
    title: "Places",
    renderer: renderer,
    source: {
      type: "data-layer",
      dataSource: {
        type: "query-table",
        workspaceId: "MyDatabaseWorkspaceIDSSR2",
        query: "SELECT * FROM ss6.gdb.Places",
        oidFields: "objectid"
      }
    }
  }]
});

RasterDataSource

A file-based raster that resides in a registered raster workspace. The raster may only be displayed in the view, not queried or assigned a renderer.

Properties:
type String

This value is always raster.

workspaceId String

The workspace where the raster resides as defined in the ArcGIS Server Manager.

dataSourceName String

The name of the raster in the registered workspace.

See also:
Example:
var layer = new MapImageLayer({
  url: "https://sampleserver6.arcgisonline.com/arcgis/rest/services/Elevation/GlacierBay/MapServer",
  sublayers: [{
    title: "slope",
    opacity: 0.75,
    source: {
      type: "data-layer",
      dataSource: {
        type: "raster",
        workspaceId: "MyDatabaseWorkspaceIDSSR2",
        dataSourceName: "slope.tiff"
      }
    }
  }]
});

TableDataSource

A table or feature class that resides in a registered workspace (either a folder or geodatabase). In the case of a geodatabase, if versioned, use version to switch to an alternate geodatabase version.

Properties:
type String

This value is always table.

workspaceId String

The workspace where the table resides as defined in the ArcGIS Server Manager.

dataSourceName String

The name of the table in the registered workspace.

gdbVersion String

References the geodatabase version if multiple versions exist in the geodatabase.

See also:
Example:
var layer = new MapImageLayer({
   url: "https://sampleserver6.arcgisonline.com/arcgis/rest/services/USA/MapServer",
   sublayers: [{
     renderer: renderer,
     source: {
       type: "data-layer",
       dataSource: {
         type: "table",
         workspaceId: "MyDatabaseWorkspaceIDSSR2",
         dataSourceName: "ss6.gdb.Railroads"
       }
     }
   }]
 });

API Reference search results

NameTypeModule

There were no match results from your search criteria.