map-init

This bundle provides a common configuration format for maps and a common place for the main map configuration. It also provides a way for other bundles to create own map widgets based on the same configuration format.

Usage

To configure a map, use the following properties:

• Basemaps
• Map (including layers)
• View (including constraints)

For a list of general properties that can be used in both basemaps and map configuration, see:

• Supported layer types
• Layer properties

The following code sample shows the default configuration structure of a map in the app.json file:

"map-init" : {
    "Config" : {
        "basemaps" : [...],
        "map" : {
            "ground": [...],
            "layers": [...],
            "tables": [...],
        },
        "view" : {
            "viewmode": "2D",
            "constraints": {...},
            "extent": {...}
        }
    }
}

The default map widget is registered at the component system with the widget role map.

Configuration reference

Basemaps

Basemaps can be configured by using either well known identifiers such as streets or satellite or specifying basemap objects that define layers similar to operational layers.

To define the basemap that is activated at the start of an app, use the parameter "selected": true.

The following code sample shows how to configure different types of basemaps:

"map-init": {
    "Config": {
        "basemaps": [
            {
                "id": "streets",
                "basemap": "streets-vector",
                "selected": true
            },
            {
                "id": "mapserver_tiled1",
                "basemap": {
                    "type": "AGS_TILED",
                    "url": "https://services.arcgisonline.com/arcgis/rest/services/Canvas/World_Light_Gray_Base/MapServer"
                }
            },
            {
                "id": "vectortile1",
                "basemap": {
                    "type": "AGS_VECTORTILE",
                    "url": "https://www.arcgis.com/sharing/rest/content/items/c11ce4f7801740b2905eb03ddc963ac8/resources/styles/root.json"
                }
            },
            {
                "id": "wms1",
                "basemap": {
                    "type": "WMS",
                    "url": "https://sgx.geodatenzentrum.de/wms_topplus_web_open",
                    "sublayers": [
                        {
                            "name": "web",
                            "title": "TopPlusOpen"
                        }
                    ]
                }
            },
            {
                "id": "wmts1",
                "basemap": {
                    "type": "WMTS",
                    "url": "https://sgx.geodatenzentrum.de/wmts_topplus_web_open"
                }
            }
        ],
        "map": {
            "layers": [...],
            "ground": [...]
        }
    }
}

If a basemap should have multiple layers it is possible to define them as an array:

"map-init": {
    "Config": {
        "basemaps": [
            {
                "id": "mybasemap",
                "basemap": [{
                    "type": "AGS_TILED",
                    "url": "https://services.arcgisonline.com/arcgis/rest/services/Canvas/World_Light_Gray_Base/MapServer"
                },{
                    "type": "AGS_VECTORTILE",
                    "url": "https://www.arcgis.com/sharing/rest/content/items/c11ce4f7801740b2905eb03ddc963ac8/resources/styles/root.json"
                }]
            }
        ],
        "map": {
            "layers": [...],
            "ground": [...]
        }
    }
}

For more information about the configuration options for each basemap in detail, see Layer properties.

Basemap thumbnails

Thumbnails are used by the bundles toc and basemaptoggler to display a small preview of a basemap. Thumbnails for Esri basemaps (such as streets or satellite) are set automatically.

To use thumbnails for custom basemaps or change the ones for Esri basemaps, set a thumbnail URL as shown in the following sample:

"map-init": {
    "Config": {
        "basemaps": [
            {
                "id": "esri_satellite",
                "basemap": "satellite",
                "thumbnailUrl": "resource('${app}:mythumbnail.png')"
            }
        ]
    }
}

Map

The map configuration can consist of a basemap, ground layers, operational layers and tables, as shown in the following code sample:

"map-init": {
    "Config": {
        "map": {
            "basemap": [...],
            "ground": [...],
            "layers": [...],
            "tables": [...],
        }
    }
}

"map-init": {
    "Config": {
        "map": {
            "basemap": [...],
            "ground": [...],
            "layers": [...]
        }
    }
}

Basemap

NOTE: Use this property only if you want to use exactly one base map in your map. To define multiple base maps that the user can switch between, see basemaps.

