Using the MarkerManager

The MarkerManager is a very useful Open Source Utility Library for Google Maps with the sole purpose to manage larger amounts of Markers. If you add markers with the MarkerManager you can control at which zoom-levels they will appear. And you can also hide and show them dynamically.

If you want to learn more about the MarkerManager and other libraries out there that deals with markers, read my article Handling Large Amounts of Markers in Google Maps.

Adding markers with the MarkerManager

Now the most effective way to add markers to the MarkerManager is to first add them to an array that you then add to the MarkerManager with the addMarkers() method. The code to do this would be something like this.

// Init the MarkerManager
var mgr = new MarkerManager();
//Defining the array that will contain all markers
var markers = [];
// Creating a marker
var marker = new GMarker(new GLatLng(57.8, 14.0));
// Add marker to the array
markers.push(marker);
// Add the array to the MarkerManager
mgr.addMarkers(markers, 1);
mgr.refresh();

Obviously it’s kind of useless to add only one marker this way. It would only be useful if you had at least a few of them, but I think you get the point.

Hiding and showing markers

In the Google Maps API there are two handy methods to toggle the visibility of markers. These are GMarker.show() and GMarker.hide(). They both work as expected, you call hide() and the markers disappears and then you call show() and the marker is displayed again.

So to hide all markers in this example you simply do this:

// Loop through all markers and hide each of them
for (var i = 0; i < markers.length; i++) {
  var marker = markers[i];
  marker.hide();
}

A bug

There is however one caveat and that is when you zoom the map the markers will magically appear again. This is an annoying bug that only appears when you use it on markers added with an utility library.

Click the image to enlarge

The solution

So far I've only found one solution for this and that is to extend the hide method and tweak the code to place the marker outside the map, thereby making it sort of invisible.

// Saving the position of the marker and then place it outside the map
GMarker.prototype.hide = function() {
  if (this.getPoint().lat() < 90) {
    try {
        this.savePoint = this.getPoint();
        this.setPoint(new GLatLng(90, 0));
    } catch (e) { }
  }
}

Subsequently you need to prototype the show method as well so that it moves the marker into the correct position again.

// Restoring the position of the marker
GMarker.prototype.show = function() {
  if (this.getPoint().lat() == 90) {
    if (this.savePoint) {
      try {
        this.setPoint(this.savePoint);
        this.savePoint = null;
      } catch (e) { }
    }
  }
}

It's a dirty solution I know, but so far it's the best solution I've found and it works really well.

Note: I haven't come up with this solution myself but haven't been able to find where I saw it. So if you know who did come up with it, please tell me so I can give credit where credit is due.

isHidden()

The Google Maps API also offers a method to determain if a marker is hidden or not, GMarker.isHidden(). If you want to be able to use that you have to prototype it as well.

GMarker.prototype.isHidden = function() {
  if (this.getPoint().lat() == 90) {
    return true;
  } else {
    return false;
  }
}

Live examples

Live examples of the bug and the solution

I've put together a few examples of different scenarios using this, so that you will see the problem as well as the solution to it.

• Using GMarker
• Using MarkerManager
• Using MarkerManager - fixed

Other libraries

There are several other libraries for dealing with markers out there, and in at least one of them, Clusterer, I've noticed the same bug as in MarkerManager. The fix proposed in this article will work just fine on that one as well and possibly on other libraries where you might also find this bug.

If you've encountered this problem in other libraries please let me know. It would also be interesting to see other, and possibly more elegant solutions to this problem.

My Google Maps book

If you found this article useful you might be interested in my book Beginning Google Maps API 3. It covers everything you need to know to create awesome maps on your web sites. Buy it on Amazon.com

In this article I will describe how to create it with the help of jQuery

The basics

The whole idea with this approach is to make the user aware that something has happened, or that an action has been performed. You want to make sure that the message gets across but at the same time you don’t want to annoy the user or get in his or hers way. One way to do this is to show a message across the screen that as soon as the user moves the mouse, clicks a mouse button or press a key on the keyboard fades away.

Watch the live demo

The HTML

The HTML is straightforward. Just insert this code somewhere in your HTML. Preferably at the top or the bottom of it. Just make sure it’s not inside a container with an absolute or relative position.

<div class="message">
    <p>This is a non-modal alert</p>
</div>

Give it some style

We will want the message to hover over the page. Therefor we want it to have an absolute position. By setting the width of the containing <div> to 60% and it’s left position to 20% it’s going to appear centered on the screen.

The other declarations are just for the visual appearance of the message.

.message {
    position: absolute;
    top: 145px;
    width: 60%;
    left: 20%;
    background: #ff9;
    border: 1px solid #fc0;
    font-size: 150%;
    padding: 15px 50px;
}
.message p {
    margin: 0;
    padding: 0 40px 0 20px;
    text-align: center;
}

The Javascript

The Javascript essentially checks if there’s a an element with the class message in the web page. If there is, it attaches a few events on it that when triggered, removes the message.

Notice that I use one() instead of bind() to attach the events. The reason being that once the event is triggered i doesn’t have to trigger again. With one(), jQuery automatically unbinds the event after it’s been triggered.

$(document).ready(function(e) {
    // Check if there's a message
    if($('.message').length) {
         // If mouse is clicked, moved or a key is pressed
         $(document).one('click mousemove keypress', function(e) {
            // Fade the message away after 500 ms
            $('.message').animate({ opacity: 1.0 }, 500).fadeOut();
        });
    }
});

Notice in the part where the alert is faded out, there’s first animate({ opacity: 1.0 }, 500). This is a hack to get a 500 ms long delay before the message starts to fade out. What it actually does is to change the opacity of the element to 1.0 over a timespan of 500 ms. But since the element already has the opacity 1.0 it just creates a 500 ms long delay before the fadeOut() part is executed.

This is all good and works well in most browsers except… you guessed it, Internet Explorer.

Extra tweaks for Internet Explorer

The problem in Internet Explorer is that the mousemove event triggers instantly even if you haven’t moved the mouse. Because of this we have to insert a short delay before the events are attached. In this example I’ve done it by moving the logic to remove the message to a function, removeMessage(), which I call from the setTimeout function. The second argument of setTimeout determains the delay in ms before removeMessage() is invoked.

$(document).ready(function(e) {
     // Check if there's a message
     if($('.message').length) {
         // the timeout is there to make things work properly in IE
         // If we have no timeout IE will trigger mousemove instantly
         setTimeout(removeMessage, 500);
    }
});
function removeMessage(){
    $(document).one('click mousemove keypress', function(e) {
        // Fade the message away after 500 ms
        $('.message').animate({ opacity: 1.0 }, 500).fadeOut();
    });
}

That’s it. Sadly the code is slightly less elegant, but at least i works in all browsers.

Check out the Live demo

Conclusion

I have found this solution to be an excellent way to tell the user what’s going on in an unobtrusive, but still obvious way. I hope that you’ll find it useful too. If you have a more elegant way of overcoming the problem with IE or other ideas on how to enhance this solution, don’t hesitate to tell me.

Checking if the page has subpages

I searched in vain for a method to determine if the current page has any subpages or not. I first assumed that there would be a has_subpages() method, but so far I haven’t found any. Lacking that, I came up with a very crude way of checking it. I explicitly had to try to fetch all the subpages with the function wp_list_pages() and then check if it returned anything. It’s not pretty but it works.

$children = wp_list_pages('&child_of='.$post->ID.'&echo=0');
if($children) {
    // This page has subpages
}

Checking if it’s a parent page or a subpage

The next thing I had to figure out was how to check i the current page is a parent page or a subpage. That’s done with the following code.

if(is_page() && $post->post_parent) {
    // This is a subpage
} else {
    // This a parent page
}

Fetching the submenu

Now I needed a way to fetch the subpages. This is done with the wp_list_pages() function. The tricky part about this is that there’s no way to get both the parent page and the subpages in the same call. So therefor we have to call the function twice. The call also looks a little different depending on if we’re on the parent page or on the subpage.

if(is_page() && $post->post_parent) {
    // This is a subpage
    $children = wp_list_pages("title_li=&include=".$post->post_parent ."&echo=0");
    $children .= wp_list_pages("title_li=&child_of=".$post->post_parent ."&echo=0");
} else if($has_subpages) {
    // This is a parent page that have subpages
    $children = wp_list_pages("title_li=&include=".$post->ID ."&echo=0");
    $children .= wp_list_pages("title_li=&child_of=".$post->ID ."&echo=0");
}

There are other ways of doing this, but the benefit of this approach is that we automatically get class="current_page_item" on the list-item that represents the page that we’re currently on. That’s handy if you want to style that item in any particular way.

Outputting the HTML

The last step is to output the actual HTML. I’ve chosen to output it as an unordered list.

<?php // Check to see if we have anything to output ?>
<?php if ($children) { ?>
<ul class="submenu">
    <?php echo $children; ?>
</ul>
<?php } ?>

Putting it all together

Now it’s time to put all the pieces together. Just put this code in your page template one of the pages in your template, like for example page.php or sidebar.php and you’re good to go. These pages are located in /wp-content/themes/your-theme/.

<?php
$has_subpages = false;
// Check to see if the current page has any subpages
$children = wp_list_pages('&child_of='.$post->ID.'&echo=0');
if($children) {
    $has_subpages = true;
}
// Reseting $children
$children = "";

// Fetching the right thing depending on if we're on a subpage or on a parent page (that has subpages)
if(is_page() && $post->post_parent) {
    // This is a subpage
    $children = wp_list_pages("title_li=&include=".$post->post_parent ."&echo=0");
    $children .= wp_list_pages("title_li=&child_of=".$post->post_parent ."&echo=0");
} else if($has_subpages) {
    // This is a parent page that have subpages
    $children = wp_list_pages("title_li=&include=".$post->ID ."&echo=0");
    $children .= wp_list_pages("title_li=&child_of=".$post->ID ."&echo=0");
}
?>
<?php // Check to see if we have anything to output ?>
<?php if ($children) { ?>
<ul class="submenu">
    <?php echo $children; ?>
</ul>
<?php } ?>

Conclusion

I think that WordPress is an absolutely awesome CMS/Blog engine, but it do lack some handy methods. Fortunately it’s almost always possible to create workarounds. I hope that you will find this useful in your own WordPress Template. Don’t hesitate to tell me if you have a smarter way of doing this.

In this article I will show you how to add different kinds of Info Windows that appear when you click on a marker.

Content

• Basic Info Window
• Info window with tabs
• Info Window containing a Mini map
• Maximizing the Info Window
• Options
• Conclusion and further resources

Basic Info Window

