To request a geolocation for a given address we use a similar code:

var address = "Milan, Italy";
var locator = new GClientGeocoder();

locator.getLatLng(address, function(point) {
    if (point) {
        alert(address + " is located at: " + point.lat() + " - " + point.lng());
    } else {
        alert("Unable to locate " + address);
    }
});

In the example above we simply alert the located address, after testing for a defined point and by using the two simple getters methods (that due to their type of method, Google should naming them getLat() and getLng()): lat() and lng(). Usually we use the callback function to add overlay to the map and to place them in the right place… and is what we are going to do!

There are several types of overlay (markers, polylines, tiles…), the most common is the GMarker (the red balloon that Google places over the searched address). However the most interesting part is to realize custom overlay, which will have our desired look, will display data related to our application/web site and will provide as many features as we need.

Create a custom overlay is like to create a custom control (as showed in the “part two“). Differently from a custom control however, we have to extend the GOverlay class and implement its 4 methods: initialize(), remove(), copy() and redraw().

The first method has the duty to place an HTML node inside the map, the second as the opposite must remove that node, the third has simply to return an instance of our custom overlay with the same settings (in a few words it must return a copy of its self) and finally the forth method is used to adjust the position of the overlay whatever required. So the code will be something like:

// our "CustomOverlay" constructor
function CustomOverlay(settings) {
    // configures the instance with the required settings
}

// extends GOverlay class
CustomOverlay.prototype = new GOverlay();

// implements initialize()
CustomOverlay.prototype.initialize = function() {
    // creates an HTML element and appends it to the map'c container
}

// implements remove()
CustomOverlay.prototype.remove = function() {
    // removes the node from the DOM
}

// implements copy()
CustomOverlay.prototype.copy = function() {
    // returns a new instance of "CustomOverlay" with the same attributes
}

CustomOverlay.prototype.redraw = function(force) {
    if (force) {
        // adjust the position of the HTML element created by initialize()
    }
}

The redraw() deserves special attention, because it MUST handle the “force” argument, which is a boolean that indicates if we have to recalculate the position of the element or not. Without checking “force”, the code inside the method will be executed several times needless, causing possible memory leaks and browser instability!.

Let’s see how to use a CustomOverlay, the GClientGeocoder and a bit of jQuery, in order to realize a small Javascript application that:

• Read a file containing a list of addresses to locate and a value for each address which indicates an hypothetical numbers of participants to an event
• For each address requires the geocoding service
• For each address place a custom overlay on the map (according to its location) which will shows the numbers of participants and will looks different due to that number
• Display a progress bar indicating the status of the “geocoded” address and disable the drag of the map while loading

For convenience the file containing the address will be a text file with a json formatted array of objects:

[
	{name: "Agrigento", quantity: 6},
	{name: "Alessandria", quantity: 8},
	{name: "Ancona", quantity: 5},
...
]

In my example each object has the property “name” which indicates the name of an Italian province and “quantity” which represents the number of participants to an hypothetical event from that city.

This is instead the CustomOverlay‘s code (comments inside the code describe all the logic behind):

// custom overlay constructor
function CustomOverlay(settings) {

	this.parentMap = settings.parentMap; // a reference to the map
	this.position = settings.position; // the geolocation of the address
	this.width = settings.width || 43; // elements's with
	this.height = settings.height || 15; // elements's height
	this.quantity = settings.quantity; // the number of partecipants to show

}

// custom overlay class extends the GOverlay class
CustomOverlay.prototype = new GOverlay();

