Working with info windows in the ArcGIS JavaScript API

An easy way to add interactivity to your ArcGIS JavaScript applications is through info windows that display information in response to a user action. From working with other APIs, you might know info windows as "balloons", "map tips", "callouts", or "popups". The concept is the same: the user clicks or hovers over a location on the map and sees HTML-based information about that particular location.

How does an info window work in the ArcGIS JavaScript API?

In the ArcGIS JavaScript API, the Map has an InfoWindow that can be shown or hidden in response to events.

Every info window has a title and content. The title is the bold text that appears at the top of the info window. The content is the HTML that appears below. When you work with info windows, you’ll frequently call methods to set the title and content.

The default event when a graphic is clicked is to show an info window. However, in order for this to happen, you need to have defined an InfoTemplate for the graphic. The InfoTemplate specifies the title and content that should be used in any info windows that result from clicking the graphics.

You can use the notation ${<FIELD>} to pull attributes directly into an info template.

var infoTemplate = new esri.InfoTemplate();
infoTemplate.setTitle("${NAME}");
infoTemplate.setContent("<b>2000 Population: </b>${POP2000}<br/>"
        + "<b>2000 Population per Sq. Mi.: </b>${POP00_SQMI}<br/>"
        + "<b>2007 Population: </b>${POP2007}<br/>"
        + "<b>2007 Population per Sq. Mi.: </b>${POP07_SQMI}");

This code would create an info window similar to what you see below.

You can handle a graphics layer’s onClick event yourself to show an info window. This can be useful if you need to use JavaScript in some way to construct what you put in the info window. The following function does some math to calculate the population density when a user clicks the graphics layer. The population density is then reported through an info window using the Map.infoWindow.setTitle() and Map.infoWindow.setContent() methods.

dojo.connect(myGraphicsLayer, "onClick", function(evt) {
  var graphicAttributes = evt.graphic.attributes;
  var title = graphicAttributes.NAME;
  var populationDensity = graphicAttributes.POP2007 / graphicAttributes.SQMI;
  var content = "The population density in 2007 is <i>" + populationDensity.toFixed(2); + "</i>.";
  map.infoWindow.setTitle(title);
  map.infoWindow.setContent(content);
  map.infoWindow.show(evt.screenPoint,map.getInfoWindowAnchor(evt.screenPoint));
});

These Map.infoWindow.setTitle() and Map.infoWindow.setContent methods are also handy if you want to show an info window in response to a query or some other action that doesn’t involve a graphic. Here’s a function designed to show an info window with lat/lon coordinates when the user clicks anywhere on the map.

dojo.connect(map, "onClick", addPoint);
function addPoint(evt) {
  map.infoWindow.setTitle("Coordinates");
  map.infoWindow.setContent("lat/lon : " + evt.mapPoint.y + ", " + evt.mapPoint.x);
  map.infoWindow.show(evt.screenPoint,map.getInfoWindowAnchor(evt.screenPoint));
}

What can you do with info windows?

You can put almost anything in an info window because it displays HTML. Images, hyperlinks, tables, dynamically rendered charts, and any other type of element that can be requested or created with HTML can be placed in an info window.

You can take advantage of Dojo libraries to enhance your info windows. This picture shows information organized in a Dojo TabContainer in the info window.

Here’s a chart dynamically constructed for an InfoWindow using the Dojo charting library:

Just because you can put something in an info window doesn’t always mean that you should. The BorderContainer and other elements in the Dojo layout libraries can help you organize information in sidebars, footers, and accordion containers on your page. (See this post for an introduction to Dojo layouts.) In some scenarios these might be more efficient than an info window.

The application pictured below avoids info windows in favor of a right-hand content pane containing charts and other information. Click the image if you're interested in downloading the code.

Designing a good info window

Although info windows can display all kinds of content, you should not use info windows as a "dumping ground" for information. A well-designed info window has:

• A descriptive title – Keep the title short and clear
• Formatting that is easy on the eyes - A few well-placed spaces, tabs, or line breaks can go a long way toward making the content easy to read.
• Clear labels for attributes - A non-GIS user looking at your application may not understand raw field names such as "PARCEL_NO". Instead, use clear descriptions or field aliases, such as "Parcel number". Avoid the ${*} shortcut that lists all field/value pairs.
• Attributes that are important to the end user – Many GIS datasets contain fields that are only of interest to a GIS analyst, not end users. "OBJECTID" is one example of a field that should probably never appear in a public-facing application.
• A manageable amount of information - Use tabs, sidebars, data grids, or links to other HTML pages if your info windows are getting too crowded and require the user to scroll.

Contributed by Sterling Quinn of the ArcGIS Server development team