The key method for opening an info window when clicking a marker is GMarker.openInfoWindowHTML(). It takes two arguments, first the text that will appear in the Info Window and secondly an optional object literal containing options you might want to use to configure the Info Window. To learn more about the available options, see Options further down the page.

In the examples for this article you have to click a marker to open the window. This is done by using the GEvent.addListener() method. I will not describe exactly how it works in this article but if you’re unfamiliar with it you can read more about it in the official documentation.

// Init a new map
var map = new GMap2(document.getElementById('map'));
map.addControl(new GSmallMapControl());
map.setCenter(new GLatLng(56.87, 14.80), 11);
// Creating a new marker
var marker = new GMarker(new GLatLng(56.87, 14.80))
// Adding a click-event to the marker
GEvent.addListener(marker, 'click', function() {
  // When clicked, open an Info Window
  marker.openInfoWindowHtml('Some text');
});
// Add marker to map
map.addOverlay(marker);

This code will result in an ordinary map showing a marker which, when you click on it, pops up an Info Window.

Watch live demo

Info Window with Tabs

If you have a lot of information about each marker, more than you can fit inside a normal Info Window, you could use an Info Window with tabs. You simply define each tab as a GInfoWindowTab and add them to an array that you later on add to the marker using the openInfoWindowTabsHtml() method.

// Create an array that will hold the tabs
var tabs = [];
// Create tabs and add them to the array
tabs.push(new GInfoWindowTab('Tab 1', 'Content of tab 1'));
tabs.push(new GInfoWindowTab('Tab 2', 'Content of tab 2'));
// Add tabs to the InfowWindow
marker.openInfoWindowTabsHtml(tabs);

The result is a tabbed Info Window.

Watch Live Demo

Info Window containing a Mini map

The API features an easy method to open up a mini map over the area where the marker is located, showMapBlowup(opts?:GInfoWindowOptions). This method takes an object literal that have two possible parameters, InfoWindowOptions.zoomLevel and InfoWindowOptions.mapType. These lets you determine at what zoom-level the mini map should start and what map type it should show.

GEvent.addListener(marker, 'click', function() {
  // When clicked, open an Info Window with a min map in it
  marker.showMapBlowup();
});

You never thought it would be this easy to do this, did you?

Watch live demo

Maximizing the Info Window

If you have a lot of content to show in you Info Window it could be useful to let the user maximize it. This is easily done using the options maxContent and maxTitle. If you define these you will automatically get a maximize button in your window.

So to make this work just do like this.

marker.openInfoWindowHtml('Click the (+) to maximize me!', {
  maxTitle: 'Maximized Title',
  maxContent: 'Maximized content text.'
});

When you first click the marker an ordinary info window will pop up. When you click the plus sign (+) in it, it will maximize.

Watch live demo

Options

As I’ve mentioned earlier each of the methods that opens an Info Window takes an optional object literal with options. The properties you can use in it are defined in the GInfoWindowOptions class.

All properties doesn’t comply with all kinds of Info Window.

• selectedTab [number]
  Determines which tab should be selected when opening an Info Window. Starts with number 0.
• maxWidth [number]
  Sets the maximum width of the info window. Note: From my observations it seems that the minimum value for this is 249 pixels.
• noCloseOnClick [bool]
  Sets if the info window should be closed when clicking inside the map. Default value is true.
• onOpenFn [Function]
  A function that is called after the info window is opened and the content is displayed.
• onCloseFn [Function]
  A function that is called when the info window is closed.
• zoomLevel [number]
  Determines what zoom level an opened Mini Map should have. Only applicable with showMapBlowUp().
• mapType [GMapType]
  Determines what map type an opened Mini Map should have. Only applicable with showMapBlowUp().
• maxContent [string]
  Determines what content should be showed when an info window is maximized. It can be either an HTML string or an HTML DOM element.
• maxTitle [string]
  Sets the title for the window when it’s maximized. It can be either an HTML string or an HTML DOM element.
• pixelOffset [GSize]
  Specifies a number of pixels to move the info window away from the current GLatLng.

How to use them

The options are passed to the method in an Object Literal. Here’s an example of using the maxWidth property when opening a basic Info Window.

marker.openInfoWindowHtml('Some text', {maxWidth: '250'});

Conclusion and further resources

Info windows are a powerful way of displaying information about certain objects in a map. In this article I have showed you some of the basic ways to use the built in ones in Google Maps. I think you can go a long way with these techniques but if you have special needs there are third party extensions out there that you can use.

It’s beyond the scope of this article to describe how they work, but the first library to check out should be ExtInfoWindow, one of the open source utility libraries for Google Maps. You’ll find documentation and examples at Google Maps API Utility Library. Joe Monahan has also written some about it on the Google Maps API Blog in the article ExtInfoWindow 1.0: Ajax powered, CSS customization.

Mike William at Google Maps API Tutorial has described two other libraries in the tutorials Using the EWindow extension and Using the EBubble extension that also might be useful.

Happy coding!

My Google Maps book

If you found this article useful you might be interested in my book Beginning Google Maps API 3. It covers everything you need to know to create awesome maps on your web sites. Buy it on Amazon.com

Update [2009-05-06]:This article has been updated with the addition of the utility library MarkerClusterer. The test results in the end of the article and the test page has also been revised.

If you’re new to markers in Google Maps I recommend that you first read Basic operations with markers in Google Maps for an introduction on how to use them.

The Marker Manager – Keeps track of them

Your first option might be to use the MarkerManager since it’s an utility library provided by Google. Rather than adding each marker individually to the map using GMap2.addOverlay() you first add them to the MarkerManager. The MarkerManager keeps track of all your markers. By defining at which zoom-levels each marker should appear you can cluster the markers to reduce the amount being shown at a time.

The MarkerManager is initially a bit slower than just adding markers directly to the map but the added benefit is that you can have more control over them.

You add markers to the MarkerManager with addMarker(GMarker, minZoom, maxZoom?). This method takes three arguments, the first one being the marker you want to add. The two second arguments are optional but define at which zoom-levels the marker will be visible.

A simple example

// Create a new map
var map = new GMap2(document.getElementById('map'));
map.setCenter(new GLatLng(59.5, 14.0), 6);
// Create a new instance of the MarkerManager
var mgr = new MarkerManager(map);
// Create a new marker
var marker = new GMarker(new GLatLng(59.0, 13.80));
// Add marker to the MarkerManager
mgr.addMarker(marker);

Obviously there’s not much use adding a single marker to the MarkerManager, but if you have hundreds of them, this might be the way to go.

Bulk adding the markers

An even more efficient way of using the MarkerManager is to do a bulk add by first putting all your markers into an array and then add the array to the MarkerManager with the addMarkers(markerArray, minZoom, maxZoom?) method.

// Create a new instance of the MarkerManager
var mgr = new MarkerManager(map);
// Create marker array
var markers = [];
// Loop to create markers and adding them to the MarkerManager
for(var i = 0; i < 50; i += 0.1) {
    var marker = new GMarker(new GLatLng(59.0 + i, 13.80 + i));
    markers.push(marker);
}
// Add the array to the MarkerManager
mgr.addMarkers(markers);
// Refresh the MarkerManager to make the markers appear on the map
mgr.refresh();

Notice that you have to use mgr.refresh() after adding the marker array to it. That's not necessary when adding the markers one by one.

Additional methods

• removeMarker(marker)
  Removes a marker from the MarkerManager
• clearMarkers()
  Removes all markers.
• getMarkerCount(zoom)
  Returns the number of markers at a given zoom-level.

The MarkerManager is a utility library provided by Google. On the URL below you'll find the source code as well as the full documentation and examples.

Google Maps MarkerManager SVN

Marker Light - Markers on a diet

Pamela Fox at Google has made a sample app for what she calls MarkerLight, which render less complex markers, thus increasing performance. The trade-off is that it's really just an image on the map, you can't interact with it. If you don't have the need for interaction this is a really easy way to gain performance, the only difference from the ordinary way of doing it is that you create a MarkerLight instead of a GMarker.

On Pamelas post about MarkerLight she explains why this approach is faster:

The reason GMarker takes so long is that it's actually composed of many DOM elements - foreground, shadow, printable version, clickable area, etc.

If your purpose is visualization, then you can get away with just creating a GOverlay extension like MarkerLight that creates a div with a background URL (or background color, even better!).

- Pamela Fox

Here's how to use it:

map.addOverlay(new MarkerLight(latlng, {image: "red_dot.png"}));

red_dot.png in is the image used for the marker. It's a very small and simple one.

You can try performance with different numbers of markers on Pamelas test page.

Download markerlight.js

Using Marker Light in combination with MarkerManager

You can add the benefits of MarkerLight with the clustering capabilities of the MarkerManager. It's really easy, just combine the two:

mgr.addMarker(new MarkerLight(latlng, {image: "red_dot.png"}));

The reason you should do this is that you can display a different number of markers at different zoom levels. This way you can ensure that not too many markers are displayed at the same time.

Clusterer - Only show what you need

A different approach is to use ACME labs Clusterer. It's a third party library that offers a faster way of adding markers. It's released under the BSD license and is freely available.

It allows faster performance by doing two things.

• Only the markers currently visible actually get created.
• If too many markers would be visible, then they are grouped together into cluster markers.

This lets you have literally thousands of markers on a map while maintaining decent performance. My tests with this approach shows that it's significantly faster than the MarkerManager approach.

Here's how to use it:

// Create a Clusterer object
var clusterer = new Clusterer(map);
// Create marker
var marker = new GMarker(new GLatLng(57.8, 14.0));
// Add marker to the map
clusterer.AddMarker(marker, 'text to infobox');

To remove a marker from the map call clusterer.RemoveMarker(marker).

There's also a few methods to change the behavior of the marker.

• clusterer.SetIcon(GIcon)
  Changes the cluster icon
• clusterer.SetMaxVisibleMarkers(n)
  Sets the threshold marker count where clustering kicks in. Default value is 150.
• clusterer.SetMinMarkersPerCluster(n)
  Sets the minumum number of markers for a cluster. Default value is 5.
• clusterer.SetMaxLinesPerInfoBox(n)
  Sets the maximum number of lines in an info box. Default value is 10.

Download Clusterer2.js

ClusterMarker - Chunk 'em all up

ClusterMarker is a free Javascript library released under the GNU General Public License, that adds clustering capabilities to markers. The unique thing with this library is that it automatically detects markers that intersect each other and cluster these into a single cluster marker.

The images below illustrates how this works

Images by Martin Pearman

The constructor takes two arguments and looks like this:

var cluster = new ClusterMarker(map, options).