// initialize the custom overlay object
CustomOverlay.prototype.initialize = function() {

	// the overlay element will have a shape of an arrow
	// this variable will be used in order to associate a
	// custom CSS class
	var arrowStyle;

	// determining the style of the label based on quantity value
	if (this.quantity  20 && this.quantity < 50) {
		arrowStyle = "yellow";
	} else {
		arrowStyle = "red";
	}

	// div that rapresents the overlay object
	this.overlayBox = document.createElement("div");

	// set overlay's size
	this.overlayBox.style.width = this.width + "px";
	this.overlayBox.style.height = this.height + "px";

	// set overlay's content
	this.overlayBox.innerHTML = this.quantity;

	// set the className to apply the stylesheet
	this.overlayBox.className = "custom_overlay_object arrow_" + arrowStyle;

	// add the html element to the dom
	this.parentMap.getPane(G_MAP_MAP_PANE).appendChild(this.overlayBox);

}

// removes the object from the dom
CustomOverlay.prototype.remove = function() {

	this.overlayBox.parentNode.removeChild(this.overlayBox);

}

// returns an object equal to the current one
CustomOverlay.prototype.copy = function() {

	return new CustomOverlay({
		parentMap: this.parentMap,
		position: this.position,
		width: this.width,
		height: this.height,
		quantity: this.quantity
	});

}

// place the object in the right position
CustomOverlay.prototype.redraw = function(force) {

	// we use redraw() only if we really need it!
	if (force) {

		// get the pixels position of the overlay based on the geographic latidute and longitude
		var elementPosition = this.parentMap.fromLatLngToDivPixel(this.position);

		// positioning the overlay
		this.overlayBox.style.left = (elementPosition.x - parseInt(this.width+4)) + "px";
		this.overlayBox.style.top = (elementPosition.y - parseInt(this.height/2)) + "px";

	}

}

To request several geocoding successfully, we have to set an interval for the use of GClientGeocoder‘s method getLatLng(), that after some tests I realized that can’t never be less then 150 milliseconds, otherwise we will get errors from Google (we can’t simply use getLatLng() into a loop!). I’ve realized a js class which read the previously cited text file and manage this callings to getLatLng() at a given interval… I’ve called it DataManager, the code is the following (once again the comments inside describe the logic behind):

function DataManager(settings) {

	// Customizable parameters
	this.dataUrl = settings.dataUrl; // the url of the txt file to read
	this.gMap = settings.gMap; // a reference to the map

	// Internal parameters
	this._geoLocator = new GClientGeocoder(); // a reference to a GClientGeocoder instance
	this._processed = 0; // a counter for the processed requests
	var instance = this; // a reference to the current instance

	this._renderProgressBar = function() {

		// create a new HTML node for the progress bar
		var pb = document.createElement("div");

		// sets its ID
		pb.id = 'dm_progress_bar';

		// sets its content
		pb.innerHTML = '<div id="dm_bar_container"><div id="dm_bar"></div>;<div id="dm_info">Loading 0 of ? location(s).</div></div>';

		// adds the node to the map's container
		// (returned from getPane(G_MAP_MAP_PANE))
		instance.gMap.getPane(G_MAP_MAP_PANE).appendChild(pb);

	}

	this._removeProgressBar = function() {

		// get a reference to the html element representing the progress bar
		var pb = document.getElementById("dm_progress_bar");

		// removes the node from the map's container
		// (returned from getPane(G_MAP_MAP_PANE))
		instance.gMap.getPane(G_MAP_MAP_PANE).removeChild(pb);

		// activates the drag feature
		instance.gMap.enableDragging();

	}

	this._processData = function(data) {

		// get the progress bar node
		var bar = document.getElementById("dm_bar");

		// get the node containing the "load x of y" message
		var info = document.getElementById("dm_info");

		// reference to the current width of the progress bar
		var barWidth = parseInt(bar.style.width) || 0;

		// calculates the new with based on the loaded data
		var newBarWidth = Math.round(barWidth + 200/data.length);

		// requires the geocoding for each address
		instance._geoLocator.getLatLng(

			// access to the address
			data[instance._processed].name,

			// callback funtion used by getLatLng()
			function(point) {

				// add the overlay to the dom
				instance.gMap.addOverlay(new CustomOverlay({
					parentMap: instance.gMap,
					position: point,
					quantity: data[instance._processed].quantity
				}))

				// increase the processed locations
				instance._processed++;

				// sets the new with for the progress bar
				bar.style.width = newBarWidth > 200 ? 200 : newBarWidth + "px";

				if (instance._processed < data.length) {

					// if the data process is not finished, display the current status
					info.innerHTML = ["Loading: ", instance._processed, " of ", data.length, " location(s)."].join("");

				} else {

					// otherwise communicates that we have finished..
					info.innerHTML = "Loaded! ;-)";

					// ...and after 1/2 second removes the progress bar
					setTimeout(instance._removeProgressBar, 500);

				}

				// if there are more locations to process call this method again every
				// 150 milliseconds. (this._processData() is a recursive function)
				if (instance._processed < data.length) {
					setTimeout(function() {
						instance._processData(data);
					}, 150);
				}

			}

		)

	}

	// display the ajax error
	this._showError = function() {

		alert("error!");

	}

	// get the data
	this.getData = function() {

		// display the progress bar
		instance._renderProgressBar();

		// uses jQuery to load the txt file via Ajax
		$.ajax({
			type: "GET",
			url: instance.dataUrl,
			dataType: "json",
			cache: false,
			success: instance._processData,
			error: instance._showError
		});

	}

}

