Class: MapModel

MapModel()

The Map Model contains all of the settings and options for a required to render a map view.

Constructor

new MapModel()

Since:
  • 2.18.0
Source:

Extends

  • Backbone.Model

Members

defaults :object

Overrides the default Backbone.Model.defaults() function to specify default attributes for the Map
Type:
  • object
Properties:
Name Type Attributes Default Description
homePosition MapConfig#CameraPosition <optional>
 {longitude: -65, latitude: 56, height: 10000000, heading: 1, pitch: -90, roll: 0} A set of coordinates that give the (3D) starting point of the Viewer. This position is also where the "home" button in the Cesium viewer will navigate to when clicked.
terrains MapAssets <optional>
 new MapAssets() The terrain options to show in the map.
layers Array.<MapConfig#MapAssetConfig> Default layer configs, converted to a MapAssets collection during initialization. Ignored when layerCategories exist.
layerCategories AssetCategories <optional>
 new AssetCategories() A collection of layer categories to display in the tool bar. Categories will be displayed in the order they appear. The array of the AssetCategoryConfig are passed to a AssetCategories collection. When layerCategories exist, the layers property will be ignored.
showToolbar boolean <optional>
 true Whether or not to show the side bar with layer list and other tools. True by default.
showLayerList boolean <optional>
 true Whether or not to include the layer list in the toolbar. True by default.
showHomeButton boolean <optional>
 true Whether or not to show the home button in the toolbar. True by default.
showViewfinder boolean <optional>
 false Whether or not to show the viewfinder UI and viewfinder button in the toolbar. Defaults to false.
showShareUrl boolean <optional>
 false Whether or not to show the share as URL UI. Defaults to false.
toolbarOpen boolean <optional>
 false Whether or not the toolbar is open when the map is initialized. Set to false by default, so that the toolbar is hidden by default.
showScaleBar boolean <optional>
 true Whether or not to show a scale bar.
showFeatureInfo boolean <optional>
 true Whether or not to allow users to click on map features to show more information about them.
showDownloadPanel boolean <optional>
 false Whether or not to show users the panel that allows partial download of data. `showLayerList` must also be set to true.