map is a reference to the map object and options is an object literal that can have these properties:

• clusterMarkerIcon [GIcon]

  Changes the default cluster marker icon to an icon of your choice.

• markers [array]
  An array with all the markers you want to pass to the ClusterMarker

Apart from these properties you can also use all the other properties of the class. Se the documentation for a complete list.

Here's how to add markers using the ClusterMarker with a minimum amount of code.

var markerArray = [];
// Insert code to fill the markerArray with markers...
// Creating a new cluster by adding the map and the markerarray
var cluster = new ClusterMarker(map, {markers: markerArray});
// Refreshing to show the added markers
cluster.refresh();

This code will insert the markers on the map and cluster them under one icon if they're close enough to each other. For more fine grained control of how it operates there are several methods and properties. For a detailed explanation of how the library works there's excellent documentation on the Clustermarker Project page.

MarkerClusterer - The new kid in town

This utility library is the newest of them all and wasn't around when I originally wrote this article. This library, which is written by Xiaoxi Wu and is part of the Google Maps Open Source Utility Library is easy to use and shows excellent performance.

Like some of the other libraries it reduces the number of visible markers by clustering them together making it easier to get an overview. Watch the image below to see how.

Image by Xiaoxi Wu

It's constructor takes three arguments, the first one being a reference to the map, the second one being an array of GMarkers and the third one being an object literal with options. Only the first one is required.

var markerCluster = new MarkerClusterer(map, markers, opts);

So to add a bunch of markers to the map having the default settings of the MarkerClusterer you do this:

var markers = [];
// Insert code to fill the markerArray with markers...
// Creating a new cluster by adding the map and the array of markers
var markerCluster = new MarkerClusterer(map, markers);

See the documentation for a full explanation of the library and it's capabilities. Also read MarkerClusterer: A Solution to the Too Many Markers Problem on the Google Geo Developer blog for more information.

Download markerclusterer.js

Compare performance

Compare the different techniques on the Test page

Inspired by Pamela Fox testpage for MarkerLight I've set up a test page of my own where you can test the performance of all the different approaches in this article.

The result

I ran a series of test with a few different browsers. In each test I added 500 markers using the different techniques. Between each test I refreshed the browsers. All tests were performed on a PC with a 3.60 GHz Pentium 4 HT processor and 2 Gb RAM running Windows XP.

Note: Since the addition of MarkerClusterer I've ran the tests again and updated the result grid. Some of the web browsers are newer than in the lats test run. See the old test results.

In this test Clusterer2 was the fastest technique of them all. Be aware however that this is not the entire truth since I've only been able to measure how long it takes before the markers are passed to the map, not the actual time until they are visible on the map. When taking this into consideration I find that MarkerClusterer is the fastest technique closely followed by ClusterMarker.

When it comes to browsers the fastest performance is marked with green and the worst performance is marked with red in the result grid. Not surprisingly Internet Explorer is the slowest of the lot. Google Chrome and Safari has the fastest overall performance with their blazing fast Javascript engine.

If you have an idea on how to improve this test to better measure the actual time until the markers are visible on the map, please share in the comments or contact me through the Contact page.

Conclusion

The techniques showed in this article are all fairly easy to implement and works well when you don't have an incredibly large amount of markers. For those occasions where none of these techniques suffice you will have to resort to more extreme measures, like creating a big overlay with all the markers, but that's beyond the scope of this article.

I hope that you'll find these techniques helpful. Happy coding!

My Google Maps book

If you found this article useful you might be interested in my book Beginning Google Maps API 3. It covers everything you need to know to create awesome maps on your web sites. Buy it on Amazon.com

Adding a marker

A marker is a type of overlay, just as it’s siblings polyline and polygon. To add a basic marker to a Google Map all you have to do is to define it with a coordinate of type GLatLng using the GMarker constructor.

// Init the map
var map = new GMap2(document.getElementById('map'));
map.addControl(new GSmallMapControl());
map.setCenter(new GLatLng(59.5, 14.0), 6);
// Create a marker
var marker = new GMarker(new GLatLng(59.0, 13.80))
// Add the marker to the map
map.addOverlay(marker);

This code will create a map and add a basic marker to it.

Making it draggable

To make the marker draggable is really easy. the GMarker constructor takes options in the form of an object literal as it’s second parameter. You simply add {draggable: true} after the coordinates.

var marker = new GMarker(new GLatLng(59.0, 13.80), {draggable: true});

Voila, the marker is now draggable. This is excellent for applications where you want the user to define places on a map.

Adding a Tooltip

Adding a tooltip is done the same way as making the marker draggable. It’s done using another option called title. It will create the same kind of tooltip that adding the attribute title to HTML-elements does.

var marker = new GMarker(new GLatLng(59.0, 13.80), {
    draggable: true,
    title: 'Drag me'
});

This code will produce a standard tooltip when putting the cursor over the marker.

There are a lot of other options you can add to a marker. For a full list check out the documentation.

Adding an Info Window

An InfoWindow is a great way to show more information about a location. It’s done by adding a click event to the marker with the help of the GEvent class. When the click event is triggered, the InfoWindow is opened using the method GMarker2.openInfoWindow().

// Adding a click event to the marker
GEvent.addListener(marker, "click", function() {
    marker.openInfoWindow('My InfoWindow');
});

The result is a standard GInfoWindow which open up when you click the marker. You can close it by either clicking the closing X in the upper right corner or by clicking somewhere in the map.

GMarker.openInfoWindow is the most basic variant of InfoWindows in the API and can only contain plain text. Other types can contain HTML and have tabs. For a full description of the other options available check out the Documentation.

Preventing InfoWindow offset

When using a combination of drag and drop and infowindow a weird thing can happen. It’s that the InfoWindow stay in the same place while the marker is moved.

To prevent this we have to make sure to close the InfoWindow when initiating the drag and drop operation. This is done by listening to the event with GEvent.addListener and close the window with GMap2.closeInfoWindow().

// Close InfoWindow at dragstart
GEvent.addListener(marker, 'dragstart', function() {
    map.closeInfoWindow();
});

Live example

I’ve put together a live example which contains all the techniques described in this article.

Watch the live example.

Conclusion

Markers is an effective way of displaying places on a map. It has a simple yet powerful set of methods to create interactivity. The techniques described here are just a few of all the things you can do, but I think they’ll provide a good starting point.

My Google Maps book

If you found this article useful you might be interested in my book Beginning Google Maps API 3. It covers everything you need to know to create awesome maps on your web sites. Buy it on Amazon.com

In this article I will show you how to make Google Maps degrade gracefully by providing a fallback for non-javascript users using the Google Static Maps API.

The map switch

The technique is simple. First you have a Google Static Map on your web page, which in fact is a static image. If Javascript is enabled, the static image is overwritten with a dynamic map.

A Static Google Map is simply an ordinary image, dynamically created at Google and displayed on your webpage. You decide how it will appear by passing arguments in the querystring of the image URL. A sample URL could look like this:

http://maps.google.com/staticmap?center=59.1,14.0&zoom=6&size=420x300&key=YOUR_KEY_HERE

This URL will generate a map that look like this:

From this example it’s quite easy to see the different arguments in the query string:

• center
  Defines the center of the map with a coordinate (x, y)
• zoom
  Sets the zoom-level (1-18)
• size
  Defines the size of the map in pixels (width x height)
• key
  Your Google Maps API key. Note that in the example URL the key is omitted. If you don’t already have one you can sign up for one for free.

The switch

This is easy as pie. Just do as normal. The only difference is that you put an image with the static map inside the <div> for the dynamic map. If the dynamic map is loaded it will automatically replace the content of the <div>.

The HTML will look like this:

<div id="map">
    <img src="http://maps.google.com/staticmap?center=59.1,14.0&zoom=6&size=420x300&key=YOUR_KEY_HERE" alt="" />
</div>

And the Javascript will look something like this:

window.onload = function(){
    if (GBrowserIsCompatible()) {
        // Init the map
        var map = new GMap2(document.getElementById('map'));
        map.setCenter(new GLatLng(59.5, 14.0), 6);
    }
}

And there you have it! A map that degrades gracefully if the user lacks Javascript support.

Note: To avoid that the switch appears as a flicker in the browser I recommend using a DOM-loader that executes after the DOM has been loaded. All major Javascript libraries like jQuery and Prototype has these.

Live example

I’ve constructed an example page to show the concept. In the example I also add markers to the map. To learn how to do this read the article Simple maps with the Google Static Maps API.

Try the live example

My Google Maps book

If you found this article useful you might be interested in my book Beginning Google Maps API 3. It covers everything you need to know to create awesome maps on your web sites. Buy it on Amazon.com

A basic map

The basic concept is to generate an image by adding a regular image tag <img> to the document and in the src attribute add an URL to Google that generates a map image. In the querystring of the URL you define how the map will appear.

Here’s a basic example:

<img src="http://maps.google.com/staticmap?center=59.1,14.0&zoom=6&size=420x300&key=YOUR_KEY_HERE" alt="" />

which will result in this image:

The parameters used in this example are:

• center
  Defines the center of the map with a coordinate (x, y)
• zoom
  Sets the zoom-level (1-18)
• size
  Defines the size of the map in pixels (width x height)
• key
  Your Google Maps API key. Note that in the example URL the key is omitted. If you don’t already have a key you can sign up for one for free.

Adding markers

The use of markers in the map is quite limited but you can put up to 50 markers on a map in 10 different colors and in 3 different sizes with an optional letter in it on the map. Naturally you can’t interact with them in any way since that requires Javascript.

The basic syntax is:

markers=markerDescriptor1|markerDescriptor2|markerDescriptor3|

Each marker is separated with a pipe character (|). It’s then defined with its coordinates and then with its characteristics: lat, lng, size|color|letter. The last parameter is the most cryptic one since the words are all crammed together. A normal sized red marker with the letter A in it will look like midreda (eg. mid red a).

This code will generate 3 markers with different characteristics. The first one will be a normal red marker with the letter A in it [midreda]. The second one will be small with the color green [smallgreen] and the last one will be really small and orange [tinyorange].

markers=59.0,13.8,midreda|59.35,15.60,smallgreen|59.73,13.12,tinyorange

The parameters in this example are:

• latitude
  The latitude of the markers position.
• longitude
  The longitude of the markers position.
• size
  Defines the size of the marker. Valid values are mid, small, tiny. If none is specified it defaults to mid.
• color
  The marker can have one of 10 different colors Valid colors are: black, brown, green, purple, yellow, blue, gray, orange, red, white. Default is red.