In the page containing the map the necessary code to run the sample application is:

function load() {

    if (GBrowserIsCompatible()) {

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

        map.disableDragging();

        map.setCenter(new GLatLng(41.65, 12.5), 6);

        var manager = new DataManager({
            dataUrl: "/gmaps/assets/js/data.json",
            gMap: map
        });

        manager.getData();

    }

}

The working example is here: http://daveoncode.yourfreehosting.net/google_maps_custom_overlay/index.html (unfortunately due to the yourfreehosting service, the load of the page is slow and difficult :P).

A brief note: although the scheduled geolation requests and the progress bar are cool to see, in a real application would be a best practice to realize a static file which already contains the various geolocations, in order to realize a faster application and avoid the google’s defined limits for geocoding requests.

The only concept that should be clear, in order to achive the goal, is what prototype is and why we must use it.

Javascript is not a really object oriented language, so we can’t really talk about classes and subclassing (using extends like in Java or Actionscript), but however we can create functions that act as constructor for new js objects, and we can inherit properties from an object to another by using the prototyping technique.

Let’s consider a simple Javascript constructor function, that can be used to create an Animal object:

function Animal(name, age, sex) {
    this.name = name;
    this.age = age;
    this.sex = sex;

    this.getInfo = function() {
        alert("Name: " + this.name + "\nAge: " + this.age + "\nSex: " + this.sex);
    }
}

To extend the Animal class with a Dog class, we have to define the Dog constructor:

function Dog(name, age, sex, barkPower) {

    Animal.apply(this, arguments);

    this.barkPower = barkPower;

    this.bark = function() {

        var barkBuffer = [this.name, " says: "];

        for (var i=0; i<this.barkPower; i++) {
            barkBuffer.push("bark! ");
        }

        alert(barkBuffer.join(""));

    }

}

and then prototyping it in this way:

Dog.prototype = new Animal();

The Animal.apply() call inside Dog, is like to use super() in Java to call the SuperClass constructor.
Now our Dog has the same methods and properties of Animal, for example we can use the getInfo() method, in addition to bark():

var laika = new Dog("Laika", 5, "F", 8);
laika.getInfo();
laika.bark();

Now, let’s put the prototyping technique in practice, in order to create a custom control for our map.
The Javascript class that represents a google map’s control is GControl, so if we want to make something of us own, we must extend that class. Furthermore we have to implements at least 2 methods: initialize() and getDefaultPosition(), in practice the GControl is to be considered an interface.
The first method, must add a DOM node (a graphic button or whatelse represents our control) to the map and return it (with return), the second must return an instance of GControlPosition which is used to place the DOM node (our control) in the right position.
Our goal is to create a custom map navigation (ie: move to north, move to south, move to east and move to west), so we will create 4 js classes that will extend GControl and implements the 2 methods. We call these classes respectively: GoUpButton, GoDownButton, GoLeftButton and GoRightButton .
Let’s see how GoUpButton is structured and how it works (others buttons will differ only for their position and click handler):

