In usability we trust

Using InfoWindows is a brilliant way to display information about a certain location. Since they provides you with a space to put text or whatever HTML you please, they can be used in very interesting ways. In this article, which is the fourth in a series about Google Maps API 3, I will show you how to make good use of this great feature.

The InfoWindow object

The InfoWindow object will open an InfoWindow somewhere on a map. It looks like a speech bubble and the tip of its stem typically points to a certain object on the map. Often it’s pointing at a marker, but it doesn’t have to be. It can point at any other object or any coordinate on the map.

The object resides in the google.map.InfoWindow namespace and takes an optional argument which is options. Options is an object literal in which you can define all the properties for the InfoWindow. This means that you can create an empty InfoWindow object for later use, but most of the time you’ll probably want to fill it with some sort of content right away. To fill it with content you’ll need to use the property content. It can be set either on creation of the object or afterwards using the setContent() method. It can be either a text string, a string containing HTML, or a reference to an existing HTML node.

Setting the scene

We will start with a map with one marker on it. If you don’t know how to create a map and add markers to it, I suggest that you read the previous articles in this series first.

For those of you that are already familiar with the concepts, here’s the code for creating a map and adding a marker to it:

// Creating an option object for the map
var options = {
	zoom: 7,
	center: new google.maps.LatLng(56.83, 15.16),
	mapTypeId: google.maps.MapTypeId.ROADMAP
};
// Initializing the map
var map = new google.maps.Map(document.getElementById('map'), options);
// Creating a marker
var marker = new google.maps.Marker({
  position: new google.maps.LatLng(56.8848, 14.7730),
  map: map,
  title: 'My workplace'
});

This will result in a map that looks like this:

Adding an InfoWindow

Now that we have the scene set, lets add an InfoWindow to it. In this example we will instantly fill the InfoWindow with some content, in this case the classic text string “Hello world”:

// Creating an InfoWindow object
var infowindow = new google.maps.InfoWindow({
  content: 'Hello world'
});

Showing the InfoWindow

We have now created an InfoWindow object but not yet added it to the map. To make it appear we have to first open it and that’s done with its method open(). This method takes two arguments: the map object which it will be added to and optionally an anchor where it will point to. The anchor must be an object on the map that exposes a position property. As of now this will probably be a marker.

If you don’t pass on the second argument you must provide the InfoWindow object with a position. This is done with either the attribute position in options or via its setPosition() method. In this example however, we will pass our marker as the second argument so that the InfoWindow will point straight at it.

infowindow.open(map, marker);

Now the InfoWindow will be visible on the map and will look like this:

Note that the default behavior of the map is that it pans so that all of the InfoWindow is visible. This behavior can be overridden by setting the property disableAutoPan to false.

Adding a click event

As of now our InfoWindow is automatically opened when our map loads. Most of the time we want it to open when something is clicked and that’s exactly the functionality we’re going to add next. We’re going to add a click event to the marker so that when it’s being clicked the InfoWindow will open.

To add an event to the marker we will need to use the addListener() method found in google.maps.event. This method takes 3 arguments, the first one being the object it will be attached to, in this case the marker. The second argument defines what kind of event we want to add, in this case a click event. The third argument is a function which will be called when the event is being triggered. In this case we will use an anonymous function and we will move the code that opens the InfoWindow inside it.

Doing that the code will look like this:

google.maps.event.addListener(marker, 'click', function() {
  infowindow.open(map, marker);
});

Now, when we load our page the InfoWindow will not be visible until we click the marker. Then it will pop up.

Using multiple InfoWindows

You may have noticed that we create the InfoWindow outside the click event of the marker. Perhaps you’re thinking that we might as well could have put all of the code regarding the InfoWindow inside it. But there’s a good reason for not doing that. By creating the InfoWindow outside the event handler, we ensure that there only exists one InfoWindow at a time. If we had put the code for creating the InfoWindow inside the event handler we would have created a new InfoWindow each time the marker was clicked. Leaving us with several identical InfoWindows on top of each other.

Now there are ways to deal with this. We could for example check if the InfoWindow existed before creating it, but by creating it only once we completely avoid the problem all together.

If you’ve been programming in version 2 of the Google Maps API you’ll notice a significant difference here. In the old API we could only have one InfoWindow at a time, but now we can have several. Because of this we have to change how we think about them. There might be occasions when we want to display several of them at once, but often we will only want to display them one at a time.

More control over the Info Window

There are some other properties that you can add to options for added control of the InfoWindow. I’ve already mentioned content which defines what will be displayed inside of it and position which in lack of an anchor defines the position of the InfoWindow. But here’s all of the properties available for controlling the look and behavior of the InfoWindow:

content

This property defines the content of the InfoWindow. It can be either plain text, HTML or a reference to an existing HTML element. The InfoWindow will automatically adjust its size to fit the content.

disableAutoPan [boolean]

If set to true the map is no longer automatically panned to fit the InfoWindow. Default value is false.

maxWidth [number]

Sets the maximum width of the InfoWindow in pixels. It must be set before the InfoWindow is opened.

Another way of controlling the size of the InfoWindow is to add HTML with certain dimensions to it. This way you can control its size from you CSS.

pixelOffset [size]

If position is used to place the InfoWindow, pixelOffset defines how far away from this point the window should be positioned.

position [LatLng]

Defines the position the InfoWindow should be pointing at. If an anchor (the second argument of the open() method is set, it will override this property.

zIndex [number]

When displaying multiple InfoWindows at the same time, this property will determine the stack order of those.

Live demo

Check out the Live Demo showing the example used in this article.

Hopefully this article has provided you with a basic understanding of how to use InfoWindows in your maps but there are a lot more that can be done with them. They still lack a lot of the functionality found in the old API, like displaying a detail map inside it or having tabbed content. Some of these features will probably never find its way into the new API but fortunately it’s quite easy to build this functionality yourself. Keep your eyes open for my upcoming book where I will explain how to do some of this stuff.

Further reading

For more information about the InfoWindow object, check out the Official Google Maps Reference. You might also want to check out the section in the documentation about Overlays.

This article was published on Monday, September 21st, 2009 in Articles.