• alphanumeric-character
  An optional character can be placed inside medium sized markers [a-z] [0-9]. Note that small and tiny markers cannot contain a character.

No need for center or zoom

One cool thing with static maps is that if you have markers on it you don’t have to define the center of the map or the zoom-level. It’s automatically calculated for you so all markers will fit. You can of course override it by explicitly defining center and zoom.

Adding paths

A path is a line built up of 2 or more coordinates. To add a path to a static map you use path: with a set of parameters.

There’s two kinds of parameters. The first kind defines the visual look of the path and the second kind the coordinates.

The visual look of a path

There are three parameters for the visual look of a path:

• rgb
  This is a 24-bit hex color value determining the color of the path. For example rgb:0x0000ff. With this parameter you can’t control the opacity of the path which defaults to 50%
• rgba
  This is a 32-bit hex color value determining the color of the path. The last 2 characters sets the alpha channel. For example rgba:0x0000ffff
• weight
  Specifies the thickness of the path in pixels. For example weight:5

The coordinates

A path is made up of 2 or more coordinates. You can currently have up to 100 coordinates for each path. The coordinates are separated by a pipe character (|) like this: 59.0,13.8|59.2,13.9.

A red semi transparent path made up of 5 coordinates would for example look like this

path=rgb:0x0000ff,weight:5|59.0,13.8|59.2,13.9|59.0,13.0|59.5,13.0|58.1,12.8

Note that just like with the markers you don’t need to supply the map with center and zoom level when using a path. The map will automatically display in a way so that the entire path is visible.

Optional parameters

There’s some other things you can do with this API. Here’s some more optional parameters to play around with.

• format
  This paramater lets you determain which image format the returned map should be in. Valid values are: gif, jpg, jpg-baseline, png8, png32. Default value is gif.
• maptype
  Defines the maptype. Possible values are roadmap, satellite, terrain, hybrid, and mobile. The default value is roadmap
• span
  This defines the minimum size of the viewport expressed as a latitude, longitude. The API calculates the appropriate from the center point and the span. If zoom is defined span is ignored.
• frame
  Defines that the image should be framed with a 5px, 55% opacity blue border. Valid values are true or false.
• hl
  Sets the language to be used on tile labels. Not all tiles support different languages, on these the default language is used.
• sensor
  This parameter specifies if the application is using a sensor to determine the users location. Valid values are true or false.

For a full description of the Google Static Maps API, visit the API page at Google.

The Static Map Wizard

If you’re lazy you can use the Static Map Wizard to create the URL for you. It’s an excellent tool making it really easy to create a map with markers and polylines.

It’s done in four easy steps.

1. Find the place on the map you want to show. Draw polylines and insert markers into the map by dragging and dropping.
   
2. Define how you want the map, markers and paths to appear
   
3. Watch the generated image
   
4. Get the created URL
   

   http://maps.google.com/staticmap?center=37.400465,-122.073003&markers=37.404119,-122.061024,brown|37.391436,-122.053299,brown&path=rgba:0xff000099,weight:6|37.39561,-122.08952|37.39125,-122.07064|37.40025,-122.06188|37.40998,-122.10291|37.39561,-122.08952&path=rgba:0xff000099,weight:6|37.38947,-122.10686&zoom=13&size=300x300&key=YOUR_KEY_HERE

Note that you manually have to add your API key at the end of the URL.

Conclusion

The Google Static Maps API is naturally not a replacement for the full Google Maps API. But it can provide basic functionality when you either just want a really simple and lightweight map or when the user doesn’t have Javascript available.

My Google Maps book

If you found this article useful you might be interested in my book Beginning Google Maps API 3. It covers everything you need to know to create awesome maps on your web sites. Buy it on Amazon.com

This time around I think I’ve got all the details right. Well, if that’s not Kaizen, what is?

The old article

In the original article, Ultimate Site Logo, I described how to code a site logo to meet these needs:

• Search engine optimized
• Clickable
• Accessible
• Looks good
• Hover effect

If you haven’t already read it, this could be a good time to do so to fully grasp the concept. But if you feel confident enough, then by all means, do read on.

The semantic problem

In my first solution I suggested that <h1> would be an appropriate element to host the logo. Even though I already back then felt that a different element could be used, I personally was leaning more towards <h1>.

After reading up a little and listening to remarks from others I have now changed my mind. Especially after reading Chris Pearsons article The Definitive Guide to Semantic Web Markup for Blogs.

I now believe that <h1> should be reserved for the most prominent heading on each individual page. So for the front page, the logo (e.g. site name) might as well be the most prominent one, while on sub pages such as an article page, the articles title should be the most prominent one.

Therefor I now recommend using a div to hold the site logo. The code for this would be:

<div id="branding">
	<div id="logo"><a href="#"><span></span>In usability we trust</a></div>
</div>

Note: I haven’t actually implemented this technique on this site yet, but I will do so in an upcoming redesign. Still you can watch it in action on the example page for this article.

The flicker problem

In my last solution I changed the background-image of the <span> displaying the logo, when hovering over it. The problem with this is that if the hover-image wasn’t cashed, there would be an occasional flicker revealing the text underneath it, before the image was loaded. To solve this issue I now use CSS sprites instead.

A sprite is basically an image that contains several images, in this case two. The trick is to, with the help of CSS, just show a part of it at a time. By aligning the background-image to either the left or the right side of the <span>, a roll-over effect is created.

As you can see this image contains two version of the logo, one in normal state and one in hover-state. By making the container only half the width of the complete image, it’s easy to show the different versions by either aligning the background-image to the left or to the right side of the container.

The logo in it’s normal state, where only the left part of the image is visible in the containing <div> (the red area).

The logo in it’s hover state, where only the right part of the image is visible in the containing <div> (the red area).

The CSS to accomplish this is:

#logo span {
	background: url(../img/logo_sprite.png) left top no-repeat;
}
#logo a:hover span {
	background-position: right top;
}

It was actually a comment from r-doll on a different article of mine that made me realize that CSS-sprites would be the way to go in this solution too. Thanks a lot!

The (almost) complete CSS

I say almost complete because there is two additional Internet Explorer fixes, that is best put in a separate CSS-file only served to IE.

#logo {
	position: relative;
	margin: 0;
	width: 442px;
	height: 125px;
}
#logo a {
	position: absolute;
	width: 100%;
	height: 100%;
}
#logo span {
	position: absolute;
	z-index: 1;
	width: 100%;
	height: 100%;
	background: url(../img/logo_sprite.png) left top no-repeat;
}
#logo a:hover span {
	background-position: right top;
}

Note: For a full explanation of the CSS and the additional fixes needed for IE, read the old article, Ultimate Site Logo.

Further improvements

If you can think of further improvements I would be more than happy if you would share it with me.

One issue that I’m aware of is when printing the web page. The logo just shows if you have print background images turned on, otherwise the text underneath the logo will show. If you have a solution for this, please let me know!

The files

• Watch the live demo
• style.css [The main style sheet]
• ie.css [Style sheet fed to IE alone]

Please read about my first take in Using microformats to populate Google Map.

The demo is still in Swedish since I originally made it for a lecture here in Sweden about using Microformats. But despite that I think it’s fairly easy for all you non-swedes to follow the code.

Watch the live demo

So what have I done in this new version?

Updated the Google Maps code

In the old demo I used some deprecated Google Maps 1.0 methods. In the new demo these are replaced with Google Maps 2 methods.

GPoint is changed to GLatLng
GMap.centerAndZoom() is changed to GMap2.setCenter()

Switched Javascript Library

I have switched Javascript library from DOMAssistant to jQuery. Lately I’ve been working a lot with jQuery so it seemed like a natural switch.

Added a slider

I wanted to be able to easily filter the result by month using a slider. Since jQuery UI features a nice Slider I went with that.

Adding the slider was fairly easy. I used the default graphics and just tweaked the slider-background a little bit in Photoshop.

To put the slider in place all that is needed is to add a div with id="date_slider" to the HTML-document and the code below:

$('#date_slider').slider({
	handle: '.handle',
	steps: 3,
	min: 5,
	max: 8,
	startValue: 8,
	slide: function(e, ui) {
		// Changing the label to the selected monthname
		$('#selected_month').html(monthName(ui.value));
	},
	change: function(e, ui) {
		// filtering event list
		filterEventList(ui.value);

		// filtering markers on map
		filterMap(ui.value);
	}
});

Scrolling the list

When you click on a marker in the map the appropriate element in the sidebar list is highlighted. When the list is long enough to be scrollable it sometimes means that the highlighted item isn’t visible. I wanted a way to make the list scroll so the item came into view.

The jQuery plugin ScrollTo came to the rescue. It’s a really nice plugin that makes it easy to do just this. The syntax is: $(element).scrollTo(obj);

Where element is the list and obj is the selected item.

The files

If you want to try the demo and check out the files, please use the links below.

• View the Live Demo
• map.js
• style.css

My Google Maps book

If you found this article useful you might be interested in my book Beginning Google Maps API 3. It covers everything you need to know to create awesome maps on your web sites. Buy it on Amazon.com

Encoding polylines on the fly

When dealing with dynamic data you may have to encode the polylines on the fly. In this example I will use PHP to perform the encoding. I have rewritten a php script made by Jim Hribar and built his functions into a class for more convenient use. I’ve also made some small changes to the code. The code itself is essentially a rip-off from Mark MacClure’s Javascript class.

The PolylineEncoder Class

To use the class is simple. First you need to call the constructor of the class: $polylineEncoder = new PolylineEncoder($point);

The constructor

PolylineEncoder optionally takes four other arguments. When they are left out these default settings are used:

• numLevels = 18
• zoomFactor = 2
• verySmall = 0.00001
• forceEndpoints = true

numLevels and zoomFactor controls how many zoomlevels the encoding should take account for and in which intervals the map should change the number of displayed coordinates.

verySmall controls what distance between coordinate the algorithm should regard a short enough distance for a coordinate to be removed. So if you want to decrease the number of coordinates used, you should set the verySmall argument to a higher number.

forceEndpoints is a boolean and if set to true ensures that the two ending points of the polyline are displayed at all zoom-levels. I really don’t see a reason to set this to anything but true.

I myself tend to use the default settings since they provide a good result.

Encoding the points

The $encoded_polyline = polylineEncoder->dpEncode() method returns an associative array with the following keys.

• Points
  A string containing the encoded points
• Levels
  A string containing the encoded levels
• ZoomFactor
  The applied Zoom Factor (Same as passed to the constructor)
• NumLevels
  The applied NumLevels (Same as passed to the constructor)

A complete call to the EncodePolyline could look something like this.

