ym4r 0.3.1 → 0.3.2

data/README

@@ -1,5 +1,5 @@
 =YM4R
-This is YM4R 0.3.1. The goal of YM4R (which naturally means Yellow Maps For Ruby...) is to ease the use of the Google Maps (including the Geocoding API) and Yahoo! Maps API's (including the Geocoding, Map Image, Traffic and Local Search API's) from Ruby and Rails.
+This is YM4R 0.3.2. The goal of YM4R (Yellow Maps For Ruby) is to ease the use of the Google Maps (including the Geocoding API) and Yahoo! Maps API's (including the Geocoding, Map Image, Traffic and Local Search API's) from Ruby and Rails.
 
 ==Operations
 ===Google Maps
@@ -58,7 +58,7 @@ What is sent to the browser will be the fllowing JavaScript code:
 A new type of GOverlay is available, called GMarkerGroup. To use it you would have to include in your HTML template the JavaScript file markerGroup.js found in the <tt>lib/ym4r/google_maps/javascript</tt> directory of the distribution.
 
 It is useful in 2 situations:
-- Display and undisplay a group of markers without referencing all of them. You just declare your marker group globally and call +activate+ and +deactivate+ on this group in response, for example, to clicks on links on your page..
+- Display and undisplay a group of markers without referencing all of them. You just declare your marker group globally and call +activate+ and +deactivate+ on this group in response, for example, to clicks on links on your page.
 - Keeping an index of markers, for example, in order to show one of these markers in reponse to a click on a link (the way Google Local does with the results of the search).
 
 Here is how you would use it from your Ruby code:
@@ -76,7 +76,32 @@ Then in your template, you could have that:
 	<%= @map.to_div %>
 When you click on one of the links, the corresponding marker has its info window displayed.
 
-You can call +activate+ and +deactivate+ to display or undisplay a group of markers. You can add new markers with +addMarker(marker,id)+. Again if you don't care about referencing the marker, you don't need to pass an id. If the marker group is active, the newly added marker will be displayed immediately. Otherwise it will be displayed the next time the group is activated. Finally, since it is an overlay, the group will be removed when calling clearOverlays on the GMap object.
+You can call +activate+ and +deactivate+ to display or undisplay a group of markers. You can add new markers with <tt>addMarker(marker,id)</tt>. Again if you don't care about referencing the marker, you don't need to pass an id. If the marker group is active, the newly added marker will be displayed immediately. Otherwise it will be displayed the next time the group is activated. Finally, since it is an overlay, the group will be removed when calling clearOverlays on the GMap object.
+
+====Clusterer
+A Clusterer is a type of overlay that contains a potentially very large group of markers. It is engineered so markers close to each other and undistinguishable from each other at some level of zoom, appear as only one marker on the map at that level of zoom. Therefore it is possible to have a very large number of markers on the map at the same time and not having the map crawl to a halt in order to display them. It has been slightly modified from Jef Poskanzer's original Clusterer2 code (see http://www.acme.com/javascript/ for the original version). The major difference with that version is that, in YM4R, the clusterer is a GOverlay and can therefore be added to the map with <tt>map.addOverlay(clusterer)</tt> and is cleared along with the rest of overlays when <tt>map.clearOverlays()</tt> is called.
+
+<b>In order to use a clusterer, you should include in your template page the clusterer.js file that can be found in the <tt>lib/ym4r/gogle_maps/javascript/</tt> directory of the YM4R distribution.</b>
+
+To create a clusterer, you should first create an array of all the GMarkers that you want to include in the clusterer (you can still add more after the clusterer has been added to the map though). When GMarkers close together are grouped in one cluster (represented by another marker on the map) and the user clicks on the cluster marker, a list of markers in the cluster is displayed in the info windo with a description: By default it is equal to the +title+ of the markers (which is also displayed as a tooltip when hovering on the marker with the mouse). If you don't want that, you can also pass to the GMarker constructor a key-value pair with key <tt>:description</tt> to have a description different from the title. For example, here is how you would create a clusterer:
+	markers = [GMarker.new([37.8,-90.4819],:info_window => "Hello",:title => "HOYOYO"),
+                  GMarker.new([37.844,-90.47819],:info_window => "Namaste",:description => "Chopoto" , :title => "Ay"),
+		  GMarker.new([37.83,-90.456619],:info_window => "Bonjour",:title => "Third"),
+	]
+	clusterer = Clusterer.new(markers,:max_visible_markers => 2)
+Of course, with only 3 markers, the whole clusterer thing is totally useless. Usually, using the clusterer starts being interesting with hundreds of markers. The options to pass the clusterer are:
+- <tt>:max_visible_markers</tt>: Below this number of markers, no clustering is performed. Defaults to 150.
+- <tt>:grid_size</tt>: The clusterer divides the visible area into a grid of this size. Defaults to 5.
+- <tt>:min_markers_per_cluster</tt>: Below this number of markers a cluster is not formed. Defaults to 5.
+- <tt>:max_lines_per_info_box</tt>: Number of lines to display in the info window displayed when a cluster is clicked on by the user. Defaults to 10.
+- <tt>:icon</tt>: Icon to be used to mark a cluster. Defaults to G_DEFAULT_ICON (the classic red marker).
+
+Then to add the clusterer to the map, you proceed as with a classic overlay:
+	map.addOverlay(clusterer)
+
+To add new markers in RJS, you should do this:
+	page << clusterer.add_marker(marker,description)
+In this case, the <tt>:description</tt> passed to the GMarker contructor will not be taken into account. Only the +description+ passed in the call to +add_marker+ will.
 
 ====Adding new map types
 It is now possible to easily add new map types, on top of the already existing ones, like G_SATELLITE_MAP or G_NORMAL_MAP. The imagery for these new map types can come from layers of the standard map types or can be taken either from a WMS server or from pretiled images on a server (that can be generated with a tool that comes with the library). 