function GoUpButton(map) {

    this.map = map;
    this.button = document.createElement("a");

}

The function above, is the GoUpButton‘s constructor, and as you can see it takes one argument: map, that is a reference to the map’s instance, then it creates an <a> tag that will be our clickable button.
The next step is to extend GControl:

GoUpButton.prototype = new GControl();

Now, let’s implement the initialize() method:

GoUpButton.prototype.initialize = function() {

    var map = this.map;

    this.button.className = "custom_nav_top";
    this.button.href = "javascript:;";
    this.button.title = "Move the map to the top";
    this.button.innerHTML = "N";

    GEvent.addDomListener(this.button, "click", function() {
        map.panBy(new GSize(0, 100));
    });

    map.getContainer().appendChild(this.button);

    return this.button;

}

In this method we define the CSS class for the button, set its href attribute to “javascript:;” to ensure it won’t reload the page (is not necessary, but I feel more secure by doing it), set its title attribute and its innerHTML (in this case an N, which stands for North). Then we add an (anonymous) event listener that will be triggered when the user will click the button. This listener will invoke the map’s panBy() method, which moves the map by a specific distance by using an animation. The distance is represented by an instance of GSize, which is essentially a virtual polygon, which dimension are expressed with the two parameters width and height. So with new GSize(0, 100), we will move the map 100 pixels to the top (y axis).
The last two steps in the method are add the node to the DOM (by using map’s getContainer() method, which returns the node containing the map) and returns it.

Ok, finally there is the getDeafultPosition() implementation:

GoUpButton.prototype.getDefaultPosition = function() {

    return new GControlPosition(G_ANCHOR_TOP_LEFT, new GSize(240, 5));

}

This is a really simple method that returns an instance of GControlPosition, which will define how to place the control. GControlPosition takes 2 arguments: anchor and offset, the first can be one of the following constants:

• G_ANCHOR_TOP_RIGHT
• G_ANCHOR_TOP_LEFT
• G_ANCHOR_BOTTOM_RIGHT
• G_ANCHOR_BOTTOM_LEFT

that will anchor the control to the 4 possible map’s corners, the second represents the offset (ie: the distance from the anchor point). In this way we can position our button where we like (GoUpButton will be placed 5 pixel to the top of the map and 240 pixels to the left… in a map of 500×300 pixels it will appears centered on the top).
We have finished with our custom control!
Now we have to repeat the previous steps for GoDownButton, GoLeftButton and GoRightButton, by replacing the necessary values such button’s class, innerHTML, title, panBy() argument and GControlPosition() arguments.
In order to add all the 4 controls to the map we will use addControl() method:

    map.addControl(new GoUpButton(map));
    map.addControl(new GoDownButton(map));
    map.addControl(new GoLeftButton(map));
    map.addControl(new GoRightButton(map));

The result should be this:

The full code for the map above is the following:

/* go top */
function GoUpButton(map) {
    this.map = map;
    this.button = document.createElement("a");
}

GoUpButton.prototype = new GControl();

GoUpButton.prototype.initialize = function() {

    var map = this.map;

    this.button.className = "custom_nav_top";
    this.button.href = "javascript:;";
    this.button.title = "Move the map to the top";
    this.button.innerHTML = "N";

    GEvent.addDomListener(this.button, "click", function() {
        map.panBy(new GSize(0, 100));
    });

    map.getContainer().appendChild(this.button);

    return this.button;

}

GoUpButton.prototype.getDefaultPosition = function() {
    return new GControlPosition(G_ANCHOR_TOP_LEFT, new GSize(240, 5));
}