// Include the file containing the class
include("PolylineEncoder.php");

// Create a nested array containing the coordinates
$points = array(
	array(
		59.6919,
		17.8582
	),
	array(
		59.3030,
		18.0395
	),
	array(
		58.9789,
		17.5341
	)
);

// Create a new instance of PolylineEncoder and supply the array
// as an argument to the constructor
$polylineEncoder = new PolylineEncoder($points);

// Encode the coordinates by calling dpEncode(), it returns an array containing the
// encoded coordinates and levels.
$encoded_points = $polylineEncoder->dpEncode();

// The resulting output
$encoded_points["Points"]; // "kqikJw|~kBr}jAclb@rh~@xuaB"
$encoded_points["Levels"]; // "PMP
$encoded_points["ZoomFactor"]; // 2
$encoded_points["NumLevels"]; // 18

Note: To learn more about how to use the optional settings for tweaking the encoded polyline, read A description of Google’s encoded polylines and The encoding algorithm for the levels string.

Download the class

The PolylineEncoder class is released under GPL MIT license and may be used and changed freely.

Download PolylineEncoder.php.txt

Making use of the encoded polyline

Now that we have an encoded polyline its time to make good use of it in Google Maps. To create a GPolyline from the encoded coordinates you use the method GPolyline.fromEncoded().

// Creating an encoded GPolyline
GPolyline.fromEncoded({
    color: string,
    weight: number,
    opacity: number,
    points: string,
    levels: string,
    numLevels: number,
    zoomFactor: number
});

As you can see it takes an object literal as an argument. The first three keys are purely for how the polyline will be styled. The keys points and levels are the ones that will be fed with the encoded polyline. The last two keys, numLevels and zoomFactor should match the settings you used when encoding the coordinates. If they don’t match, the polyline will not be rendered correctly.

Adding it to the map

So adding an encoded polyline to your map is very much like adding a normal polyline to it. The only difference is that instead of creating the polyline with the constructor of GPolyline(), you call the GPolyline.fromEncoded() method and pass the encoded points and levels to it.

// Instanciate a new map
var map = new GMap2(document.getElementById('map'));
map.setCenter(new GLatLng(59.3219, 17.6165), 8);

// Create the polyline from the encoded points
var polyline = GPolyline.fromEncoded({
    color: '#FF0000',
    weight: 6,
    opacity: 0.6,
    points: 'kqikJw|~kBr}jAclb@rh~@xuaB',
    levels: 'PMP',
    numLevels: 18,
    zoomFactor: 2
});

// Add the polyline to the map
map.addOverlay(polyline);

Watch the live example.

Even better performance

To get even better performance you have to use a pre-encode polyline to serve directly to the Javascript. This way you save the time the PHP-script takes to execute the encoding. In many cases this might not be possible, but if it is, it delivers the best performance.

Watch the pre-encoded example.

The improved load-time is pretty big. When I compare this example with the one encoding the polyline in the browser using Javascript, I get load times that’s range from 2 seconds (Safari) to over 20 seconds faster (IE).

All test scenarios

Here’s all the tested cases, from both this and the previous article.

• Simple unencoded polyline
• Complex unencoded polylines
• Complex encoded polylines, encoding done in browser with Javascript
• Complex encoded polylines, encoding done dynamically on server
• Complex pre-encoded polylines

Other resources

There are several server-side classes in different languages for encoding polylines, including Perl, Java and Ruby, available at Encoding polylines for Google Maps, a website by Mark McClure.

I have yet to find a class written in C#. If you find one or has written one yourself, I would be more than happy if you could tell me about it.

My Google Maps book

If you found this article useful you might be interested in my book Beginning Google Maps API 3. It covers everything you need to know to create awesome maps on your web sites. Buy it on Amazon.com

Let’s say that you have a number of markers on a map and you want the map to be displayed so that they all fit inside the viewport. You could of course experiment with center point and zoom levels to get it right. But what if the markers are put there dynamically so you don’t know beforehand where they’ll show up?

That’s where this trick will come in handy.

Using a Bounding Box

First you have to calculate the bounding box. That is, the coordinate for the south-west and north-east corners. In this case the coordinates for the marker that’s most south and the marker that’s most west provides the coordinates for the south-west corner. And vice versa for the north-east corner.

Now that you know the coordinates you just have to create a GLatLngBounds object, define it’s coordinates and serve it to GMap2.setCenter().

GLatLngBounds takes two optional arguments. A GLatLng for the south-west corner and a GLatLng for the north-east corner.

GMap2.getBoundsZoomLevel() calculates the appropriate zoom level to fit the bounding box in the available viewport. It also adds some extra padding around the box.

map = new GMap2(document.getElementById("map"));

// Define the two corners of the bounding box
var sw = new GLatLng(59.0, 13.12);
var ne = new GLatLng(60.35, 16.90);

// Create a bounding box
var bounds = new GLatLngBounds(sw, ne);

// Center map in the center of the bounding box
// and calculate the appropriate zoom level
map.setCenter(bounds.getCenter(), map.getBoundsZoomLevel(bounds));

Watch the live demo

I was shown this technique by my good friend Fredrik Jonsson, who writes about programming on freddes.se.

My Google Maps book

If you found this article useful you might be interested in my book Beginning Google Maps API 3. It covers everything you need to know to create awesome maps on your web sites. Buy it on Amazon.com

A basic polyline

Polylines consists of several points forming a line. Like for example a road on a map.

Normally you create a GPolyline and add it to the map using GMap2.addOverlay().

// Create an instance of Google map
var map = new GMap2(document.getElementById("map"));

// Tell the map where to start
map.setCenter(new GLatLng(59.3324, 17.8857), 9);

// Create an array with points
var points = [
   new GLatLng(59.6919, 17.8582),
   new GLatLng(59.3030, 18.0395),
   new GLatLng(58.9789, 17.5341)
];

// Create a new polyline
var polyline = new GPolyline(points, '#ff0000', 5, 0.7);

// Add the polyline to the map using map.addOverlay()
map.addOverlay(polyline);

As you can see GPolyline takes four arguments. The first one is the only required one, and it’s the coordinates for the polyline. The other ones are optional and are settings for how the polyline will appear. They are, from left to right, the color, the thickness and the opacity of the polyline.

Watch the small polyline example.

This works fine as long as the polyline doesn’t consist of too many coordinates. However when the polyline is more complex the rendering becomes really slow.

More complex polylines

Here’s an example of five polylines with a total of 7841 coordinates which are added to the map the same way as the previous example. You’ll notice that the performance is really starting to degrade. The load time is longer and when you zoom in or out on the map you’ll notice a significant delay.

Watch the complex polylines example (Warning: The loading time can be long)

The performance vary from browser to browser. So if you try the example with Internet Explorer it’s really slow, but with Safari or Google Chrome it’s still pretty fast.

Data format

In the example the coordinates are fetched through an AJAX call to a file containing the coordinates in JSON format. The data structure looks like this:

