highlights

This bundle displays highlights on a map or scene view. Highlighted points, polygons or other geometries are created and destroyed on demand by the provided API.

Usage

Highlights are dynamically created graphics that are rendered on top of all other layers. You can use the functions of this bundle to add and remove highlights.

Highlights support all properties supported by esri/Graphic. For example, you can use the properties geometry, attributes, symbol, popupTemplate and maptipTemplate. Only the geometry property is required, all others are optional (for example default symbols are provided). When using popupTemplate or maptipTemplate, all required attributes must be transported in the attributes: { ... } property.

For a detailed description of the available capabilities, see the API documentation.

Constraints

When switching from 2D to 3D the 2D symbols are converted to 3D symbols if no 3D symbols are configured. However, when the app is started in 3D mode and only 2D symbols are configured, in 3D mode only the default symbols are displayed, because highlights created with a 3D symbol (see Highlighter.highlight) are only visible if the map's current viewmode is "3D".

Configuration Reference

The default symbols for highlights that do not specify custom symbols are taken from the bundle configuration and can be overwritten in apps. Symbols must contain all properties required by esri/Symbol and its derived classes:

The following sample shows all configurable properties and their default values:

"highlights": {
    "Config": {
        "point": {
            "type": "simple-marker",
            "color": [0, 255, 255, 0.25],
            "size": 16,
            "outline": {
                "color": [0, 255, 255, 1],
                "width": 2
            }
        },
        "polyline": {
            "type": "simple-line",
            "width": 1.3,
            "color": [0, 255, 255, 1]
        },
        "polygon": {
            "type": "simple-fill",
            "color": [0, 255, 255, 0.25],
            "style": "solid",
            "outline": {
                "color": [0, 255, 255, 1],
                "width": 2
            }
        },
        "point-3d": {
            "type": "simple-marker",
            "color": [0, 255, 255, 0.25],
            "size": 16,
            "outline": {
                "color": [0, 255, 255, 1],
                "width": 2
            }
        },
        "polyline-3d": {
            "type": "simple-line",
            "width": 1.3,
            "color": [0, 255, 255, 1]
        },
        "polygon-3d": {
            "type": "simple-fill",
            "color": [0, 255, 255, 0.25],
            "style": "solid",
            "outline": {
                "color": [0, 255, 255, 1],
                "width": 2
            }
        }
    }
}

Examples

Using the default HighlightService

The default highlight service operates on the default MapWidgetModel. You can obtain the instance by referencing "highlights.HighlightService" in your Component:

// manifest.json
// ...
"components": [
    {
        "name": "MyExampleComponent",
        "provides": "my-bundle.MyExampleComponent",
        "references": [
            {
                "name": "_highlighter",
                "providing": "highlights.HighlightService"
            }
        ]
    }
]
// ...

You can then use the Highlighter injected as _highlighter to create a point highlight:

// MyExampleComponent.js
export default class MyExampleComponent {
    deactivate() {
        // Remove the highlight when our component shuts down.
        this._clearHighlight();
    }

    highlightPoint() {
        // This example only creates one highlight at a time.
        // We store the current highlight object so that we can remove it again.
        // There is no restriction on the number of highlights you can create.
        this._clearHighlight();
        this._currentHighlight = this._highlighter.highlight({
            // For valid geometry properties, see
            // https://developers.arcgis.com/javascript/latest/api-reference/esri-geometry-Geometry.html
            geometry: {
                type: "point",
                longitude: 7.6261347,
                latitude: 51.9606649
            },
            maptipTemplate: {
                title: "Maptip",
                content: "This is a tooltip on a map. That makes this a maptip."
            }
        });
    }

    _clearHighlight() {
        if (this._currentHighlight) {
            this._currentHighlight.remove();
            this._currentHighlight = undefined;
        }
    }
}

Using the HighlighterFactory for custom MapWidgetModels

Reference the "highlights.HighlighterFactory" in your component:

// manifest.json
// ...
"components": [
    {
        "name": "MyExampleComponent",
        "provides": "my-bundle.MyExampleComponent",
        "references": [
            {
                "name": "_factory",
                "providing": "highlights.HighlighterFactory"
            }
        ]
    }
]
// ...

The Highlighter created using the HighlighterFactory operates on the custom MapWidgetModel:

// MyExampleComponent.js
export default class MyExampleComponent {
    activate() {
        const mapWidgetModel =
            /* obtained from somewhere */
            (this._highlighter = _factory.forMapWidgetModel(mapWidgetModel));
    }

    deactivate() {
        this._highlighter.destroy();
    }

    useHighlighter() {
        // Uses the custom highlighter.
        // Call highlight.remove() at some point to remove the graphic from the map.
        // See API documentation for supported arguments.
        const highlight = this._highlighter.highlight(...);
    }
}