/* go down */
function GoDownButton(map) {
    this.map = map;
    this.button = document.createElement("a");
}

GoDownButton.prototype = new GControl();

GoDownButton.prototype.initialize = function() {

    var map = this.map;

    this.button.className = "custom_nav_down";
    this.button.href = "javascript:;";
    this.button.title = "Move the map to the bottom";
    this.button.innerHTML = "S";

    GEvent.addDomListener(this.button, "click", function() {
         map.panBy(new GSize(0, -100));
    });

    map.getContainer().appendChild(this.button);

    return this.button;

}

GoDownButton.prototype.getDefaultPosition = function() {
    return new GControlPosition(G_ANCHOR_TOP_LEFT, new GSize(240, 270));
}

/* go left */
function GoLeftButton(map) {
    this.map = map;
    this.button = document.createElement("a");
}

GoLeftButton.prototype = new GControl();

GoLeftButton.prototype.initialize = function() {

    var map = this.map;

    this.button.className = "custom_nav_left";
    this.button.href = "javascript:;";
    this.button.title = "Move the map to the left";
    this.button.innerHTML = "W";

    GEvent.addDomListener(this.button, "click", function() {
        map.panBy(new GSize(100, 0));
    });

    map.getContainer().appendChild(this.button);

    return this.button;

}

GoLeftButton.prototype.getDefaultPosition = function() {
    return new GControlPosition(G_ANCHOR_TOP_LEFT, new GSize(5, 140));
}

/* go right */
function GoRightButton(map) {
    this.map = map;
    this.button = document.createElement("a");
}

GoRightButton.prototype = new GControl();

GoRightButton.prototype.initialize = function() {

    var map = this.map;

    this.button.className = "custom_nav_right";
    this.button.href = "javascript:;";
    this.button.title = "Move the map to the right";
    this.button.innerHTML = "E";

    GEvent.addDomListener(this.button, "click", function() {
         map.panBy(new GSize(-100, 0));
    });

    map.getContainer().appendChild(this.button);

    return this.button;

}

GoRightButton.prototype.getDefaultPosition = function() {
    return new GControlPosition(G_ANCHOR_TOP_LEFT, new GSize(470, 140));
}

function initialize() {

    if (GBrowserIsCompatible()) {

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

        map.addControl(new GoUpButton(map));
        map.addControl(new GoDownButton(map));
        map.addControl(new GoLeftButton(map));
        map.addControl(new GoRightButton(map));
        map.setCenter(new GLatLng(41.87194, 12.56738), 5);

    }

}

1. Getting an API key

In order to use the Google maps service into our website/application, we have to go at the following address:
http://code.google.com/apis/maps/signup.html, accept the terms and conditions, specify our website url (an API key will works only for the specified url and its sub-directories), click on the “Generate Api Key” button and waiting for its generation. Note that in order to get the key, we have to be logged with a google account, otherwise Google will invite you to register before letting use its service.
After the API key generation, we will redirected to a page showing:

- The Key (for example, by asking a key for the domain www.foo.com, we’ll get something like: ABQIAAAAswsigAo1t_SU1aGAbcpt8hSRoQh9m-phgHuyQptS3bFLHQ8pkBQR4s7kR1aUKqmyqavqMz-lfRX09Q)
- Where this key is valid (the url that we have requested)
- A basic HTML code sample to create a map with the Google service

The only external file that will need to use to realize our custom map is this:

<script type="text/javascript" src="http://maps.google.com/maps?file=api&amp;v=2&amp;key=GENERATED_KEY"></script>

2. Setting up the basic map

As we can see in the Google example, the first steps in order to display the map are: put a div in the page that will be the container (with a bit of stylesheet to set its dimension) and assign it an ID for a convenient way to retrieve it with the the Javascript DOM method document.getElementById(“DIV_ID”), waiting for the loading of the page (in the example Google uses the <body> onload attribute, to pass an initialization function that will be executed after the loading of the page, but we can use a custom window.onload = ourFunction, or $(document).ready() jQuery’s method, Ext.onReady() method or else according to the js library that we want to use or not) and then use the main Google maps class GMap2.