[{
    "Name":"Section 1",
    "Geom":[[59.1949,17.6596],[59.1942,17.6591],[59.1941,17.659]]
},
{
    "Name":"Section 2",
    "Geom":[[59.3819,18.0088],[59.3819,18.0089],[59.3818,18.0091]]
},

I only show three points per Section here but in the used file there a total of five Sections with thousands of points each.

Better performance

Decrease the number of coordinates

One easy way to make it faster is to try to limit the number of coordinates that you serve to the map. You gain some performance but loose accuracy, especially when you zoom in on the page.

Encoded polylines on the fly

A far better solution is to encode the polylines. It provides much better performance than just decreasing the number of coordinates plus you get better accuracy. The algorithm that encodes the coordinates removes some coordinates but more importantly decreases the number of coordinates when you zoom out, and increase them when zooming in.

Here’s how it’s done.

Instead of just feeding the map with coordinates you first encode them. An excellent encoder is Mark McClure’s PolylineEncoder class. It’s available from Encoding polylines for Google Maps. You can also download PolylineEncoder.js from there.

The encoder doesn’t make a very big difference on the loading time of the page, but when you start zooming and panning, the difference is huge.

Encoding the coordinates

Put all your coordinates in an array and feed it to dpEncodeToGPolyline() in the polylineEncoder class. The coordinates should be in the GLatLng format.

As you may notice dpEncodeToGPolyline() takes exactly the same arguments as GPolyline() and returns a GPolyline. So basically you just call dpEncodeToGPolyline() instead of GPolyline() and then add it to the map with addOverlay(), just like you did with the regular polyline.

// Create an array that will hold the coordinates
var points = [];

// Loop through the coordinates.
// In this case the coordinates are in a JSON object
for(var j = 0; j < json[i].Geom.length; j++) {
    var coords = json[i].Geom[j];
    //Convert the coordinates to GLatLng and insert into the array
    points.push(new GLatLng(parseFloat(coords[0]), parseFloat(coords[1])));
}

// Create a new instance of PolylineEncoder
var polylineEncoder = new PolylineEncoder();

// Assign the array to dpEncodeToGPolyline  to get an encoded polyline
var polyline = polylineEncoder.dpEncodeToGPolyline(points, '#ff0000', 5, 0.7);

// Add the returned polyline to the map with map.addOverlay()
map.addOverlay(polyline);

The performance boost with this technique is enormous. The loading time can still be quite long but interacting with the map is a totally different experience. Watch the encoded polylines example to see what I mean.

Encode polylines on the server

Loading time could still be too long, especially in Internet Explorer which has a a notoriously slow Javascript engine. To improve on that you should perform the encoding server side. In the second part of this article I describe how to do just that using PHP, to get dramatically shorter load-times.

Further reading

Mark MacClure, as I've already mentioned, has written a lot on the subject and also provides several examples, so don't miss checking Encoding polylines for Google Maps out.

Peter Chng has written an article about encoded polylines, Playing with Google Maps and encoded polylines, that helped clear a lot of my confusion.

My Google Maps book

If you found this article useful you might be interested in my book Beginning Google Maps API 3. It covers everything you need to know to create awesome maps on your web sites. Buy it on Amazon.com

In the ASP.NET MVC Framework, passing JSON from the server to the client script is almost too easy. In this article I will walk you through the code required to make it work.

The back end

Suppose we have a class named Cars like the one below. We want to feed our web page with a list of cars that we want to display AJAX style, preferably by sending the list as a JSON object.

public class Car {
	public string Name { get; set; }
	public string Color { get; set; }
}

With the ASP.NET MVC Framework it’s a breeze. In your Controller you simply create a method of the type JsonResult which returns a JSON object. You then use the Json() method to transform the class to JSON.

public class CarsController : Controller
{
	public JsonResult GetCars()
	{
		List<Car> cars = Cars.GetCars();
		return this.Json(cars);
	}
}

Calling this method will return JSON that looks something like this:

[{"Name":"Saab","Color":"Red"},{"Name":"Volvo","Color":"Blue"}]

Making the AJAX call

To get the list of cars on the client side, you want to make an AJAX call to the Controller method GetCars(). This is done by calling the URL /Cars/GetCars/.

First I’ll walk you through how to do it with pure Javascript. Then I’ll show you how to do it with the jQuery library.

The Classic Javascript way

First of all you have to create an instance of the XMLHttpRequest object. It’s through this object that you communicate with the back end. Since IE 6 doesn’t support this object but do have support for an ActiveX object that essentially does the same thing, we initially have to do some checking to make sure that we use the correct object. I’ve created a wrapper function that with the help of object detection determines which object to use and then returns it.

function getRequestObject() {
	var req = false;
	if(window.XMLHttpRequest) {
		req = new XMLHttpRequest();
	} else if(window.ActiveXObject) {
		req = new ActiveXObject("Microsoft.XMLHTTP");
	}
	return req;
}

I use the getRequestObject function to get the correct Request Object and then gets on with setting up the request.

var request = getRequestObject();
request.onreadystatechange = handleResponse;
request.open('GET', '/Cars/GetCars', true);
request.send(null);

Note: If you’re unfamiliar with AJAX and find this code really strange, I recommend that you read getting started with AJAX from Mozilla Developer Center.

Ok, so the AJAX Call is all set up. The last thing to do is to create the function handleResponse that takes care of the request and the received data.

function handleResponse() {
	if (request.readyState == 4) {
		var cars = eval('(' + request.responseText + ')');

		for each(car in cars) {
			alert(car.Name + ', ' + car.Color);
		}
	}
}

The object is received as JSON text through the responseText property of the request object. To convert it to a JSON object you can use the Eval() function. It will parse the text and produce an object structure. This is a fast and convenient way of doing it, but be aware of that it has potential security issues. Only use it if you know that you can trust the source. Otherwise you should use a more robust JSON parser.

The code in this example will throw an alert for each item in the JSON object and display it’s properties. This is done by looping through the received object. Notice how we can access the properties of the object through convenient dot notation.

The jQuery way

The client side scripting is even easier using jQuery. All the Javascript code above can be replaced with this.

$.getJSON("/Cars/GetCars", null, function(data) {
	$.each(data, function(index, car) {
		alert(car.Name, car.Color)
	});
});

jQuery handles everything that happens in the background, like instantiating the request object and parsing the received JSON object. So it does all the heavy lifting and leaves the fun stuff to you, like doing creative things with the received data.

Note: For brevity I have excluded all error handling in this example. This should naturally always be considered in a live application.

The problem

At first I coded each custom icon individually, creating massive amounts of code. I then had to have a huge If-else statement to determine which icon to use on each type of marker. This didn’t feel right and also made the application unnecessarily bloated and redundant, so I started looking for a better way of doing this. Eventually I stumbled upon this solution in one of Mike Williams excellent Google Maps tutorials.

The solution

The solution is all about storing the icons in an associative array that you later on call to get the correct icon.

Defining the icon

Start of by defining a “template”-icon that you base your other icons on.

var custIcon = new GIcon(G_DEFAULT_ICON);
custIcon.iconSize = new GSize(16, 16);
custIcon.shadowSize = new GSize(0, 0);
custIcon.iconAnchor = new GPoint(0, 0);

I’m using the optional copy argument in the GIcon constructor. You don’t have to do this but it’s convenient since all the properties of the icons are otherwise empty and you have to manually define them yourself.

Note: To learn more about how markers and icons works in Google Maps read the section on overlays in the Google Maps API documentation.

Creating the array

The next step is to define an array and start adding icons to it. Since it’s an associative array I use labels instead of numbers to identify each item.

Also notice that I add my template icon and a specific image for each individual icon in the GIcon constructor.

var myIcons = [];
myIcons['house'] = new GIcon(custIcon, 'house.png');
myIcons['castle'] = new GIcon(custIcon, 'castle.png');

Putting the array to use

Later on when you want to place a marker in the map and assign it one of your custom icons you just write this.

var marker = new GMarker(point, { icon: myIcons['house']});

In the application I’m currently building I give the array-items the same label as the type they represent. So instead of using a huge if-else statement to get the right icon, I just have to write one line of code where I insert my type as label for the array.

var marker = new GMarker(point, { icon: myIcons[type]});

Simple, effective and elegant!

My Google Maps book

If you found this article useful you might be interested in my book Beginning Google Maps API 3. It covers everything you need to know to create awesome maps on your web sites. Buy it on Amazon.com

Since Preview Release 5 of the ASP.NET MVC Framework, the handling of User Controls have changed a bit. The helper method RenderUserControl have been replace by RenderPartial. A little annoying thing when a User Control is imported into a View is a tiny difference in how it’s coded that is easily overlooked. So if you get this cryptic error:

CS1502: The best overloaded method match for ‘System.IO.TextWriter.Write(char)’ has some invalid arguments

It’s because you’ve been inserting the User Control with <%= RenderPartial("ViewName") %>, instead of <% RenderPartial("ViewName"); %>. (Note the equal sign before the method call and the semicolon after).

Passing a Data Object from the Controller to the View

Suppose you have a class called Car with the properties Make and Color, that you want to render using a User Control.

In order to pass data to the User Control, you first have to pass it from the Controller to the View. This is done by either sending the Data Object in the Return statement in a ActionResult method like this:

public ActionResult List() 
{
	List<Car> cars = cars.GetCars();
	return View(cars);
}

Or assign it explicitly to the ViewData object like this:

public ActionResult List() 
{
	List<Car> cars = cars.GetCars();
	ViewData["Cars"] = cars;

	return View();
}

I often find it more convenient to do it the first way, but when you have several data objects that you want to pass, you’ll have to use the second way too.

Passing DataObject to the User Control

Like I mentioned earlier in this article, the MVC Framework has a useful helper method for inserting User Control into Views. It’s called RenderPartial. Before the Preview Release 5 it was called RenderUserControl and was used a little different. So don’t confuse the two.

It’s used like this:

<% Html.RenderPartial("~/Views/Cars/List.ascx"); %>

To pass a list containing several instances of Car from the View to the User Control is easy. You just add it as the second parameter in the RenderPartial call like this:

<% Html.RenderPartial("~/Views/Cars/List.ascx", ViewDataModel); %>

or if you explicity assigned it to the ViewData object:

<% Html.RenderPartial("~/Views/Cars/List.ascx", ViewData["Cars"]); %>

Displaying the data in the User Control

In the User Control you have to first add a reference to the class Car in the CodeBehind. And since you want a list of it you have to use List<> around it:

public partial class List : System.Web.Mvc.ViewUserControl<List<Car>>
{
}

In the .ascx you then access the data by referencing to the ViewData.Model, just like you would in a View. So rendering a simple list of cars would look something like this:

<ul>
<% foreach(Car car in ViewData.Model) { %>
	<li><%= car.Make %>, <%= car.Color %></li>
<% } %>
</ul>

What’s up with the name?

I find it a little confusing that the Helper method is called RenderPartial when it’s actually a User Control that you render. Wouldn’t it be more logical to call the User Control, Partial View or something instead? Or have I missed something?

To read more about the ASP.NET MVC Framework and how to pass data objects, check out Scott Guthries excellent blog post, ASP.NET MVC Framework (Part 3): Passing ViewData from Controllers to Views. It’s on an older release but most of it still applies.

Happy coding!

In a recent project I was building a map where different regions of a map would highlight when you hover with the mouse over it. Using an imagemap in combination with CSS and Javascript seemed like the natural way to do it.

I thought that to actually code this solution would be pretty straightforward, but soon discovered some peculiar quirks. I also couldn’t find any information about this, so I thought that I’d share my experiences with you.

This is what I had in mind when I first started of.

• Use an image of a map.
• Make it into an imagemap and define the clickable areas.
• Do images of the different parts that is to be highlighted.
• Position them with absolute positioning.
• Use Javascript to show or hide them when the user hovers with the mouse over them.

The XHTML

I started of with a regular imagemap. (Some code is removed for brevity). I use a map over Scandinavia as the the image for the imagemap.

<div id="map">
  <img src="img/scandinavia.png" alt="" usemap="#scandinavia_map" />
  <map name="scandinavia_map" id="scandinavia_map">
    <area id="area_finland" shape="poly" coords="193,64,207,[...]" alt="Finland" href="finland.html" />
    <area id="area_sweden" shape="poly" coords="192,65,206,[...]" alt="Sweden" href="sweden.html" />
    <area id="area_norway" shape="poly" coords="187,64,194, [...]" alt="Norway" href="norway.html" />
  </map>
  <ul>
    <li id="finland"><a href="finland.html">Finland</a></li>
    <li id="norway"><a href="norway.html">Norway</a></li>
    <li id="sweden"><a href="sweden.html">Sweden</a></li>
  </ul>
</div>

As you can see I also made a list with links. This list serves a dual purpose. First of all I’m using the list items as hooks for the “highlight images”. But they also serves as a backup, in case the user doesn’t have CSS and images turned on.

The CSS

First of all I style the containing <div> with position: relative. This is necessary in order to later on position the different regions with absolute positioning. I’m also defining it’s width and height which is the same as the size of the map image.

#map {
  position: relative;
  width: 340px;
  height: 438px;
}

Then I style the unordered list. The important details here is to give the <li> an absolute positioning to be able to position them on the right spots, a text-indent so that the text won’t show and display: none to hide them. (They will later be displayed with the help of Javascript.)

#map ul {
  list-style: none;
}
#map li {
  position: absolute;
  z-index: 20;
  text-indent: -1000em;
  display: none;
}

Finally I style the different regions giving them the right image as a background, the right dimensions and the right position over the map. It can take some trial and error to get them in the right position. Temporarily set display: block while you position them.

Here are the images that I use as backgrounds on the elements I position over the map. (Well actually these are smaller version of the once I use)

#sweden {
  background: url(../img/sweden.png) no-repeat;
  width: 158px;
  height: 374px;
  top: 64px; 
  left: 80px;
}
#finland {
  background: url(../img/finland.png) no-repeat;
  width: 148px;
  height: 283px;
  top: 27px;
  right: 0;
}
#norway {
  background: url(../img/norway.png) no-repeat;
  width: 292px;
  height: 362px;
  top: 0;
  left: 0;
}

That sets the looks of the map. Now we just need some Javascript to make the rollover effects.

