ArcGIS API for JavaScript

Generate popup templates for data exploration

Version 4.16 of the ArcGIS API for JavaScript (ArcGIS JS API) quietly added a couple of methods for generating default popup templates based on a layer’s renderer.

These reside in the esri/smartMapping/popup/ namespace.

All you have to do is provide a layer, and the method will respond with one or more suggested popup templates that pair nicely with the layer’s renderer.

Design popups with purpose

You should always configure popups with purpose. Keep the end user in mind. What do they want to know about the data? How do they want it presented to them? The getTemplates methods should not be used as a lazy way to create a popup template for the sake of saving time.

In most development scenarios you are unlikely to need these methods at all. It’s far more advisable to consider the end user and design a popup from scratch, so you have full control over the content.

Furthermore, you are more likely to be familiar with the attributes available in the layer. If you know the layer’s data, you can easily create a popup template referencing the attributes of most interest to your users. See the snippet and map below for an example of creating a popup with a bar chart that compares three attributes.

layer.popupTemplate = {
  title: "{COUNTY}, {STATE}",
  content: [{
    type: "media",
    mediaInfos: [
      {
        type: "column-chart",
        title: "Number of households with one, two, or three registered vehicles",
        value: {
          fields: [
            "ONE_VEHICLE",
            "TWO_VEHICLES",
            "THREE_VEHICLES"
          ]
        }
      }
    ]
  }]
};
This map visualizes each census tract based on the most common number of vehicles in each household. The popup displays a column chart to compare the number of 1-vehicle households, 2-vehicle households, and 3-vehicle households.
This map visualizes each census tract based on the predominant number of vehicles in each household. The popup displays a column chart to compare the number of 1-vehicle households, 2-vehicle households, and 3-vehicle households.

Smart popup templates for data exploration

So why bother generating a default popup at all? The primary case is for data exploration apps. These apps may take an unfamiliar layer as input and generate a renderer based on parameters indicated by the user for the purpose of exploring the data.

That’s where the Smart Mapping APIs come into play. These APIs provide a series of helper functions that generate good default renderers based on field values (or expressions). These renderers use color schemes best suited for the map’s basemap and set break points at meaningful stops based on statistics returned from the layer.

The ArcGIS JS API documentation contains more than a dozen samples demonstrating how these Smart Mapping methods work. These methods also power the layer styling options in the ArcGIS Online map viewer.

The getTemplates methods can be used to generate popup templates that match the renderers generated in a Smart Mapping workflow.

Default popup templates

Alternatively, you could use the default popup template in data exploration apps.

The default popup template for a layer displays a scrollable table of all the attributes and values in the feature. This template can help developers familiarize themselves with the data, but it shouldn't be used for production apps.
The default popup template for a layer displays a scrollable table of all the attributes and values in the feature. This template can help developers familiarize themselves with the data, but it shouldn't be used for production apps.

But this overwhelms the user and doesn’t clearly describe the information the user is exploring. The default popup template is intended for developers as they get to know data for use in an application. It shouldn’t be presented in a production app for conveying information to an end user.

Generate better popup templates

The Smart Mapping APIs enable end users to ask a question about their data.

The resulting renderer will show spatial patterns that answer the user’s question about the layer as a whole. The popup answers these questions for an individual feature much better than a renderer, even with the aid of a legend.

For example, the following map answers the question, What is the temperature in the United States?

The renderer, or style of the layer, helps us see patterns for one or more attributes. In this map, we can clearly see a pattern of temperatures more than 100 degrees F in the southwest and midwest. However, the exact temperature is unknown.
In this map, we can clearly see a pattern of temperatures more than 100 degrees F in the southwest and midwest. However, the exact temperature of individual cities is not obvious. If you want to know the exact temperature of Indio, CA, all you know is that it is probably higher than 100 degrees F.

The renderer, or style, of the layer helps us see overall patterns where it is warm or cold. However, no matter the renderer type, whether it’s class breaks, graduated symbols, or continuous color, it is nearly impossible to know the exact value of a numeric attribute in a feature even with the help of a legend.

Instead of overwhelming the user with a default popup that requires them to dig for the answer to their question, you can use the getTemplates method to generate a minimalist popup template that gets to the point. Just provide a layer and the method does the rest of the work.