@@ -96,9 +121,26 @@ Here is how to define a pretiled layer:
 	layer = PreTiledLayer.new("http://localhost:3000/tiles",
 	{'prefix' => "Map C 2006", 'copyright_texts' => ["Open Atlas"]},
 	13..13,0.7,"gif")
-I tell the PreTiledLayer constructor where I can find the tiles, setup the Copyright string, the valid zooms for the map, the opacity and the format. Tiles must have standardized names: <tt>tile_#{zoom}_#{x_tile}_#{y_tile}.#{format}</tt> (here the format is "gif"). You can use some tools (see below) to generate tiles in this format either from local maps or from WMS servers (useful to create tiles from geographic data files without having to run a map server or to cache images from slow servers).
+I tell the PreTiledLayer constructor where I can find the tiles, setup the Copyright string, the valid zooms for the map, the opacity and the format. Tiles must have standardized names: <tt>tile_#{zoom}_#{x_tile}_#{y_tile}.#{format}</tt> (here the format is "gif"). You can use some tools (see below) to generate tiles in this format either from local maps or from WMS servers (useful to create tiles from geographic data files without having to run a map server or to cache images from slow servers). 
 
-You can add such a layer to a new map type the following way:
+Instead of having the tiles requested directly, you can also decide to have an action on the server which takes care of it. You can used the class PreTiledLayerFromAction for this. In this case, the first argument of the constructor is an url of an action. The arguments +x+, +y+ and +z+ will be passed to it.
+	layer = PreTiledLayerFromAction.new(url_for(:action => :get_tile),
+	{'prefix' => "Map C 2006", 'copyright_texts' => ["Open Atlas"]},
+	13..14,0.7,"png")
+The other constructor arguments have the same meaning as PreTiledLayer. Here is an uninteresting example of action that serves tiles:
+	def get_tile
+          x = @params[:x]
+    	  y = @params[:y]
+    	  z = @params[:z]
+    	  begin
+            send_file "#{RAILS_ROOT}/public/tiles/tile_#{z}_#{x}_#{y}.png" , 
+		:type => 'image/png', :disposition => 'inline'
+          rescue Exception
+            render :nothing => true
+          end
+        end
+
+You can add a layer to a new map type the following way:
 	map_type = GMapType.new(layer,"My WMS")
 This is actually the simplest configuration possible. Your map type has only one data layer and is called "My WMS". You can add more that one layer: Either one that you have created yourself or existing ones. For example:
 	map_type = GMapType.new([GMapType::G_SATELLITE_MAP.get_tile_layers[0],layer,GMapType::G_HYBRID_MAP.get_tile_layers[1]],
@@ -202,19 +244,22 @@ Here is an example of request:
 Preliminary support for this API has been added. It works along the same lines as with the Google Maps API but it is not very polished currently.
 
 ==Changes since last version
-- Addition of a utility class to use the Google Maps API
+- Addition of Clusterer class
+- Addition of a PreTiledLayerFromAction class
 
 ==TODO
-- Add support for easy manipulation of external Google Maps-related libraries: Advanced tooltip manipulation, GeoRSS, Clusterer...
-- Add support to show and hide groups of overlays easily
+- Add support for easy manipulation of external Google Maps-related libraries: Advanced tooltip manipulation, GeoRSS, KML,...
 - Documentation! Documentation! Documentation!
 - Tutorials
 
 ==Disclaimer
 This software is not endorsed in any way by Yahoo! or Google.
 
+==Acknowledgement
+YM4R bundles JavaScript libraries from John Deck (WMS layers on Google Maps) and Jef Poskanzer (Clusterer on Google Maps).
+
 ==License
-YM4R is released under the MIT license.
+YM4R is released under the MIT license. The <tt>clusterer.js</tt> file is redistributed with a different license (but still compatible with the MIT license). Check the top of the file in <tt>lib/ym4r/google_maps/javascript</tt> to know more.
 
 ==Support
 Any questions, enhancement proposals, bug notifications or corrections can be sent to mailto:guilhem.vellut+ym4r@gmail.com.

data/lib/ym4r/google_maps/javascript/clusterer.js

@@ -0,0 +1,444 @@
+// Clusterer.js - marker clustering routines for Google Maps apps
+//
+// The original version of this code is available at:
+// http://www.acme.com/javascript/
+//
+// Copyright � 2005,2006 by Jef Poskanzer <jef@mail.acme.com>.
+// All rights reserved.
+//
+// Modified for inclusion into the YM4R library in accordance with the 
+// following license:
+//
+// Redistribution and use in source and binary forms, with or without
+// modification, are permitted provided that the following conditions
+// are met:
+// 1. Redistributions of source code must retain the above copyright
+//    notice, this list of conditions and the following disclaimer.
+// 2. Redistributions in binary form must reproduce the above copyright
+//    notice, this list of conditions and the following disclaimer in the
+//    documentation and/or other materials provided with the distribution.
+//
+// THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
+// ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+// IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+// ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
+// FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+// DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
+// OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
+// HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
+// LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
+// OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
+// SUCH DAMAGE.
+//
+// For commentary on this license please see http://www.acme.com/license.html
+
+
+// Constructor.
+Clusterer = function(markers,icon,maxVisibleMarkers,gridSize,minMarkersPerCluster,maxLinesPerInfoBox) {	
+    this.markers = [];
+    if(markers){
+	for(var i =0 ; i< markers.length ; i++){
+	    this.addMarker(markers[i]);
+	}
+    }    
+    this.clusters = [];
+    this.timeout = null;
+        
+    this.maxVisibleMarkers = maxVisibleMarkers || 150;
+    this.gridSize = gridSize || 5;
+    this.minMarkersPerCluster = minMarkersPerCluster || 5;
+    this.maxLinesPerInfoBox = maxLinesPerInfoBox || 10;
+    
+    this.icon = icon || G_DEFAULT_ICON;
+}
+
+Clusterer.prototype = new GOverlay();
+
+Clusterer.prototype.initialize = function ( map ){
+    this.map = map;
+    this.currentZoomLevel = map.getZoom();
+   
+    GEvent.addListener( map, 'zoomend', Clusterer.makeCaller( Clusterer.display, this ) );
+    GEvent.addListener( map, 'moveend', Clusterer.makeCaller( Clusterer.display, this ) );
+    GEvent.addListener( map, 'infowindowclose', Clusterer.makeCaller( Clusterer.popDown, this ) );
+    //Set map for each marker
+    for(var i = 0,len = this.markers.length ; i < len ; i++){
+	this.markers[i].setMap( map );
+    }
+    this.displayLater();
+}
+
+Clusterer.prototype.remove = function(){
+     for ( var i = 0; i < this.markers.length; ++i ){
+	 this.removeMarker(this.markers[i]);
+     }
+}
+
+Clusterer.prototype.copy = function(){
+    return new Clusterer(this.markers,this.icon,this.maxVisibleMarkers,this.gridSize,this.minMarkersPerCluster,this.maxLinesPerInfoBox);
+}
+
+Clusterer.prototype.redraw = function(force){
+    this.displayLater();
+}
+
+// Call this to change the cluster icon.
+Clusterer.prototype.setIcon = function ( icon ){
+    this.icon = icon;
+}
+
+// Call this to add a marker.
+Clusterer.prototype.addMarker = function ( marker, description){
+    marker.onMap = false;
+    this.markers.push( marker );
+    marker.description = marker.description || description;
+    if(this.map != null){
+	marker.setMap(this.map);
+	this.displayLater();
+    }
+};
+
+
+// Call this to remove a marker.
+Clusterer.prototype.removeMarker = function ( marker ){
+    for ( var i = 0; i < this.markers.length; ++i )
+	if ( this.markers[i] == marker ){
+	    if ( marker.onMap )
+		this.map.removeOverlay( marker );
+	    for ( var j = 0; j < this.clusters.length; ++j ){
+		var cluster = this.clusters[j];
+		if ( cluster != null ){
+		    for ( var k = 0; k < cluster.markers.length; ++k )
+			if ( cluster.markers[k] == marker ){
+			    cluster.markers[k] = null;
+			    --cluster.markerCount;
+			    break;
+			}
+		    if ( cluster.markerCount == 0 ){
+			this.clearCluster( cluster );
+			this.clusters[j] = null;
+			}
+		    else if ( cluster == this.poppedUpCluster )
+			Clusterer.rePop( this );
+		    }
+		}
+	    this.markers[i] = null;
+	    break;
+	    }
+    this.displayLater();
+};
+
+Clusterer.prototype.displayLater = function (){
+    if ( this.timeout != null )
+	clearTimeout( this.timeout );
+    this.timeout = setTimeout( Clusterer.makeCaller( Clusterer.display, this ), 50 );
+};
+
+Clusterer.display = function ( clusterer ){
+    var i, j, marker, cluster, len, len2;
+
+    clearTimeout( clusterer.timeout );
+
+    var newZoomLevel = clusterer.map.getZoom();
+    if ( newZoomLevel != clusterer.currentZoomLevel ){
+	// When the zoom level changes, we have to remove all the clusters.
+	for ( i = 0 , len = clusterer.clusters.length; i < len; ++i ){
+	    if ( clusterer.clusters[i] != null ){
+		clusterer.clearCluster( clusterer.clusters[i] );
+		clusterer.clusters[i] = null;
+	    }
+	}
+	clusterer.clusters.length = 0;
+	clusterer.currentZoomLevel = newZoomLevel;
+    }
+
+    // Get the current bounds of the visible area.
+    var bounds = clusterer.map.getBounds();
+
+    // Expand the bounds a little, so things look smoother when scrolling
+    // by small amounts.
+    var sw = bounds.getSouthWest();
+    var ne = bounds.getNorthEast();
+    var dx = ne.lng() - sw.lng();
+    var dy = ne.lat() - sw.lat();
+    dx *= 0.10;
+    dy *= 0.10;
+    bounds = new GLatLngBounds(
+      new GLatLng( sw.lat() - dy, sw.lng() - dx ),
+      new GLatLng( ne.lat() + dy, ne.lng() + dx ) 
+    );
+
+    // Partition the markers into visible and non-visible lists.
+    var visibleMarkers = [];
+    var nonvisibleMarkers = [];
+    for ( i = 0, len = clusterer.markers.length ; i < len; ++i ){
+	marker = clusterer.markers[i];
+	if ( marker != null )
+	    if ( bounds.contains( marker.getPoint() ) )
+		visibleMarkers.push( marker );
+	    else
+		nonvisibleMarkers.push( marker );
+    }
+
+    // Take down the non-visible markers.
+    for ( i = 0, len = nonvisibleMarkers.length ; i < len; ++i ){
+	marker = nonvisibleMarkers[i];
+	if ( marker.onMap ){
+	    clusterer.map.removeOverlay( marker );
+	    marker.onMap = false;
+	}
+    }
+
+    // Take down the non-visible clusters.
+    for ( i = 0, len = clusterer.clusters.length ; i < len ; ++i ){
+	cluster = clusterer.clusters[i];
+	if ( cluster != null && ! bounds.contains( cluster.marker.getPoint() ) && cluster.onMap ){
+	    clusterer.map.removeOverlay( cluster.marker );
+	    cluster.onMap = false;
+	}
+    }
+
+    // Clustering!  This is some complicated stuff.  We have three goals
+    // here.  One, limit the number of markers & clusters displayed, so the
+    // maps code doesn't slow to a crawl.  Two, when possible keep existing
+    // clusters instead of replacing them with new ones, so that the app pans
+    // better.  And three, of course, be CPU and memory efficient.
+    if ( visibleMarkers.length > clusterer.maxVisibleMarkers ){
+	// Add to the list of clusters by splitting up the current bounds
+	// into a grid.
+	var latRange = bounds.getNorthEast().lat() - bounds.getSouthWest().lat();
+	var latInc = latRange / clusterer.gridSize;
+	var lngInc = latInc / Math.cos( ( bounds.getNorthEast().lat() + bounds.getSouthWest().lat() ) / 2.0 * Math.PI / 180.0 );
+	for ( var lat = bounds.getSouthWest().lat(); lat <= bounds.getNorthEast().lat(); lat += latInc )
+	    for ( var lng = bounds.getSouthWest().lng(); lng <= bounds.getNorthEast().lng(); lng += lngInc ){
+		cluster = new Object();
+		cluster.clusterer = clusterer;
+		cluster.bounds = new GLatLngBounds( new GLatLng( lat, lng ), new GLatLng( lat + latInc, lng + lngInc ) );
+		cluster.markers = [];
+		cluster.markerCount = 0;
+		cluster.onMap = false;
+		cluster.marker = null;
+		clusterer.clusters.push( cluster );
+	    }
+
+	// Put all the unclustered visible markers into a cluster - the first
+	// one it fits in, which favors pre-existing clusters.
+	for ( i = 0, len = visibleMarkers.length ; i < len; ++i ){
+	    marker = visibleMarkers[i];
+	    if ( marker != null && ! marker.inCluster ){
+		for ( j = 0, len2 = clusterer.clusters.length ; j < len2 ; ++j ){
+		    cluster = clusterer.clusters[j];
+		    if ( cluster != null && cluster.bounds.contains( marker.getPoint() ) ){
+			cluster.markers.push( marker );
+			++cluster.markerCount;
+			marker.inCluster = true;
+		    }
+		}
+	    }
+	}
+
+	// Get rid of any clusters containing only a few markers.
+	for ( i = 0, len = clusterer.clusters.length ; i < len ; ++i )
+	    if ( clusterer.clusters[i] != null && clusterer.clusters[i].markerCount < clusterer.minMarkersPerCluster ){
+		clusterer.clearCluster( clusterer.clusters[i] );
+		clusterer.clusters[i] = null;
+	    }
+
+	// Shrink the clusters list.
+	for ( i = clusterer.clusters.length - 1; i >= 0; --i )
+	    if ( clusterer.clusters[i] != null )
+		break;
+	    else
+		--clusterer.clusters.length;
+
+	// Ok, we have our clusters.  Go through the markers in each
+	// cluster and remove them from the map if they are currently up.
+	for ( i = 0, len = clusterer.clusters.length ; i < len; ++i ){
+	    cluster = clusterer.clusters[i];
+	    if ( cluster != null ){
+		for ( j = 0 , len2 = cluster.markers.length ; j < len2; ++j ){
+		    marker = cluster.markers[j];
+		    if ( marker != null && marker.onMap ){
+			clusterer.map.removeOverlay( marker );
+			marker.onMap = false;
+		    }
+		}
+	    }
+	}
+	
+	// Now make cluster-markers for any clusters that need one.
+	for ( i = 0, len = clusterer.clusters.length; i < len; ++i ){
+	    cluster = clusterer.clusters[i];
+	    if ( cluster != null && cluster.marker == null ){
+		// Figure out the average coordinates of the markers in this
+		// cluster.
+		var xTotal = 0.0, yTotal = 0.0;
+		for ( j = 0, len2 = cluster.markers.length; j < len2 ; ++j ){
+		    marker = cluster.markers[j];
+		    if ( marker != null ){
+			xTotal += ( + marker.getPoint().lng() );
+			yTotal += ( + marker.getPoint().lat() );
+		    }
+		}
+		var location = new GLatLng( yTotal / cluster.markerCount, xTotal / cluster.markerCount );
+		marker = new GMarker( location, { icon: clusterer.icon } );
+		cluster.marker = marker;
+		GEvent.addListener( marker, 'click', Clusterer.makeCaller( Clusterer.popUp, cluster ) );
+	    }
+	}
+    }
+
+    // Display the visible markers not already up and not in clusters.
+    for ( i = 0, len = visibleMarkers.length; i < len; ++i ){
+	marker = visibleMarkers[i];
+	if ( marker != null && ! marker.onMap && ! marker.inCluster )
+	{
+	    clusterer.map.addOverlay( marker );
+	    marker.addedToMap();
+	    marker.onMap = true;
+	}
+    }
+
+    // Display the visible clusters not already up.
+    for ( i = 0, len = clusterer.clusters.length ; i < len; ++i ){
+	cluster = clusterer.clusters[i];
+	if ( cluster != null && ! cluster.onMap && bounds.contains( cluster.marker.getPoint() )){
+	    clusterer.map.addOverlay( cluster.marker );
+	    cluster.onMap = true;
+	}
+    }
+
+    // In case a cluster is currently popped-up, re-pop to get any new
+    // markers into the infobox.
+    Clusterer.rePop( clusterer );
+};
+
+
+Clusterer.popUp = function ( cluster ){
+    var clusterer = cluster.clusterer;
+    var html = '<table width="300">';
+    var n = 0;
+    for ( var i = 0 , len = cluster.markers.length; i < len; ++i )
+	{
+	var marker = cluster.markers[i];
+	if ( marker != null )
+	    {
+	    ++n;
+	    html += '<tr><td>';
+	    if ( marker.getIcon().smallImage != null )
+		html += '<img src="' + marker.getIcon().smallImage + '">';
+	    else
+		html += '<img src="' + marker.getIcon().image + '" width="' + ( marker.getIcon().iconSize.width / 2 ) + '" height="' + ( marker.getIcon().iconSize.height / 2 ) + '">';
+	    html += '</td><td>' + marker.description + '</td></tr>';
+	    if ( n == clusterer.maxLinesPerInfoBox - 1 && cluster.markerCount > clusterer.maxLinesPerInfoBox  )
+		{
+		html += '<tr><td colspan="2">...and ' + ( cluster.markerCount - n ) + ' more</td></tr>';
+		break;
+		}
+	    }
+	}
+    html += '</table>';
+    clusterer.map.closeInfoWindow();
+    cluster.marker.openInfoWindowHtml( html );
+    clusterer.poppedUpCluster = cluster;
+};
+
+Clusterer.rePop = function ( clusterer ){
+    if ( clusterer.poppedUpCluster != null )
+	Clusterer.popUp( poppedUpCluster );
+};
+
+Clusterer.popDown = function ( clusterer ){
+    clusterer.poppedUpCluster = null;
+};
+
+Clusterer.prototype.clearCluster = function ( cluster ){
+    var i, marker;
+
+    for ( i = 0; i < cluster.markers.length; ++i ){
+	if ( cluster.markers[i] != null ){
+	    cluster.markers[i].inCluster = false;
+	    cluster.markers[i] = null;
+	}
+    }
+    
+    cluster.markers.length = 0;
+    cluster.markerCount = 0;
+    
+    if ( cluster == this.poppedUpCluster )
+	this.map.closeInfoWindow();
+    
+    if ( cluster.onMap )
+    {
+	this.map.removeOverlay( cluster.marker );
+	cluster.onMap = false;
+    }
+};
+
+// This returns a function closure that calls the given routine with the
+// specified arg.
+Clusterer.makeCaller = function ( func, arg ){
+    return function () { func( arg ); };
+};
+
+
+// Augment GMarker so it handles markers that have been created but
+// not yet addOverlayed.
+GMarker.prototype.setMap = function ( map ){
+    this.map = map;
+};
+
+GMarker.prototype.getMap = function (){
+    return this.map;
+}
+
+GMarker.prototype.addedToMap = function (){
+    this.map = null;
+};
+
+
+GMarker.prototype.origOpenInfoWindow = GMarker.prototype.openInfoWindow;
+GMarker.prototype.openInfoWindow = function ( node, opts ){
+    if ( this.map != null )
+	return this.map.openInfoWindow( this.getPoint(), node, opts );
+    else
+	return this.origOpenInfoWindow( node, opts );
+};
+
+GMarker.prototype.origOpenInfoWindowHtml = GMarker.prototype.openInfoWindowHtml;
+GMarker.prototype.openInfoWindowHtml = function ( html, opts ){
+    if ( this.map != null )
+	return this.map.openInfoWindowHtml( this.getPoint(), html, opts );
+    else
+	return this.origOpenInfoWindowHtml( html, opts );
+};
+
+GMarker.prototype.origOpenInfoWindowTabs = GMarker.prototype.openInfoWindowTabs;
+GMarker.prototype.openInfoWindowTabs = function ( tabNodes, opts ){
+    if ( this.map != null )
+	return this.map.openInfoWindowTabs( this.getPoint(), tabNodes, opts );
+    else
+	return this.origOpenInfoWindowTabs( tabNodes, opts );
+};
+
+GMarker.prototype.origOpenInfoWindowTabsHtml = GMarker.prototype.openInfoWindowTabsHtml;
+GMarker.prototype.openInfoWindowTabsHtml = function ( tabHtmls, opts ){
+    if ( this.map != null )
+       return this.map.openInfoWindowTabsHtml( this.getPoint(), tabHtmls, opts );
+    else
+       return this.origOpenInfoWindowTabsHtml( tabHtmls, opts );
+};
+
+GMarker.prototype.origShowMapBlowup = GMarker.prototype.showMapBlowup;
+GMarker.prototype.showMapBlowup = function ( opts ){
+    if ( this.map != null )
+	return this.map.showMapBlowup( this.getPoint(), opts );
+    else
+	return this.origShowMapBlowup( opts );
+};
+
+
+function addDescriptionToMarker(marker, description){
+    marker.description = description;
+    return marker;
+}

data/lib/ym4r/google_maps/layer.rb

@@ -43,16 +43,17 @@ module Ym4r
     class GTileLayer
       include MappingObject
             
-      attr_accessor :opacity, :zoom_inter, :copyright
+      attr_accessor :opacity, :zoom_inter, :copyright, :format
 
-      def initialize(zoom_inter = 0..17, copyright= {'prefix' => '', 'copyright_texts' => [""]}, opacity = 1.0)
+      def initialize(zoom_inter = 0..17, copyright= {'prefix' => '', 'copyright_texts' => [""]}, opacity = 1.0, format = "png")
         @opacity = opacity
         @zoom_inter = zoom_inter
         @copyright = copyright
+        @format = format.to_s
       end
 
       def create
-        "addPropertiesToLayer(new GTileLayer(new GCopyrightCollection(\"\"),#{zoom_inter.begin},#{zoom_inter.end}),#{get_tile_url},function(a,b) {return #{MappingObject.javascriptify_variable(@copyright)};}\n,function() {return #{@opacity};})"
+        "addPropertiesToLayer(new GTileLayer(new GCopyrightCollection(\"\"),#{zoom_inter.begin},#{zoom_inter.end}),#{get_tile_url},function(a,b) {return #{MappingObject.javascriptify_variable(@copyright)};}\n,function() {return #{@opacity};},function(){return #{@format == "png"};})"
       end
       
       #for subclasses to implement
@@ -60,32 +61,38 @@ module Ym4r
       end
     end
     
+    #Represents a pre tiled layer, taking images directly from a server, without using a server script.
     class PreTiledLayer < GTileLayer
-      attr_accessor :base_url, :format
+      attr_accessor :base_url
       
-      def initialize(base_url = "http://localhost:8080/tiles", copyright = {'prefix' => '', 'copyright_texts' => [""]}, zoom_inter = 0..17, opacity = 1.0,format = "png")
-        super(zoom_inter, copyright, opacity)
+      def initialize(base_url = "/public/tiles", copyright = {'prefix' => '', 'copyright_texts' => [""]}, zoom_inter = 0..17, opacity = 1.0,format = "png")
+        super(zoom_inter, copyright, opacity,format)
         @base_url = base_url
-        @format = format
       end
       
       #returns the code to determine the url to fetch the tile. Follows the convention adopted by the tiler: {base_url}/tile_{b}_{a.x}_{a.y}.{format}
       def get_tile_url
-        "function(a,b,c) { return '#{@base_url}/tile_' + b + '_' + a.x + '_' + a.y + '.#{@format}';}"
+        "function(a,b,c) { return '#{@base_url}/tile_' + b + '_' + a.x + '_' + a.y + '.#{format}';}"
       end 
     end
+
+    #Represents a pretiled layer (it actually does not really matter where the tiles come from). Calls an action on the server to get back the tiles. It can be used, for example, to return default tiles when the requested tile is not present.
+    class PreTiledLayerFromAction < PreTiledLayer
+      def get_tile_url
+        "function(a,b,c) { return '#{base_url}?x=' + a.x + '&y=' + a.y + '&z=' + b;}"
+      end
+    end
     
     #needs to include the JavaScript file wms-gs.js for this to work
     #see http://docs.codehaus.org/display/GEOSDOC/Google+Maps
     class WMSLayer < GTileLayer
-      attr_accessor :base_url, :layers, :styles, :format, :merc_proj, :use_geographic
+      attr_accessor :base_url, :layers, :styles, :merc_proj, :use_geographic
 
       def initialize(base_url, layers, styles = "", copyright = {'prefix' => '', 'copyright_texts' => [""]}, use_geographic = false, merc_proj = :mapserver, zoom_inter = 0..17, opacity = 1.0,format= "png")
-        super(zoom_inter, copyright, opacity)
+        super(zoom_inter, copyright, opacity,format)
         @base_url = base_url
         @layers = layers
         @styles = styles
-        @format = format
         @merc_proj = if merc_proj == :mapserver
                        "54004"
                      elsif merc_proj == :geoserver
@@ -101,7 +108,7 @@ module Ym4r
       end
 
       def create
-        "addWMSPropertiesToLayer(#{super},#{MappingObject.javascriptify_variable(@base_url)},#{MappingObject.javascriptify_variable(@layers)},#{MappingObject.javascriptify_variable(@styles)},#{MappingObject.javascriptify_variable(@format)},#{MappingObject.javascriptify_variable(@merc_proj)},#{MappingObject.javascriptify_variable(@use_geographic)})"
+        "addWMSPropertiesToLayer(#{super},#{MappingObject.javascriptify_variable(@base_url)},#{MappingObject.javascriptify_variable(@layers)},#{MappingObject.javascriptify_variable(@styles)},#{MappingObject.javascriptify_variable(format)},#{MappingObject.javascriptify_variable(@merc_proj)},#{MappingObject.javascriptify_variable(@use_geographic)})"
       end
     end
   end

data/lib/ym4r/google_maps/map.rb

@@ -117,7 +117,8 @@ module Ym4r
         #put the functions in a separate javascript file to be included in the page
         html << "function addInfoWindowToMarker(marker,info){\nGEvent.addListener(marker, \"click\", function() {\nmarker.openInfoWindowHtml(info);\n});\nreturn marker;\n}\n"
         html << "function addInfoWindowTabsToMarker(marker,info){\nGEvent.addListener(marker, \"click\", function() {\nmarker.openInfoWindowTabsHtml(info);\n});\nreturn marker;\n}\n"
-        html << "function addPropertiesToLayer(layer,getTile,copyright,opacity){\nlayer.getTileUrl = getTile;\nlayer.getCopyright = copyright;\nlayer.getOpacity = opacity;\nreturn layer;\n}\n"
+        html << "function addPropertiesToLayer(layer,getTile,copyright,opacity,isPng){\nlayer.getTileUrl = getTile;\nlayer.getCopyright = copyright;\nlayer.getOpacity = opacity;\nlayer.isPng = isPng;\nreturn layer;\n}\n"
+        html << "function addOptionsToIcon(icon,options){\nfor(var k in options){\nicon[k] = options[k];\n}\nreturn icon;\n}\n"
         html << @global_init * "\n"
         html << "var #{@variable};\n" if !no_declare and !no_global
         html << "window.onload = function() {\nif (GBrowserIsCompatible()) {\n" if !no_load

data/lib/ym4r/google_maps/overlay.rb

@@ -56,18 +56,15 @@ module Ym4r
       #Creates a GIcon.
       def create
         if @copy_base
-          "new GIcon(#{MappingObject.javascriptify_variable(@copy_base)})"
+          c = "new GIcon(#{MappingObject.javascriptify_variable(@copy_base)})"
         else
-          "new GIcon()"
+          c = "new GIcon()"
         end
-      end
-      #Declares a GIcon. It is necessary to declare an icon before using it, since it is the only way to set up its attributes.
-      def declare(variable)
-        decl = super(variable) + "\n"
-        @options.each do |key,value|
-          decl << "#{to_javascript}.#{MappingObject.javascriptify_method(key.to_s)} = #{MappingObject.javascriptify_variable(value)};\n"
+        if !options.empty?
+          "addOptionsToIcon(#{c},#{MappingObject.javascriptify_variable(@options)})"
+        else
+          c
         end
-        decl
       end
     end
      
@@ -96,6 +93,7 @@ module Ym4r
       end
     end
 
+    #A GOverlay representing a group of GMarkers. The GMarkers can be identified with an id, which can be used to show the info window of a specific marker, in reponse, for example, to a click on a link. The whole group can be shown on and off at once. It should be declared global at initialization time to be useful.
     class GMarkerGroup
       include MappingObject
       attr_accessor :active, :markers, :markers_by_id
@@ -115,6 +113,31 @@ module Ym4r
         "new GMarkerGroup(#{MappingObject.javascriptify_variable(@active)},#{MappingObject.javascriptify_variable(@markers)},#{MappingObject.javascriptify_variable(@markers_by_id)})"
       end
     end
+
+    #Makes the link with the Clusterer2 library by Jef Poskanzer (slightly modified though). Is a GOverlay making clusters out of its GMarkers, so that GMarkers very close to each other appear as one when the zoom is low. When the zoom gets higher, the individual markers are drawn.
+    class Clusterer
+      include MappingObject
+      attr_accessor :markers,:options
+
+      def initialize(markers = [], options = {})
+        @markers = markers
+        @options = options
+      end
+
+      def create 
+        js_marker = '[' + @markers.collect do |marker|
+          add_description(marker)
+        end.join(",") + ']'
+
+        "new Clusterer(#{js_marker},#{MappingObject.javascriptify_variable(@options[:icon] || GIcon::DEFAULT)},#{@options[:max_visible_markers] || 150},#{@options[:grid_size] || 5},#{@options[:min_markers_per_cluster] || 5},#{@options[:max_lines_per_info_box] || 10})"
+      end
+            
+      private
+      def add_description(marker)
+        "addDescriptionToMarker(#{MappingObject.javascriptify_variable(marker)},#{MappingObject.javascriptify_variable(marker.options[:description] || marker.options[:title] || '')})"
+      end
+      
+    end
     
     #A basic Latitude/longitude point.
     class GLatLng 

data/rakefile.rb

@@ -24,7 +24,7 @@ spec = Gem::Specification::new do |s|
   s.platform = Gem::Platform::RUBY
 
   s.name = 'ym4r'
-  s.version = "0.3.1"
+  s.version = "0.3.2"
   s.summary = "Using Google Maps and Yahoo! Maps from Ruby and Rails"
   s.description = <<EOF
 EOF

metadata

@@ -3,8 +3,8 @@ rubygems_version: 0.8.11
 specification_version: 1
 name: ym4r
 version: !ruby/object:Gem::Version 
-  version: 0.3.1
-date: 2006-06-18 00:00:00 +05:00
+  version: 0.3.2
+date: 2006-06-23 00:00:00 +05:00
 summary: Using Google Maps and Yahoo! Maps from Ruby and Rails
 require_paths: 
 - lib
@@ -59,6 +59,7 @@ files:
 - lib/ym4r/yahoo_maps/flash/tool.rb
 - lib/ym4r/yahoo_maps/flash/widget.rb
 - lib/ym4r/google_maps/config/config.yml
+- lib/ym4r/google_maps/javascript/clusterer.js
 - lib/ym4r/google_maps/javascript/markerGroup.js
 - lib/ym4r/google_maps/javascript/wms-gs.js
 - tools/tile_image.rb