The Javascript

I use the DOM Assistant Javascript library to help with the DOM manipulation. If you prefer you can just as easily use jQuery, Prototype or any other similar Javascript library to do the same thing. Still, to use this example, be sure to include a reference to DOM Assistant in the head of the HTML document.

The script is pretty straightforward. What it basically does is that it loops through the list elements and assign mouseover, mouseout and click events to them. Review the comments in the code for a deeper explanation.

// When the DOM is loaded, initilize initPage
DOMAssistant.DOMReady(initPage);
function initPage() {
  // Get a reference to the containing div with id='map'
  var map = $$('map');
  // Check if map exists
  if (map) {
    // Get all the areas of the imagemap
    var country_list = map.getElementsByTagName('AREA');
    // Loop through all areas
    for (var i=0; i<country_list.length; i++) {
      $(country_list[i]).style.display = 'none';
      // Assign an action to the mouseover event
      $(country_list[i]).addEvent('mouseover', function(e) {
        // Get the id from the hovered area
        var country_id = this.id;
        // Extract the "country"-part of the id = the id of the list-item
        country_id = country_id.substring(country_id.indexOf('_')+1, country_id.length);

        // Set the <li> to "display: inline" = show it
        $$(country_id).setStyle('display', 'inline');
      });
      // Assign an action to the mouseout event
      $(country_list[i]).addEvent('mouseout', function(e)  {
        // Get the id from the hovered area
        var country_id = this.id;
        // Extract the "country"-part of the id = the id of the list-item
        country_id = country_id.substring(country_id.indexOf('_')+1, country_id.length);
        // Set the <li> to "display: none" = hide it
        $$(country_id).setStyle('display', 'none');
      });
      $(country_list[i]).addEvent('click', function(e) {
        var country_id = this.id;
        country_id = country_id.substring(country_id.indexOf('_')+1, country_id.length);
        alert('You clicked ' + country_id)
        DOMAssistant.preventDefault(e);
      });
    }
  }
}

This should do it one should think. But here’s where strange things starts to happen. The highlighted image flickers constantly as if the mouseOver and mouseOut events are triggered over and over again. Watch it in action.

Solution to the flicker problem

After some experimenting I came up with a solution where I use a transparent image as an overlay on the map image. I then assign the imagemap to the transparent image and voilà, the problem is solved.

<img src="img/transp.gif" id="transparent_map" alt="" usemap="#scandinavia_map" />

It’s important to give the transparent image the same dimensions as the image of the map.

#transparent_map {
  position: absolute;
  z-index: 30;
  width: 340px;
  height: 438px;
  border: none;
}

With that fix the map works just fine. View a live demo.

Accessibility

My conclusion is that this solution, if not perfect, is still pretty accessible. With CSS turned off, the list is visible and even though the map isn’t clickable you can click the links in the list. With Javascript turned off, the different parts of the map doesn’t highlight but they are still clickable.

For those who uses the keyboard to navigate, it’s still usable, but I haven’t been able to find a way to highlight an area when it’s “active”. If anyone has an idea of how to do this, please tell me.

I found one other weakness and a more serious that is. If you browse with images turned off and CSS enabled, neither the map nor the list of links is visible thus you can’t use it. If you have a solution to this, please let me know!

The files

• Download map.js
• Download map.css

Update [2009-05-04]: There’s now an example using jQuery available. Also check out the Javascript file: map_jquery.js.

Update [2010-02-27]: I’ve made a new example using jQuery and a fade effect.

Here’s a simple tip on how to loop through elements with jQuery that I thought I’d share.

An example

We start with a simple unordered list.

<ul id="my_list">
	<li>Item</li>
	<li>Item</li>
	<li>Item</li>
</ul>

What we want to do now is to change the color of each list item to red. With regular DOM scripting this would probably take a few lines of code but with jQuery we need just one.

$('#my_list li').css('color', 'red');

This would result in:

• Item
• Item
• Item

If you want to do something a little more fancy, like something different with each item, you have to write a little more code, but not much. First you have to grab the the list elements like in the previous example by using selectors. By using the each() method, you are then able to loop through each item. By assigning an anonymous function to each() you get access to every individual item by using $(this).

Notice that in the anonymous function there’s an attribute i. That’s the number of each item, just like in any normal array, starting from 0 and incrementing.

$('#my_list li').each(function(i) {
	$(this).append(i.toString());
});

The result is a list with the item number attached to the text inside the elements like this:

• Item0
• Item1
• Item2

The really cool thing about this is that each iteration has it’s own function scoop. If you ever tried to do this with regular DOM scripting and a standard for loop you’ve most likely ran into some kind of scoop problem when dynamically assigning values to an object. They all end up getting the same value. jQuery elegantly solves this and makes you’re coding life a little bit easier.

Pretty cool don’t you think? Happy coding!

In my opinion a good site logo have these characteristics:

• It’s search engine optimized
  Score high on Google
• It’s clickable
  Support the strong convention that a click on the site logo takes you to the homepage
• It’s accessible
  Enable those with screenreaders or images turned off to read the “logo”
• It looks good
  A good looking logo is important to build your brand.

If you’re the impatient kind you can watch the example page right away. For an explanation of how it’s done, read on!

The HTML

I’m taking a bottom-up approach to marking this up. That is, I start with some basic HTML to render a simple text link inside a <h1>. I then build upon this with the help of CSS, placing the logo image on top of the text. By doing this I enable all users, even those that use screen readers or have images disabled, to view the sitename while still letting those with able browsers to see the logo image instead.

This approach is often referred to as progressive enhancement and is an important concept when developing web sites according to web standards. The beauty of this approach is that it’s also an effective way to optimize the page for search engines.

To use <h1> or not

In my opinion <h1> is a suitable element for the site logo since it indicates that it’s the most important heading of the page. When search engines indexes pages they give more weight to text inside a <h1> than for example text inside <div> or <p>.

I know that some people disagrees with this and regards the <h1> reserved for the individual documents most prominent heading and not the web sites. However in my approach <h1> is used for the site name and <h2> is used for the documents most prominent heading. If you disagree with me, you can still use this approach by exchanging the <h1> for another element.

Adding a link

I also want the site logo to be clickable. This is one of the most wide spread conventions in web design, and most users expect the site logo to take them to the homepage when they click it. To accommodate this I make the heading a link which points to the homepage.

I have wrapped the <h1> inside a <div> with the id “branding”. Later in the CSS I will use this id as a hook for styling what’s inside.

To get this solution to work properly I’m also forced to use an extra set of <span> inside the <a>. I will use this later on to insert the logo image over the text. Even though I’m not very keen on adding extraneous HTML to the document, this seems like a small trade-off to get this to work properly.

<div id="branding">
	<h1><a href="/"><span></span>In usability we trust</a></h1>
</div>

At this point the site logo sure is accessible and SEO friendly but it doesn’t look very appealing. Soon we’re gonna change all that with some styling.

Styling it

I like to keep the HTML lean, therefor I want to have as few CSS selectors as possible. In this case I only have one, the id="branding" on the <div>. I use this hook in my CSS to access the header like this: #branding h1. What I tell the CSS is that I want to access the heading that’s inside the element with the id “branding”.

Styling the heading

I start off by giving the heading a relative position. The reason I’m doing this is that I want to position the containing elements using absolute positioning. Elements with an absolute position is positioned in relation to the nearest containing element with a relative position. If none is available it’s positioned relative to the browsers viewport. So in order to position the site logo inside the containing <div> I have to do assign it a relative position.

I then remove the margin from the heading and give it the same dimensions as my logo image so that it will fit nicely inside it.

#branding h1 {
	position: relative;
	margin: 0;
	width: 461px;
	height: 125px;
}

Styling the link

The next step is to style the link. I want the link to be invisible yet clickable. This is done by giving it an absolute position. This is so that I can stack the link and the <span> (which will contain the logo image) on each other using z-index. An element with an absolute position implicitly have a z-index of 0. Therefor I don’t have to explicitly define it in the CSS for the link since I want it to have z-index: 0;.

I also want to ensure that the link stretches the whole area so it’s possible to click anywhere at the logo and I therefor give it a width and height of 100%.

#branding h1 a {
	position: absolute;
	width: 100%;
	height: 100%;
}

Styling the <span>

The last step is to position the <span> on top of the link and display the logo image in it. This is done in three steps.

1. Give it an absolute position and a z-index of 1. Thereby placing it on top of the link.
2. Ensure that it covers the whole area by giving it a width and height of 100%.
3. Assign the logo image as the background. and also add a white background color so that the text doesn’t shine through before the images has loaded.

Edit: I’ve removed the background color because it prevented the text to display if the user have images turned off. The trade-off is that there can be an occasional flicker where the text shines through when hovering the first time if the hover-image hasn’t loaded yet.

#branding h1 span {
	position: absolute;
	z-index: 1;	
	width: 100%;
	height: 100%;
	background: url(img/logo.png) no-repeat;
}

Now the site logo looks a lot nicer. The ugly text is gone and is replaced with the site logo graphics. Still if you turn off the stylesheet you can read the heading and click it to enter the homepage.

Adding a Hover effect

To add some extra flare to the site logo and to provide the user with an additional hint that it’s clickable, you can add a hover effect. In this case it’s done by assigning the pseudo-class :hover to the link. When the user points at the logo the background image is altered.

#branding h1 a:hover span {
	background-image: url(img/logo_hover.png);
}

This is what it will look like when the user hovers with the cursor over it.

Tweaks to make it work in IE6 and IE7

It doesn’t come as a big suprise that Internet Explorer needs some special treatment in order for this to work properly. Frankly I wouldn’t have expected anything else!

A good practice is to place these “hacks” in a separate file and only feed it to IE using conditional comments. Conditional comments is a proprietary feature in IE that allow us to target specific versions of IE. All other browsers treat it just like any other HTML comment and ignores what’s inside it.

<!--[if lt IE 8]>
	<link rel="stylesheet" href="css/ie.css" type="text/css" media="all" />
<![endif]-->

This code snippet feeds the ie.css to versions of IE that is lower than 8 (lt stands for less than). If you just want to feed the file to IE6, just replace the 8 with a 7. More information on conditional comments.

Fixing the cursor

A problem that occurs in both IE 6 and 7 is that the cursor doesn’t change from an arrow to a hand when it hovers over the logo. That is easily fixed with this code snippet:

#branding h1 span {
	cursor: hand; 
}

Fixing the hover effect

If you added the hover effect you will need this tweak to get it to work properly in IE6. Otherwise you can just discard it.