// Sets a suggested popupTemplate on the layer based on its renderer
popupTemplateCreator.getTemplates({
  layer: featureLayer
}).then(function(popupTemplateResponse){
  if ( popupTemplateResponse.primaryTemplate ){
    featureLayer.popupTemplate = popupTemplateResponse.primaryTemplate.value;
  }
}).catch(function(error){
  console.error(error);
});
The getTemplates method generates a popup that provides minimalist information about the data required for rendering the layer.
The getTemplates method generates a popup that provides minimalist information about the data required for rendering the layer. Now we can see the exact temperature for Indio, CA.

The resulting popup provides the exact value of a feature based on the renderer. Nothing more. Nothing less. That may be all your user needs in their data exploration workflow.

Multivariate styles

More complicated multivariate renderers may contain information from two or more fields or expressions. This is the case for renderers that have more than one visual variable, predominance renderer, dot density renderer, and relationship renderer.

The following sample from the ArcGIS JS API documentation uses the suggested default popup template for the predominance renderer as determined by the getTemplates method.

The suggested popup template for a layer with a predominance layer.

The template for predominance renderer provides a lot more information about each feature because the renderer requires more fields to answer the question, What is the most common decade in which homes were built in this area?

In fact, the getTemplates method returns multiple secondary popup templates for predominance renderer. The example below shows one with a pie chart.

A popup showing a secondary popup template with a pie chart that matches a predominance renderer.
// Sets a suggested popupTemplate on the layer based on its renderer
popupTemplateCreator.getTemplates({
  layer: featureLayer
}).then(function(popupTemplateResponse){

  // If available, applies a secondary template with a pie chart
  // The number of secondary templates depends on the input renderer
  // Sometimes none are returned
  featureLayer.popupTemplate = popupTemplateResponse.secondaryTemplates[5].value;

}).catch(function(error){
  console.error(error);
});

Generate popup templates for point clusters

You can define popup templates for clustered layers using the featureReduction.popupTemplate. This template allows you to present summary information about features in the cluster based on fields used in the layer’s renderer.

Just like the layer’s popup template, you can create this popup template from scratch with a limited set of aggregate fields determined by the layer’s renderer. Read the FeatureReductionCluster.popupTemplate documentation for more information about aggregate fields.

The esri/smartMapping/popup/clusters module, however, allows you to generate a good default template for any layer style where clustering is (or will be) enabled on a layer. Just generate the template and set the resulting template in layer.featureReduction.popupTemplate.

clusterPopupTemplateCreator.getTemplates({
  layer: featureLayer
}).then(function(popupTemplateResponse){
  const featureReduction = featureLayer.featureReduction.clone();
  featureReduction.popupTemplate = popupTemplateResponse.primaryTemplate.value;
  featureLayer.featureReduction = featureReduction;
}).catch(function(error){
  console.error(error);
});
The suggested popup template for a clustered layer with a UniqueValueRenderer. By default, this popup displays the feature count and the predominant value or type of features in the cluster.
The suggested popup template for a clustered layer with a UniqueValueRenderer. By default, this popup displays the feature count and the predominant value or type of features in the cluster.

Check out the Point clustering – generate suggested configuration sample in the ArcGIS JS API documentation to learn more about this workflow.

Final thoughts

As stated earlier, you should be considerate when defining your own popup content, just as you should make deliberate choices about styling the layer’s renderer. The popup template generators are only intended to either be a starting point to get to know the data in an unknown layer, or for generating popups for data exploration applications.

In most cases, you should allow the map author to create popups in the ArcGIS Online map viewer, or directly in the web app using JavaScript. If you need some inspiration, I suggest you browse the maps and layers from the Living Atlas. This site contains curated content with many examples of scenario-specific and informative popups.

The popup defined on the Current Weather and Wind Station Data layer in the Living Atlas. The Living Atlas contains hundreds of authoritative layers with popups already configured and ready to use in production web apps.
The popup defined on the Current Weather and Wind Station Data layer in the Living Atlas. The Living Atlas contains hundreds of authoritative layers with popups already configured and ready to use in production web apps.

About the author

Kristian Ekenes is a Product Engineer on the ArcGIS API for JavaScript team at Esri. His work focuses on mapping, visualization, and Arcade integration. Prior to joining Esri he worked as a GIS Specialist for an environmental consulting company. He enjoys cartography, GIS analysis, and building GIS applications for genealogy.

Connect:

Leave a Reply

Please Login to comment

Next Article

Easy as pie: Mapping large datasets in ArcGIS Insights, part 3

Read this article