clickFeatureAction string <optional>
 "showDetails" The default action to take when a user clicks on a feature on the map. The available options are "showDetails" (show the feature details in the sidebar) or "zoom" (zoom to the feature's location).
showNavHelp boolean <optional>
 true Whether or not to show navigation instructions in the toolbar.
showFeedback boolean <optional>
 false Whether or not to show a feedback section in the toolbar.
feedbackText string <optional>
 null The text to show in the feedback section.
globeBaseColor string <optional>
 null The base color of the globe when no layer is shown.
debug boolean <optional>
 false Enables Cesium's built-in map debugging aids and overlays for development.
show3DTilesInspector boolean <optional>
 false Whether or not to show Cesium's built-in 3D Tiles inspector widget.
featureRestoreTimeoutMs number <optional>
 15000 Maximum time to keep asynchronous feature-restore waiters active before canceling.
zoomPresets ZoomPresets <optional>
 @deprecated use ViewfinderCards instead.
viewfinderCards ViewfinderCards <optional>
 null A Backbone.Collection of a predefined list of locations with an enabled list of layer IDs, content to open in an embedded iframe, or links to external content to be shown in a new tab. Requires `showViewfinder` to be true as this UI appears within the ViewfinderView. Viewfinder Cards were generalized from zoom presets so this also accepts the legacy key `zoomPresets` for backward compatibility.
Source:

type :string

The type of model this is.
Type:
  • string
Since:
  • 2.25.0
Default Value:
  • "MapModel"
Source:

Methods

addAsset(asset) → {MapAsset}

Add a layer or other asset to the map. This is the best way to add a layer to the map because it will ensure that this map model is set on the layer model. If the map is using layer categories, the layer will be added to the first category.
Parameters:
Name Type Description
asset object | MapAsset A map asset model or object with attributes to set on a new map asset model.
Since:
  • 2.25.0
Source:
To Do:
  • Enable adding a terrain asset.
Returns:
The new layer model.
Type
MapAsset

applyFeatureRestoreState()

Open the feature info panel for any feature ids stored in restoreState. Called after other state is restored so the feature panel appears last. Searches all map layers for a matching feature and selects it directly without simulating a user click. If entities are not yet loaded, waits for each layer's status to become 'ready' before retrying.
Since:
  • 2.40.0
Source:

applyRestoreState()

Apply the restored URL destination as a navigation target.
Since:
  • 2.38.0
Source:

clearFeatureRestoreSession()

Cancel and clear any in-flight asynchronous feature restore waiters.
Since:
  • 2.40.0
Source:

clearSelectedFeaturesForLayer(layer) → {boolean}

Remove any currently selected features that belong to a given layer.
Parameters:
Name Type Description
layer MapAsset The layer being hidden.
Since:
  • 2.41.0
Source:
Returns:
True when at least one selected feature was removed.
Type
boolean

findFeature(featureId, layerIdopt) → {Object|null}

Find a feature by id, optionally scoped to a single layer id.
Parameters:
Name Type Attributes Description
featureId string Feature id to find.
layerId string <optional>
 Optional layer id to constrain search.
Since:
  • 2.40.0
Source:
Returns:
Matching feature result or null when not found.
Type
Object | null

flyHome()

Indicate that the map widget view should navigate to the home position.
Source:

getAllLayers() → {Array.<MapAsset>}

Source:
Returns:
A flat list of all layer models across all layer groups.
Type
Array.<MapAsset>

getEnabledLayerIdsForUrlState() → {Array.<string>}

Get enabled layer ids from live layer groups for URL state sync.
Since:
  • 2.38.0
Source:
Returns:
A normalized list of visible layer ids.
Type
Array.<string>

getLayerGroups() → {Array.<MapAssets>}

Source:
Returns:
When layerCategories are configured, each MapAssets represets layers from one category. When layerCategories doesn't exist, flat layers are used and the array includes exactly one MapAssets with all the layers. Returns an empty array if no layer are found.
Type
Array.<MapAssets>

getSelectedFeatureStateForUrlState() → {Array.<{featureId: string, layerId: (string|null)}>}

Get selected feature/layer entries from current map interaction state for URL sync.
Since:
  • 2.40.0
Source:
Returns:
Selected feature state entries.
Type
Array.<{featureId: string, layerId: (string|null)}>

getSelectedFeatures() → {Features}

Get the currently selected features on the map.
Since:
  • 2.27.0
Source:
Returns:
The selected Feature collection.
Type
Features

handleLayerGroupMutation()

Rebuild flattened layers after collection mutations and recalculate aggregate loading state.
Since:
  • 2.41.0
Source:

handleLayerLoadingStateChange()

Recalculate aggregate loading state when layer readiness metadata changes.
Since:
  • 2.41.0
Source:

handleLayerVisibilityChange(layer, visible)

Reconcile restore-session waiters when a layer is toggled. Hidden layers should not keep map loading state active.
Parameters:
Name Type Description
layer MapAsset The layer whose visibility changed.
visible boolean The layer's new visible value.
Since:
  • 2.41.0
Source:

handleShowShareUrlChange(_model, showShareUrl)

Re-apply restore state when share URL syncing is toggled on.
Parameters:
Name Type Description
_model MapModel The model that changed.
showShareUrl boolean Whether URL syncing is enabled.
Since:
  • 2.38.0
Source:

initialize(optionsopt)

Build layer collections and restore map state.
Parameters:
Name Type Attributes Description
options MapConfig | null <optional>
 Map config, or null to use defaults
Source:
Throws:
When a layer config contains a Backbone model
Type
Error

isValid() → {boolean}

Source:
Returns:
True if map is valid, otherwise false.
Type
boolean

moveAsset(asset, targetLayers, index) → {boolean}

Move a layer within its list or to another category.
Parameters:
Name Type Description
asset MapAsset An existing layer in this map
targetLayers MapAssets An existing layer collection in this map
index number The final zero-based position in the destination
Since:
  • 2.41.0
Source:
Returns:
Whether the layer moved
Type
boolean

refreshAllLayers() → {MapAssets}

Keep legacy allLayers attribute in sync for backward compatibility.
Since:
  • 2.38.0
Source:
Returns:
Flattened layer collection.
Type
MapAssets

removeAsset(asset)

Remove a layer from the map.
Parameters:
Name Type Description
asset MapAsset The layer model to remove from the map.
Since:
  • 2.27.0
Source:

resetLayerVisibility()

Reset the visibility of all layers to the value that was in the intial configuration.
Source:

resetLayers() → {MapAssets}

Restore the default layers in a new collection.
Since:
  • 2.25.0
Source:
Returns:
The new layers collection
Type
MapAssets

selectFeatures(features)

Select features on the map. Updates the selectedFeatures attribute on the MapInteraction model.
Parameters:
Name Type Description
features Array.<Feature> An array of Feature models to select. since 2.28.0
Source:

setUpInteractions() → {MapInteraction}

Set or replace the MapInteraction model on the map.
Since:
  • 2.27.0
Source:
Returns:
The new interactions model.
Type
MapInteraction

setUpLayerLoadingStateListeners()

Set up listeners that aggregate visible-layer and restore-session loading state.
Since:
  • 2.41.0
Source:

setUpUrlStateListeners()

Set up listeners that keep URL state in sync with the map model.
Since:
  • 2.38.0
Source:

shouldSyncUrlState() → {boolean}

Returns true when the map should sync URL state.
Since:
  • 2.38.0
Source:
Returns:
Whether URL sync is enabled.
Type
boolean

syncSelectedFeaturesToUrl()

Write the currently selected feature ids to the URL. Called when selectedFeatures changes. Managed independently from updateSearchParams so that camera/layer syncs cannot inadvertently clear the f param.
Since:
  • 2.40.0
Source:

toConfig() → {MapConfig}

Return the current map config for saving, for example, into a portal document.
Since:
  • 2.41.0
Source:
Returns:
A plain object of settings to save
Type
MapConfig

updateSearchParams()

Update the search parameters related to the current map position and visible layers.
Since:
  • 2.38.0
Source:

validate() → {object|null}

Validate the map model.
Source:
Returns:
Null if map is valid, otherwise errors keyed by attribute names.
Type
object | null

zoomTo(target)

Indicate that the map widget view should navigate to a given target. This is accomplished by setting the zoom target on the MapInteraction model. The map widget listens to this change and updates the camera position accordingly.
Parameters:
Name Type Description
target Feature | MapAsset | GeoBoundingBox | object The target to zoom to. See CesiumWidgetView#flyTo for more details on types of targets.
Source: