Map Module

The Map Module manages the map and map-related events.

Visual Feedback when Clicking a Map

A built-in default provides a visual cue to indicate where the user clicked in the map when no other tool is active.

The visual cue is a faint ripple effect, which is followed immediately by the appropriate map action for the clicked target. For example, when a user clicks a map feature. the ripple effect occurs, a pushpin appears on the target, the target in focus is highlighted in blue, and a map tip opens.

Ripple effect on a map (left image) followed by a pushpin and focus highlighting on the target (right image)

Configuration Properties

Module

panDuration: The length of time in milliseconds that the map takes to pan from one extent to another. The default is 350 milliseconds.
panRate: The length of time in milliseconds that the map takes to refresh as it pans to the next extent. The default is 50 milliseconds.
zoomDuration: The length of time in milliseconds that the map takes to zoom from one extent to another. The default is 500 milliseconds.
zoomRate: The length of time in milliseconds that the map takes to refresh as it zooms to the next extent. The default is 50 milliseconds.

panDuration, panRate, zoomDuration, and zoomRate are Esri map control properties.
longClickMilliseconds: The number of milliseconds the user must hold down the mouse button or finger on the touchscreen, before the commands specified in onLongClick execute. The default is 500.
maxExtentLogSize: The maximum number of map extent changes available when zooming to the previous or next extent. The default for the Desktop and Tablet interface is 100. The default for the Handheld interface is 50.
showLoadingStatus: When set to true, shows a Loading message while loading the map. The default is true.
loadingMessageTiming: An array of times in milliseconds to elapse before a stage 1, stage 2, and stage 3 "Still loading" messages display. The defaults are 1000 ms, 3000 ms, and 3000 ms respectively.
defaultPointFeatureZoomScales: An array of default zoom scales for point features. The default is an empty array.
behaviors: An array of named behaviors that run when an associated event occurs. By default, the behaviors are:
- MapOnClickBehavior: A behavior that runs an array of commands when the user quickly clicks on or touches the map. By default, this includes the command: InvokeMapTip.
- MapOnContextMenuBehavior: A behavior that runs an array of commands when the user right-clicks on the map. By default, this includes the ActivateMapContextMenu command.
- MapOnLongClickBehavior: A behavior that runs an array of commands when the user clicks on or touches the map for the amount of time specified by longClickMilliseconds. By default, this includes the ActivateMapContextMenu command.
- MapOnFeatureClickBehavior: A behavior that runs an array of commands, and works in conjunction with the MapTips module's webMapFeaturePresenter property to show map tips for features from web maps. If the site does not contain any references to web maps, this property has no effect. By default, this includes the ShowMapTip command.
  
  Modifying the MapOnFeatureClickBehavior property is an advanced task. We recommend that you use the default configuration for MapOnFeatureClickBehavior.
- MapTimeExtentChangedBehavior: A behavior that runs an array of commands when the map's time extent is changed. The default is an empty array.
You can remove or rearrange the commands of any behavior. You can also remove behaviors altogether.

You can add commands to a behavior if the command does not require a parameter, or if the type of the command's parameter matches the parameter of an existing command or the event associated with the behavior. Refer to "Viewer Commands and Events" in Developer Help to determine if the parameters are compatible. Note that private commands and events are not documented.

Adding a new behavior is only recommended for experienced developers.

See Viewer Commands and Events for more information.
menus: An array of menus used by the Map Module. By default, this includes a single menu: MapContextMenu. Each menu has the following properties:
- id: The menu's ID.
- defaultIconUri: The URI of the default icon for menu items.
- items: An array of menu items. Menu items have the following properties:
  - iconUri: The image to display beside the menu item. The recommended image size is 24px by 24px.
  - text: The text to appear on the menu item. You can use a text key or the literal text.
  - description: A brief description of the menu item to appear below the text. You can use a text key or the literal text.
  - command: The command to execute when the menu item is selected.
    
    If you set the command property, do not set the batch property.
  - commandParameter: The parameter value to pass to the command when it runs, if it has a parameter. Parameters may either be simple strings or complex objects containing any number of parameters.
    
    If you set the commandParameter property, do not set the batch property.
    
    In the following example from the MapContextMenu, a commandParameter is passed into the PanToPoint command to center the map on the point the user right-clicked or long-pressed:
```
"command": "PanToPoint",
"commandParameter": "{{context}}"
```
    The {{context}} token is a special token that retrieves the default menu context which a menu may have. For example, the default context of MapContextMenu is the Point the user right-clicked or long-pressed on the map. Therefore, the command centers the map to the point that the user right-clicked or long-pressed.
  - hideOnDisable: If this property is set to true and the menu item's command cannot run, the menu item does not show in the menu.
    
    If hideOnDisable is false and the menu item's command cannot run, the menu item shows in the menu, but it is grayed out.
  - batch: An array of objects, each with three properties: an executable command, an optional command parameter, and an optional Boolean to abort the execution of further commands if a command fails to execute. This allows multiple commands to be executed in a specified order, although some commands may trigger asynchronous actions.
    
    The following example attempts to activate the tabbed toolbar and, if successful, proceeds to greet the user with an alert:
```
"batch": [
    {
        "command": "ActivateView",
        "commandParameter": "TabbedToolbarView",
        "abortBatchOnFailure": true
    },
    {
        "command": "Alert",
        "commandParameter": "Hello!"
    }
]
```
    If omitted, abortBatchOnFailure is false by default.
    
    If you set the batch property, do not set the command or commandParameter properties.
tools: An array of tools related to working with the map. The factory configuration has tools to center the map, zoom in, and zoom out.