The following sample shows a minimal configuration to define a basemap:

"map-init": {
    "Config": {
        "map": {
            "basemap": "streets-vector"
        }
    }
}

Layers

The following code sample shows how to configure different types of layers:

"layers": [
    {
        "url": "https://services.conterra.de/arcgis/rest/services/common/grenzen/FeatureServer/2",
        "type": "AGS_FEATURE",
        "visible": true
    },
    {
        "url": "http://services.arcgisonline.com/arcgis/rest/services/World_Terrain_Base/MapServer",
        "type": "AGS_TILED"
    },
    {
        "id": "test",
        "title": "Grenzen",
        "type": "AGS_DYNAMIC",
        "url": "https://services.conterra.de/arcgis/rest/services/common/grenzen/MapServer",
        "visible": true,
        "sublayers": [
            {
                "id": 2
            },
            {
                "id": 3
            }
        ]
    },
    {
        "id": "ogcfeaturelayer",
        "url": "https://vtp2.geo-solutions.it/geoserver/ogc/features",
        "type": "OGC_FEATURE",
        "copyright": "vtp2.geo-solutions.it",
        "title": "OGCFeatureLayer",
        "collectionId": "ne:countries50m",
        "objectIdField": "NE_ID",
        "limit": 5000
    },
    {
        "type": "GROUP",
        "layers": [
            {
                "url": "https://sampleserver6.arcgisonline.com/arcgis/rest/services/USA/MapServer",
                "type": "AGS_DYNAMIC"
            },
            {
                "url": "https://sampleserver6.arcgisonline.com/arcgis/rest/services/Military/MapServer",
                "type": "AGS_DYNAMIC"
            }
        ]
    },
    {
        "id": "topplus2",
        "title": "WMS (TopPlus-Web-Open)",
        "type": "WMS",
        "url": "https://sgx.geodatenzentrum.de/wms_topplus_web_open",
        "sublayers": [
            {
                "name": "web",
                "title": "TopPlusOpen"
            }
        ]
    }
]

Adding formatting information to a layer

If a layer should be used with the AutoStoreRegistration to serve as source for a store, it is possible to add formatting information to control, how values of feature are displayed in a data table in the Result UI. The following configuration options may be used in the fieldConfig array:

"layers": [
    {
        "url": "https://services.conterra.de/arcgis/rest/services/common/grenzen/FeatureServer/2",
        "type": "AGS_FEATURE",
        "visible": true,
        "fieldConfig": [
            {
                "name": "expression/title",
                "title": "Title"
            },
            {
                "name": "year",
                "title": "other-alias",
                "dateFormat": "short-date",
                "digitSeparator": true,
                "places": 2
            }
        ],
        "expressionInfos": [
            {
                "name": "title",
                "expression": "`${$feature.name} (${$feature.hauptstadt})`"
            }
        ]
    }
]

NOTE: Please note that if you use fieldConfig to configure fields in the Result UI, only the fields that are configured in fieldConfig are displayed, all others are not displayed.

The sample is showing the definition of a virtual field by using a reference to an ArcGIS Arcade expression defined in the expressionInfos option.

For more details, see formatting options in the agssearch bundle.

Tables

The tables property defines which tables can be used in the map. Tables are configured in the same way as layers. Only feature layers can be used as tables (type AGS_FEATURE).

For example:

"tables": [
    {
        "url": "https://sampleserver6.arcgisonline.com/arcgis/rest/services/SF311/FeatureServer/1",
        "type": "AGS_FEATURE"
    }
]

Ground

Ground layers can be configured by using either well known identifiers such as world-elevation or specifying a service of type AGS_ELEVATION.

The following sample shows a minimal configuration to define a ground layer:

"ground": "world-elevation"

To define a custom ground layer, use the following syntax:

"ground": {
    "title": "MyGround",
    "layers": [{
        "url": "http://elevation3d.arcgis.com/arcgis/rest/services/WorldElevation3D/Terrain3D/ImageServer",
        "type": "AGS_ELEVATION"
    }]
}

To define multiple ground layers, use an array notation:

"ground": [
    {
        "url": "http://elevation3d.arcgis.com/arcgis/rest/services/WorldElevation3D/Terrain3D/ImageServer",
        "type": "AGS_ELEVATION"
    },
    {
        "url": "http://sampleserver6.arcgisonline.com/arcgis/rest/services/Elevation/MtBaldy_Elevation/ImageServer",
        "type": "AGS_ELEVATION"
    }
]

View

"map-init": {
    "Config": {
        "view": {
            "viewmode": "2D",
            "center": [
                10.138039,
                51.008837
            ],
            "scale": 12000000,
            "constraints": {
                "rotationEnabled": false
            }
        }
    }
}

extent

The extent represents the visible portion of a map within the view. When configured, this property overrides the center, scale, and zoom properties. This property is ignored if the viewpoint or camera are also configured.

"view": {
    "extent": {
        "xmin": 600000,
        "ymin": 5800000,
        "xmax": 1700000,
        "ymax": 7600000,
        "spatialReference": 3857
    }
}

center

Represents the view's center point. To set the center, configure a point object or a longitude/latitude pair (for example [long,lat]). This property is ignored if the camera, or extent properties are also configured.

"view": {
    "center": {
        "x": 12804.24,
        "y": -1894032.09,
        "spatialReference": 2027
    }
}

"view": {
    "center": [-112, 38]
}

scale

This property overrides the zoom property. This property is ignored if the camera or extent properties are also configured.

The following code sample sets the map scale in the view's center to 1:24,000:

"view": {
    "scale" : 24000
}

camera

This property overrides the extent, center, scale, and zoom properties. A camera position is composed by using the following properties:

The following code sample shows how to configure a complete camera view point:

"map-init": {
    "Config": {
        "view": {
            "viewmode": "3D",
            "camera": {
                "fov": 20,
                "heading": 120,
                "tilt": 65,
                "position": {
                    "x": 852169,
                    "y": 6787701,
                    "z": 208,
                    "spatialReference": {
                        "wkid": 3857
                    }
                }
            }
        }
    }
}

The following code sample shows how to define a view with a minimal configuration and alternative position composition [x,y,z]:

"map-init": {
    "Config": {
        "view": {
            "viewmode": "3D",
            "camera": {
                "position": [-117.646733, 34.288857, 5000]
            }
        }
    }
}

zoom

Represents the level of detail (LOD) at the center of the view.

The following code sample shows how to set the LOD to 18 (large map scale):

"view": {
    "zoom": 18
}

constraints

Represents the constraints of the view to restrict its behavior. The properties are compatible to the constraints of Esri's MapView and SceneView. All properties are optional.

The following code sample shows the configuration of all properties with sample values:

"view": {
    "constraints": {
        "minScale": 1000000,
        "maxScale": 10000,
        "lods": [
            {
                "level": 3,
                "resolution": 19567.87924099992,
                "scale": 73957190.948944
            },
            {
                "level": 4,
                "resolution": 9783.93962049996,
                "scale": 36978595.474472
            }
        ],
        "minZoom": 10,
        "maxZoom": 14,
        "snapToZoom": true,
        "geometry": {
            "type": "extent",
            "xmin": 753914,
            "ymin": 6590000,
            "xmax": 797273,
            "ymax": 6635000,
            "spatialReference": 3857
        },
        "rotationEnabled": true,
        "altitude": {
            "max": 10000,
            "min": 1000
        },
        "clipDistance": {
            "near": 100,
            "far": 100,
            "mode": "auto"
        },
        "tilt": {
            "max": 100,
            "mode": "auto"
        }
    }
}

navigation

Represents settings to control the view's navigation behavior when a user interacts with the browser. The properties are compatible with Esri's Navigation properties. All properties are optional.

"view": {
    "navigation": {
        "mouseWheelZoomEnabled": true,
        "browserTouchPanEnabled": true
    }
}

timeExtent

Controls visibility of temporal features when time aware layers are used in a map. Setting the time extent only shows features whose date falls into that extent.

This property is compatible with the timeExtent property on Esri's MapView and SceneView.

Specify dates in JavaScript compatible simplified ISO 8601 format:

