Popup on a SymbolLayer

I want to have a simple text popup that is displayed when the mouse moves over a pin. The pin is a SymbolLayer. The popup needs to display 2 lines of text specific to the pin.

I know I can do this using MouseEnter & MouseLeave on the symbol. However, the SymbolLayerOptions.TextOptions leads me to believe there's a way to display text with a pin. Is there a way to have this text display when the mouse is over it?

And if not, what is the purpose of the TextOptions?

Solution

Generally, the TextOptions on the symbol layer is for rendering text on the map, like a label. A good example of doing this is when you want to put a number on top of an icon to help users cross reference points with a list. Symbols could be only text (icon disabled) and is what the map does to display labels for locations/roads. This text is rendered into the map via WebGL and thus, is not a popup. It is a commonly used feature but I haven't seen it used for your scenario. It is technically possible to use events to display this text on mouse hover but this is likely more work than needed and may not be the most performant as it would cause the map to re-render ever time the text is showed/hidden.

If you want to show a popup of the text on mouse hover, use a reusable popup and keep it simple. Here is a code sample for this scenario: https://samples.azuremaps.com/?sample=show-popup-on-hover

Summary code block of the sample here:

<!DOCTYPE html>
<html lang="en">
<head>
    <title></title>

    <meta charset="utf-8" />

    <!-- Add references to the Azure Maps Map control JavaScript and CSS files. -->
    <link href="https://atlas.microsoft.com/sdk/javascript/mapcontrol/3/atlas.min.css" rel="stylesheet" />
    <script src="https://atlas.microsoft.com/sdk/javascript/mapcontrol/3/atlas.min.js"></script>

    <script>
        var map, datasource, popup, symbolLayer;

        function GetMap() {
            //Initialize a map instance.
            map = new atlas.Map('myMap', {
                center: [-122.33, 47.63],
                zoom: 11,
                view: 'Auto',

                //Add authentication details for connecting to Azure Maps.
                authOptions: {
                    authType: 'subscriptionKey',
                    subscriptionKey: '[YOUR_AZURE_MAPS_KEY]'
                }
            });

            //Wait until the map resources are ready.
            map.events.add('ready', function () {

                //Create a data source and add it to the map.
                datasource = new atlas.source.DataSource();
                map.sources.add(datasource);

                //Create three point features on the map and add some metadata in the properties which we will want to display in a popup.
                datasource.add([
                    new atlas.data.Feature(new atlas.data.Point([-122.33, 47.6]), {
                        name: 'Point 1 Title',
                        description: 'This is the description 1.'
                    }),

                    new atlas.data.Feature(new atlas.data.Point([-122.335, 47.645]), {
                        name: 'Point 2 Title',
                        description: 'This is the description 2.'
                    }),

                    new atlas.data.Feature(new atlas.data.Point([-122.325, 47.635]), {
                        name: 'Point 3 Title',
                        description: 'This is the description 3.'
                    })
                ]);

                //Add a layer for rendering point data as symbols.
                symbolLayer = new atlas.layer.SymbolLayer(datasource, null, { iconOptions: {allowOverlap: true}});
                map.layers.add(symbolLayer);

                //Create a popup but leave it closed so we can update it and display it later.
                popup = new atlas.Popup({
                    position: [0, 0],
                    pixelOffset: [0, -18]
                });

                 //Close the popup when the mouse moves on the map.
                map.events.add('mousemove', closePopup);

                /**
                 * Open the popup on mouse move or touchstart on the symbol layer.
                 * Mouse move is used as mouseover only fires when the mouse initially goes over a symbol. 
                 * If two symbols overlap, moving the mouse from one to the other won't trigger the event for the new shape as the mouse is still over the layer.
                 */
                map.events.add('mousemove', symbolLayer, symbolHovered);
                map.events.add('touchstart', symbolLayer, symbolHovered);
            });
        }

        function closePopup() {
            popup.close();
        }
        
        function symbolHovered(e) {
            //Make sure the event occurred on a shape feature.
            if (e.shapes && e.shapes.length > 0) {
                var properties = e.shapes[0].getProperties();

                //Update the content and position of the popup.
                popup.setOptions({
                    //Create the content of the popup.
                    content: `<div style="padding:10px;"><b>${properties.name}</b><br/>${properties.description}</div>`,
                    position: e.shapes[0].getCoordinates(),
                    pixelOffset: [0, -18]
                });

                //Open the popup.
                popup.open(map);
            }
        }
    </script>
</head>
<body onload="GetMap()">
    <div id="myMap" style="position:relative;width:100%;height:600px;"></div>
</body>
</html>