Pop-ups are often the single most important aspect of a web mapping application because they can enable interactivity with the map. A well-designed pop-up can be the difference between a good app and a great app. This article covers some of the subtle yet powerful capabilities of the pop-up that you can take advantage of as a developer.
Pop-Up Content Basics
These are two familiar approaches to creating pop-ups. At this point, many developers would consider their work on pop-ups done. However, you have even more options for tailoring pop-up content and experience. Basically, you can put anything you want inside a pop-up.
Many More Things to Do with Pop-Ups
Click a Button, Execute a Function
You can easily configure the pop-up to have one or more buttons that execute a function that you’ve created. These are called pop-up actions. You may have noticed the zoom-in button that is symbolized by a magnifying glass in the default pop-up. That is an action. When clicked, the map zooms in and centers on the selected feature.
You can add any number of custom actions to the pop-up and control how many are displayed before items are added to the menu accessed by the More Options icon (which is denoted by an ellipsis or “…”). This capability is most often used when you want the user to be able to do something with the selected feature.
For example, if you had a layer containing possible retail locations, you could have an action that, when clicked, calculates a 10-minute drive time around the selected feature and displays demographics for people who live within the drive-time polygon. You could also have a button to intersect the drive time polygon with another layer in the map. You decide exactly what happens when the user clicks on a custom action. Actions were created to give developers an easy way to integrate custom workflows into pop-ups.
Alternatives to the Default Pop-Up
As mentioned earlier, the PopupTemplate is used to display nicely formatted pop-up content. If you’d like to display formatted content somewhere in your application other than inside the pop-up, you can use the Feature widget, which renders information about a feature according to its PopupTemplate. The pop-up uses the Feature widget internally to display content and surrounds it with the pop-up UI (such as the docking control and pagination). The Feature widget can be placed in any container, on top of the map, or completely outside the map. This functionality is commonly used to display the feature’s information in a side panel next to the map or in a floating window that is visible when the user hovers over a feature.
If you need to display more than one pop-up at the same time, use multiple instances of the Feature widget, and a pop-up helper method. Rather than showing the information inside a pop-up, which automatically closes when another feature is clicked, it is shown in Feature widgets that are added to the UI. You can display multiple pop-ups next to a selected feature and provide a button for the user to explicitly close each pop-up. You will have to do a little plumbing to get this to work. You will need to set the pop-up’s autoOpenEnabled property to false and add a click listener on the view to get all features that were clicked.
You can get the features at a given screen location using the PopupViewModel’s fetchFeatures method. (The business logic that powers the pop-up is the PopupViewModel.) You might wonder why you wouldn’t just use the map view’s hitTest for this. There are two important distinctions with using fetchFeatures. First, you get all the features in all layers from the client and server rather than limiting features to layers that are already loaded on the client. Second, you get the features that have a pop-up enabled and a popupTemplate defined for you to use.
If you don’t want to show pop-up information at all, you can disable the pop-up by setting popupEnabled to false for a single layer or disable pop-ups for all layers using this syntax:
view.map.layers.forEach( layer => layer.popupEnabled = false );
Fine-Tuning the Experience
There are several configuration options related to the pop-up experience that can be easily overlooked but that you might like to try out.
Customize the feature highlight color. When the user clicks on features, what color would you like used for highlighting? You can customize the color by setting the highlightOptions for the map or scene view.
Remove parts of the pop-up. Using the visibleElements property, you can turn individual elements of the widget’s display on and off including the Close button and the navigation controls for cycling through selected features.
Control docking behavior. When a pop-up is dockEnabled, it means the pop-up no longer points to the selected feature or the location assigned to it. Rather, it is placed in one of the corners of the view or at the top or bottom of the view. Docking the pop-up provides a better user experience, particularly when opening pop-ups in apps on mobile devices. You can control various aspects of the docking behavior, including setting the breakpoint property to determine at what screen size the pop-up will be docked. You can also turn off docking completely if you don’t want your pop-up to switch to a docked position when the viewport is small.
You can change a handful of properties by overriding the pop-up’s CSS. An easy way to figure out what properties you want to change is to use the developer tools in the browser to inspect the CSS to see property settings and test out changes that you want to make.
If you need a scalable approach with more fine-grained control, you may want to consider working with the pop-up’s Sass file. [Sass, which stands for syntactically awesome stylesheet, is an extension to CSS.] This is the recommended approach for customizing CSS for a pop-up, as it provides a more robust option than manually overriding it. You can find the Sass file for the pop-up on the Esri repo on GitHub.
Where to Learn More