"view": {
    "timeExtent": {
        "start": "2019-04-01T00:00Z",
        "end": "2019-10-06T00:00Z"
    }
}

Supported Layer Types

The following layer types are supported:

Layer Properties

When defining layers for basemap, ground and layers, you basically create instances of ArcGIS Maps SDK for JavaScript layers.

For every layer object specify a type as defined in the Supported Layer Types section. Inside the layer object definition you can use all properties that are available for the corresponding layer type of the ArcGIS Maps SDK for JavaScript with one limitation:

Typed properties can only be used if they support the autocasting feature of the Esri API.

Use Cases

Use different basemaps together with webmaps

To use multiple basemaps together with webmaps and for example allow to switch them with the basemaptoggler, only declare the property basemaps.

Optimize app startup performance

By default all layers are pre-loaded and initialized independent of their visibility state. If a configuration contains many layers that are invisible when the app started, the following options reduce the startup time of the app.

Delay the initialization of invisible layers

The following configuration delays the initialization of invisible layers for 2 seconds:

"map-init": {
    "Config": {
        // NOTE: this property can be omitted, default value is 'default'
        "initInvisibleLayerStrategy": "delayed",
        // NOTE: this property can be omitted, the default value is 5000 (5sec)
        "initInvisibleLayerStrategyDelay": 2000
    }
}

NOTE: The toc widget shows protected services to users having insufficient access rights during the configured delay.

Initialize a layer only when it becomes visible

The following configuration initializes a layer only when it becomes visible, for example by setting it visible in the toc widget.

"map-init": {
    "Config": {
        "initInvisibleLayerStrategy": "on-visible"
    }
}

NOTE: The toc widget shows protected services to users having insufficient access rights until the layer becomes visible.

Initialize the basemap prior all operational layers

By default the basemap and the operational layers are initialized together. To improve the startup time of the map, the basemap can be initialized with high priority. Operational layers are initialized after the basemap is ready and displayed.

The following configuration delays the initialization of operational layers for 2 seconds:

"map-init": {
    "Config": {
        "initBaseMapFirst": true,
        // NOTE: this property can be omitted, the default value is 1500 (1.5sec)
        "initBaseMapFirstDelay": 2000
    }
}

NOTE: This approach can only be used for basemaps configured directly in your app. Do not use this feature together with domain bundles.

Disable the sandbox attribute on IFrames for WMS layer popups

Some WMS services render complex HTML in popups. By default, the ArcGIS Maps SDK for JavaScript uses the sandbox attribute for the surrounding <iframe> that contains the contents of the popup for security reasons. This behavior disables many HTML features and may cause the popup to display incorrectly or not at all. map.apps provides an option that disables the "Sandbox" attribute for certain WMS layers:

"map-init": {
    "Config": {
        "map": {
            "layers": [
                {
                    "id": "<wms-layer-id>",
                    "url": "<WMS_URL>",
                    "type": "WMS",
                    "disableSandbox": true
                }
            ]
        },
    }
}

NOTE: Use the disableSandbox property only for trusted WMS services. The embedded HTML code can execute any JavaScript code, for example.

Provide a custom layer type factory

To provide a custom layer type factory, see the specific documentation of the map-config-api bundle.

Provide a custom map widget

To create a custom map widget and reuse the configuration format of this bundle, reference the configuration interpreter in your manifest.json file as in the following code sample:

{
    "name": "YourComponent",
    "references": [
        {
            "name": "interpreter",
            "providing": "map-init.Interpreter"
        }
    ]
}

The following code sample shows how to trigger the interpretation of a JSON configuration in your component:

// the map configuration
let config = {map: ..., view : ...};

// the map-init.Interpreter
let interpreter = this.interpreter;

// trigger interpretation
interpreter.interpret(config).toMapWidget()
    //a Promise is returned
    .then(({map,mapWidgetModel,mapWidget}) => {

        // do something with the created parts
        // by defining createWidget:false the mapWidget is not created.

    });

// if you are only interested into a MapWidgetModel
interpreter.interpret(config).toMapWidgetModel()

For more details, see the API documentation.