The very basic code, to initialize the map is:

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

However the line above will only produce a grey box with the Google logo, and the link “Terms of use”.
To display something into the map, we must tell Google what part of the world we want to see.
This can be possible by using the GMap2′s method setCenter(), which requires a GLatLng as a mandatory parameter, plus an optional zoom level.
As API reference says: GLatLng is a point in geographical coordinates longitude and latitude.
This is the code (in the minimal possible version):

map.setCenter(new GLatLng(0, 0));

The previous command, will produces a very general geographic view, that according to us div dimensions will show a repeated world’s map.
That’s because, we didn’t specify a zoom level, and so 0 (zero) is assumed by Google (which is the lowest possible value).
Let’s try to pass a zoom value of 1 and see what happen!

map.setCenter(new GLatLng(0, 0), 1);

Hei! Finally we can at least read the names of the countries and pacific and Indian oceans… but is still not so funny, let’s move on!

3. Positioning the map on a given location

To positioning the map on a specific geographic location we have to know the latitude and longitude coordinates and passing them into the GLatLng,
constructor’s arguments. The basic way to do this, is to use maps.google.com website, search for a location (for example “Italy”), click on “Link”
button (the last link above the map) and extract the queryString parameter “ll”, which in my test for Italy are “41.87194,12.56738″.

By using the setCenter() method, in this way:

map.setCenter(new GLatLng(41.87194, 12.56738), 5);

We are able to visualize the whole Italy, plus others adjacent nations (in a 500×300 pixel div). This is how the map should be:

4. Add map controls

The map we have created so far doesn’t offer many features, except the drag and drop and the doubleclick to zoom, which is enabled by default (to avoid that functionality we can use disableDoubleClickZoom() map’s method, and we can eventually toggle it alternating with enableDoubleClickZoom() and checking for its status with doubleClickZoomEnabled() which returns a boolean indicating if is active or not).
To add a map control, we have to use the addControl() method and pass an instance of the desired control.
The following are the basic controls that Google maps offers:

map.addControl(new GMapTypeControl());

That will display:

map.addControl(new GHierarchicalMapTypeControl());

That will display:

map.addControl(new GMenuMapTypeControl(false));
// we can pass true to display short names

That will display:

map.addControl(new GSmallZoomControl());

That will display:

map.addControl(new GSmallMapControl());

That will display:

map.addControl(new GLargeMapControl());

That will display:

map.addControl(new GScaleControl());

That will display:

map.addControl(new GOverviewMapControl());

That will display:

Many controls are mutually exclusive, ie if we use for example both GSmallMapControl and GLargeMapControl the result is an ugly sovrapposition of these.

I’ve already developed a working map, that loads a datasource (in my test a simple .txt file which contains a JSON formatted string) with ajax and then shows the labels on the map (after a Flash like preloader), but it can be improved considerably.
However in the next days I will describe all the necessary steps and know-how to achive the goal.
I will split the… tutorial? description?…ah ah, I don’t know how to call it… let’s say story, into 2 parts:

Part 1

1. Getting a key to use the API
2. Setting up the basic map
3. Positioning the map on a given location
4. Add custom controls for zoom, map type, and navigation
5. Geolocation’s service (find latitude and longitude of a given address)

Part 2

6. Creating a custom overlay object by extending the GOverlay class
7. Display the custom overlay on a given location
8. Handle multiple geolocation requests and overlay together
9. Freeze the map and display a progress bar until geolocation process has finished

The first is the easy part and doesn’t require a good javascript knowledge nor particular html or css skills, the second is not so hard, but requires a pretty good understanding of javascript, prototype, css and ajax.
Stay tuned ;-)