The Tools Module implements the ability to define an array of tools in other modules. Each tool in the array has the following properties:
- name: The name of the tool.
  
  If your viewer is going to be available in more than one language, enter the text key that the tool name is assigned to.
- command: The command that the tool runs.
  
  For a list of commands, see Viewer Commands and Events.
- drawMode: The type of geometry the user draws, upon which the tool operates.
- isSticky: When set to true, the tool remains selected after the user has used it. To deselect the tool, the user must click the tool a second time, or click a different tool. This allows the user to use a tool repeatedly without having to reselect it each time.
  
  If you do not want a tool to remain selected after it is used, set isSticky to false.
- iconUri: The image that displays beside the tool.
- statusText: The status message to display when the tool's input method is via mouse, often containing instructions for the user. You can use a text key or the literal text.
- keyboardStatusText: The status message to display when the tool's input method is via keyboard, often containing keyboard shortcut hints for the user. You can use a text key or the literal text.

Views

MapView:
- wrapAround180: When set to true, the map supports continuous pan across the date line. The default is false.
- disableMapKeyboardNavigation: Disables keyboard navigation for the map when set to true. The default value is false.
  
  When you choose to disable map keyboard navigation, note that your viewer is no longer compliant with the Web Content Accessibility Guidelines 2.0. Users who require the keyboard to navigate on the map may be unable to use your viewer. For additional information, see Accessibility.
- extentBroadcastFrequency: The frequency in milliseconds after which the MapExtentChanging event is published. The default is 20 ms.
- fitTiledMapsToExtent: If set to true, a map containing tiled map services is guaranteed to display the entirety of its initial extent. The default is false.
- showAttribution: If set to true, copyright information is displayed about the map if available. The default is true.
- minScale: The minimum scale at which the map is visible in viewers. For example, if the map's minimum scale is 1:5,000,000, you could extend the minimum scale to 1:10,000,000 in Essentials by setting minScale to 10000000. You can also configure this setting in Manager, on the viewer's Map page.
- maxScale: The maximum scale at which the map is visible in viewers. For example, if the map's maximum scale is 1:2,000, you could extend the maximum scale to 1:500 in Essentials by setting maxScale to 500. You can also configure this setting in Manager, on the viewer's Map page.
MapContextMenuView: No configuration properties

The MapContextMenuView has a title property that determines the panel title used for the map context menu in the Handheld interface.
ContextMenuReverseGeocodeView: No configuration properties
ContextMenuCoordinatesView: No configuration properties
ContextMenuMapMenuView:
- menuId: The ID of the menu to use in the map context menu. The default is MapContextMenu.

View Models

MapViewModel:
- stepZoomFactor: The factor by which the map zooms in or out when the user clicks the Zoom In map widget or the Zoom Out map widget . The Zoom In and Zoom Out map widgets are implemented by the ZoomControl Module.
  
  The value that you specify for stepZoomFactor is inversely proportional to the size of the step. To decrease the amount that the extent changes each time the user clicks the map widget, specify a larger value. To change the extent more with each step, specify a smaller value.
  
  The value must be between 0 and 1. The default value is 0.5.
  
  If you are using a tiled map service, make sure the step size is large enough to reach the next cached map scale with each click of the map widget—the HTML5 Viewer cannot show extents between two cached scales in a tiled map service.
MapContextMenuViewModel: No configuration properties
ContextMenuReverseGeocodeViewModel:
- showReverseGeocoder: To display the address of the point right-clicked or long-pressed, set to true. The default value is true.
ContextMenuCoordinatesViewModel:
- showCoordinates: To display the coordinates of the point right-clicked or long-pressed, set to true. The default value is true.
ContextMenuMapMenuViewModel:
- showMenu: To display the menu items of the Map Context Menu, set to true. The default value is true.
MapCoordinatesModel:
- defaultCoordinateDisplayTypes: An array of display formats to present coordinates. By default, the following are included:
  - dd: Decimal degrees.
  - ddm: Decimal degrees with minutes.
  - dms: Degrees, minutes, seconds.
  - xy: Native X and Y coordinates.
- customCoordinateSystems: An array of custom coordinate systems. By default, the array is empty.
- fractionalDigits: An integer that specifies the number of decimal places to display for coordinates. The default value is 5.
- defaultGcsWkid: The default Geographic Coordinate System to display. The default value is 4326.

Example - Add a Command with a Parameter to a Behavior

The following example demonstrates adding a new command with a parameter to the behavior MapOnFeatureClickBehavior.

To add a command with a parameter to a behavior:

Run an XML editor or text editor as an administrator.
Open one of the viewer configuration files, Desktop.json.js, Tablet.json.js, or Handheld.json.js, in the editor.

By default, the configuration files are here:

C:\Program Files (x86)\Latitude Geographics\Geocortex Essentials\[instance]\REST Elements\Sites\[site]\Viewers\[viewer]\VirtualDirectory\Resources\Config\Default\

In the Map module section, find the behaviors property. Locate the behavior you want to edit, for example, MapOnFeatureClickBehavior.

{
    "moduleName": "Map",
    ...
    "configuration": {
        ...
        "behaviors": [
            ...
            {   
                "name": "MapOnFeatureClickBehavior",
                "commands": [
                    "ShowMapTip"
                ]
            }
        ]
    },
    ...
}

The behavior executes a single command: ShowMapTip.

Refer to Viewer Commands and Events to determine the type of parameter that is associated with this command. ShowMapTip has a parameter of type, geocortex.essentialsHtmlViewer.mapping.infrastructure.Feature.
Find a command that you want to add to the behavior that has the same parameter type. For example, ZoomToFeature.
Add the desired command to the list of commands, separated by a comma. For example:
```
"commands": [
    "ShowMapTip",
    "ZoomToFeature"
]
```
Save the file.