The problem occurs when the user have hovered with the cursor over the logo and then remove it. For some reason the image doesn’t go back to it’s original state. I found that setting border: none on the link, makes the browser recognize that the cursor have been removed. I’m not sure why this is, but I suspect that it has something to do with the hasLayout property in IE6.

#branding h1 a:hover {
	border: none;
}

The only thing is that it now changes the height of the link to be lower than before, resulting in that only a part of the logo is visible. To fix this I had to define the height of the link in pixels instead of just as 100%.

#branding h1 a {
	height: 125px;
}

With those issues taken care of, it works fine in IE too.

Compability

I’ve tested the code in Firefox 2.5-3.0, Internet Explorer 5.5 SP2, 6.0 and 7.0, Opera 9.26 and Safari 3.1. All in Windows XP. The only weakness I’ve found so far is that “print background images” has to be turned on in the browser for the logo image to show in print-outs. Otherwise the text version is printed instead.

If you have a solution for this, spot other weaknesses or have other ideas of how to improve this. Please share!

• The example page
• style.css
• ie.css

Update: Since I wrote this article I have changed my mind regarding using <h1> as container for the site logo. I have also found other ways to further improve this solution. Read about it in Ultimate Site Logo 2 – For real this time.

If you’re building web sites you probably mark up contact information every now and then. Why not do it in a standardized ways so that you are able to quickly mark it up, style it and enhance it with microformats at the same time? The way to do this is by using hCard, a microformat for marking up contact information.

This article will not only show you why you should do this, but also exactly how!

hCard = vCard

Maybe you’ve heard of, or even used vCard before? It’s a widely adopted standard for dealing with contact info. Outlook and just about any other email application uses it, probably even your mobile phone. hCard is an HTML adaption of the vCard format.

By using hCard to mark up contact info you enable it for automatic processing. You could for example import it directly to an address application by using the Operator extension for Firefox. As of now you have to install an extension to be able to import microformat data, but as I understand it Firefox 3 will have native support for it.

Several search engines, including Google and Yahoo, has adopted microformats and this gives you the possibility to enable the search engines to more accurately find your content.

The basic markup

Let’s start by marking up a name, a phone number and an URL using standard XHTML.

<div>
	<h4>Gabriel Svennerberg</h4>
	<div>
		Tel: +46 470-76 40 50
	</div>
	<div>
		<a href="http://www.svennerberg.com/">www.svennerberg.com</a>
	</div>
</div>

As you can see there’s nothing fancy here. Just some basic XHTML. But now comes the interesting part: how to spice it up with microformats.

Note: In my examples I mainly use div and span to mark up the content but you could just as well use any other suitable (X)HTML element such as list- or table elements.

Enhance it with some sweet microformat magic

The next step is to enhance it with microformats. For starters we want to wrap the whole thing inside a tag marked with class="vcard". We do this to tell that this part of the web page is an hCard.

We also want to define what the name of the contact is, in this case by using class="fn" (formatted name). We also want to define the phone number by using class="tel" and the url by using class="url".

And this is how it’s done. You just use the class-attribute with predefined class names, and voilá, you got some microformat-enhanced content.

<div class="vcard">
	<h4 class="fn">Gabriel Svennerberg</h4>
	<div>
		Tel: <span class="tel">+46 470-76 40 50</span>
	</div>
	<div>
		<a class="url" href="http://www.svennerberg.com/">www.svennerberg.com</a>
	</div>
</div>

Display it with style

You can easily style the address information using the microformat classes as hooks. Here’s an example of some simple styling where I’ve used the vcard and the fn classes to style the content.

.vcard {
	margin: 1em 0;
	padding: 20px;
	border: 1px solid #dde;
	width: 15em;
	background: #f4f8fd;

}
.fn {
	margin: 0 0 .1em;
}

The result would look something like this.

Further enhancements

You could further enhance the content by giving it even more detailed specifications. You could for example define what part of the name that’s the first name and what part that’s the family name. This is accomplished by using class="given-name" and class="family-name".

You could also be more specific about the phone number by specifying what kind of phone number it is (e.g. work, home, etc.). This pattern is how you mark up several items of one particular type, like phone numbers. You then use class="type" to define the type of number and class="value" to define the actual number and wrap it all in a container with class="tel".

<div class="vcard">
	<h4 class="fn">
		<span class="given-name">Gabriel</span> 
		<span class="family-name">Svennerberg</span>
	</h4>
	<div class="tel">
		<span class="type">Home</span>:
		<span class="value">+46 470-76 40 50</span>
	</div>
	<div>
		<a class="url" href="http://www.svennerberg.com/">www.svennerberg.com</a>
	</div>
</div>

Adding more content

In this example I have added even more address information, like the street address, two different phone numbers and so on. By now I think you got the hang of it! You just use standard (X)HTML elements and classes to define the content.

<div class="vcard">
	<h4 class="fn">
		<span class="given-name">Gabriel</span> 
		<span class="family-name">Svennerberg</span>
	</h4>
	<div class="adr">
		<div class="street-address">Kasernv&auml;gen 9b</div>
		<div>
			<span class="postal-code">352 36</span> 
			<span class="locality">V&auml;xj&ouml;</span>
		</div>
		<div class="country-name">Sweden</div>
		<div class="tel">
			<span class="type">Home</span>:
			<span class="value">+46 470-76 40 50</span>
		</div>
		<div class="tel">
			<span class="type">Work</span>:
			<span class="value">+46 470-427 14</span>
		</div>
		<div>
			<a class="url" href="http://www.svennerberg.com/">www.svennerberg.com</a>
		</div>
	</div>
</div>

As you can see there are quite a few class names that you can use to semantically mark up your content. In fact there’s more. Here’s the complete list:

• fn, n (family-name, given-name, additional-name, honorific-prefix, honorific-suffix), nickname, sort-string
• url, email (type, value), tel (type, value)
• adr (post-office-box, extended-address, street-address, locality, region, postal-code, country-name, type, value), label
• geo (latitude, longitude), tz
• photo, logo, sound, bday
• title, role, org (organization-name, organisation-unit)
• category, note
• class, key, mailer, uid, rev

Class names inside parenthesis are subproperties of the preceding class name. Just like in the example with the telephone number; tel is the parent and type and value are the subproperties.

You might have noticed that there’s a class-name called geo in the list. Geo enables you to specify the geographic location of a contact by specifying coordinates. In my article, Using microformats to populate Google Map, I describe how to use microformats in combination with Javascript to populate a Google Map.

More resources

Sitepoint has an excellent article on microformats, Microformats—Plugging the Gaps In HTML
They’ve got separate sections about the different microformats such as hCard, hCalendar, hReview and so on, that’s really useful.

Microformats.org has a wiki with lots of information and examples of how to use microformats. They also have a page specifically dealing with hCard.

Unfortunately the demo is in Swedish, but I think those of you who doesn’t speak Swedish can easily understand it anyway.

The main concept is to use a list of folksong festivals in Scandinavia, carefully marked up with microformats, as a data source. I then use Javascript to loop through the content and populate the map.

I got the list of festivals from www.nordvisa.org. Thank you Chris!

Watch the demo in action

So what’s the big deal?

The advantage of this is that you can handle all events marked up with microformats the same way. It’s a standardized way of telling what is what. It means that you could for example build a script that automatically collects data from different sources (e.g. different web sites) and then display them all in the same place. If you find a new source to collect data from you just hook it up as well and you’re good to go.

On microformats.org they describe it like this:

Designed for humans first and machines second, microformats are a set of simple, open data formats built upon existing and widely adopted standards.

It’s basically a way to give more meaning to content. If for example you mark up your contact info with the microformat hCard. It can easily be imported to address books and other services.

Marking up the content

To mark up content with microformats you use the attribute: class on an HTML element. If you for example want to mark up your home phone number you can do it like this:

<div class="tel">
	<span class="type">home</span>:
	<span class="value">+1.415.555.1212</span>
</div>

This way not only humans can see that that’s your home phone number but computers can interpret it as well.

In this demo I’ve used the microformat hCalendar to mark up events. To mark up a block of information as an event using the hCard standard you use the class vevent on the container, in this case the list element <li>.

This is how I marked up the title and the dates of an event:

<li class="vevent">
	<h3 class="summary">Vømmelfestivalen</h3>
	<p>
		<abbr class="dtstart" title="2008-05-29">29 Maj</abbr> —
		<abbr class="dtend" title="2008-06-01">31 Maj</abbr>
	</p>
</li>

Note that in this case I use class="dtstart" attribute to tell what kind of information it is, in this case the start date of the event. Then I use the attribute title="2008-05-29" to tell the date in a standardized, machine readable way.

To mark up geographical data there’s a class called geo and there’s also classes to mark up the coordinates: latitude and longitude. I use these classes so that I later on can extract the events position using Javascript.

<p class="geo">
	GEO: <span class="latitude">63.798256</span>,
	<span class="longitude">11.494446</span>
</p>

Are you starting to get a hang of it? Microformats isn’t hard to use. It’s all about using the same HTML that you always use with the difference that you use certain class names to describe the content.

The Javascript

I use the classes in the markup as hooks to extract the data and put it in the map. As an added bonus I can also use the classes to style the visual appearance of the content.

In map.js the script loops through the different events (class="vevent") and look for information about them. It then uses this information to put a marker in the map and to create a info bubble that appears when you click the marker.

Here’s the code to extract the geo data:

Note: I’ve used the Javascript library DOMAssistant to ease the pain of DOM coding. If you don’t recognize the $() notation, you should definitively check it out.

// Getting all elements marked up with the class="vevent"
var events = $('.vevent');

// Loop through all event elements to extract data about each event
for (var i=0; i < events.length; i++) {
	// Extracting the coordinates
	events[i].latitude =  $(events[i]).elmsByClass('latitude')[0].innerHTML;
	events[i].longitude =  $(events[i]).elmsByClass('longitude')[0].innerHTML;
}

And here’s the code for putting a marker into a Google map (some code omitted for clarity of the example):

// Creating a point in Google map
var point = new GPoint(events[i].longitude, events[i].latitude);

// Creating and adding a marker in Google Maps
var marker = new GMarker(point);

// The variable map is the map object.
// It's been created earlier in the code and is not shown in the example
map.addOverlay(marker); 

Of course in the demo I do more than this. I extract more information about the events and then use it to create an info bubble which I attach to the click event of the marker. Please check out the entire Javascript code for this demo by downloading map.js.

If you want to use the code yourself you also need DOMAssistantComplete-2.7.js (or newer) and an API-key for Google maps.

Watch the demo in action

Related resources

• Google Maps api
• Microformats
• DOMAssistant