ym4r 0.3.2 → 0.4.1

data/README

@@ -1,5 +1,24 @@
 =YM4R
-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.
+This is YM4R 0.4.1. 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.
+
+==Installing
+===As a Gem
+Just type under a command line:
+	gem install ym4r
+And the last version will be automatically downloaded and installed.
+
+===In the lib directory of a Rails project
+It can be useful if you cannot install global gems on the machine where you are going to deploy your application (for example on a shared host).
+
+You first need to unpack the gem. To do this, if the gem is installed on your local machine, type:
+	gem unpack ym4r
+
+You can also directly untar the gem (after having downloaded it first) if you prefer:
+	tar xf ym4r-0.3.2.gem
+then:
+	tar xzf data.tar.gz
+
+Then copy the content of the lib directory of the gem into the lib directory of your rails application: You should have in RAILS_ROOT/lib the ym4.rb file and the ym4r directory (plus a tasks folder; which was already there before). Contrary to what is done for a plugin, you will still need to require and include in your application the files and modules you are interested in.
 
 ==Operations
 ===Google Maps
@@ -14,6 +33,13 @@ You should load the Google Maps part of YM4R this way:
 	require 'ym4r/google_maps'
 	include Ym4r::GoogleMaps
 
+===Managing the API key(s)
+Google Maps requires a domain dependent key in order to use the library. So if you use your app from both <tt>localhost</tt> (for developing and testing) and some other domain like <tt>mydomain.com</tt>, you will need 2 sets of keys. You can get keys from http://www.google.com/apis/maps/signup.html. Your key will be valid for all the subdirectories of the URL you requested the key for.
+
+Starting with version 0.4.1, there are 2 ways to manage the keys:
+- The first is to have only 1 key at a time and change the content of the <tt>YM4R_ROOT/lib/ym4r/google_maps/config/config.yml</tt> file as part of the deployment process. Managing the keys is then your sole responsibility. If you do that, you should have only one key valid for your currently deployment location as the content of the <tt>config.yml</tt> file. Basically that's it.
+- The other one is to have a YAML hash as the content of the <tt>YM4R_ROOT/lib/ym4r/google_maps/config/config.yml</tt> file. Each key will be a host and each value the corresponding API key for the host. Then in the view, when outputting the headers with the <tt>GMap.header</tt> class method, you should pass the option <tt>:host</tt> with the host as the value. Of course this host should not be hardcoded but taken from the request. For example in Rails, you could pass: <tt>:host => @request.host</tt>.
+
 ====Naming conventions
 The names of the Ruby class follow the ones in the JavaScript Google Maps API v2, except for GMap2, which in Ruby code is called simply GMap. To know what is possible to do with each class, you should refer to the documentation available on Google website.
 
@@ -39,7 +65,7 @@ which is strictly equivalent to
 The map is represented by a GMap object. You need to pass to the constructor the id of a DIV that will contain the map. You have to place this DIV yourself in your HTML template. You can also optionnally pass to the constructor the JavaScript name of the variable that will reference the map, which by default will be global in JavaScript. You have convenience methods to setup the controls, the center, the zoom, overlays, map types and the icons (which are also global). You can also pass arbitrary JavaScript to +record_init+ and +record_global_init+. Since, by default, the initialization of the map is performed in a callback function, if you want to have a globally accessible variable, you need to use the +global+ version.
 
 Then in your template, you have 2 necessary calls:
-- <tt>GMap#header</tt>: Outputs the inclusion of the JavaScript file from Google to make use of the Google Maps API + a style declaration for VML objects, necessary to display polylines under IE.
+- The static <tt>GMap.header</tt>: Outputs the inclusion of the JavaScript file from Google to make use of the Google Maps API and by default a style declaration for VML objects, necessary to display polylines under IE. This default can be overriddent by passing <tt>:with_vml => false</tt> as option to the +header+ method. You can also pass to this method a <tt>:host</tt> option in order to select the correct key for the location where your app is currently deployed. See the section "Managing the API key(s)" above for more details.
 - <tt>GMap#to_html</tt>: Outputs the initialization code of the map. By default, it outputs the +script+ tags and initializes the map in response to the onload event of the JavaScript window object.
 
 Starting with version 0.2.1, there is no need to manually wire in the body element the response to the +load+ and +unload+ events on the JavaScript window object.
@@ -96,13 +122,56 @@ Of course, with only 3 markers, the whole clusterer thing is totally useless. Us
 - <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)
+Then to add the clusterer to the map at initialization time, you proceed as with a classic overlay:
+	@map.overlay_init clusterer
 
-To add new markers in RJS, you should do this:
+To add new markers in RJS (if the clusterer has been declared globally with overlay_global_init), 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.
 
+====GeoRss Overlay
+An group of markers taken from a Rss feed containing location information in the basic geo (WGS83 lat/lon) vocabulary. See http://www.w3.org/2003/01/geo/ for more details. It is a bit confusing since this vocabulary is very often referred to as GeoRss, while being different from the current GeoRss standardization effort (http://georss.org). Maybe the latter vocabulary will be supported by YM4R in the future but it is not currently the case. The support for GeoRss relies on the MGeoRSS library by Mikel Maron (http://brainoff.com/gmaps/mgeorss.html), although a bit modified, mostly to have the GeoRssOverlay respect the GOverlay API.
+
+<b>Note that the <tt>geoRssOverlay.js</tt> file found in the <tt>YM4R_ROOT/lib/ym4r/google_maps/javascript</tt> folder must be included in the HTML template in order to use this functionality.</b>
+
+Here is how you would use it. First create the overlay at initialization:
+	def index
+	  @map = GMap.new("map_div")
+    	  @map.control_init(:large_map => true)
+    	  @map.center_zoom_init([38.134557,-95.537109],0)
+          @map.overlay_init(GeoRssOverlay.new(url_for(:action => "earthquake_rss"))
+	end
+Since it is not possible to make requests outside the domain where the current page comes from, there is a need for a proxy. With the GeoRssOverlay initialization above, the request will be made by the <tt>earthquake_rss</tt> action, where the address to find the RSS feed will be hardwired:
+	def earthquake_rss
+           result = Net::HTTP.get_response("earthquake.usgs.gov","/eqcenter/recenteqsww/catalogs/eqs7day-M5.xml")
+           render :xml => result.body
+  	end
+If you don't want to hardwire the RSS feed location in an action, you can. But you will have to pass the <tt>:proxy</tt> option to the GeoRssOVerlay constructor. When requesting the RSS feed, the browser will in fact call the proxy with the actual URL of the RSS feed in the +q+ parameter of the request. Here is how you would initialize the GeoRssOVerlay that way:
+	@map.overlay_init(GeoRssOverlay.new("http://earthquake.usgs.gov/eqcenter/recenteqsww/catalogs/eqs7day-M5.xml",
+	:proxy => url_for(:action => "proxy")))
+And here is the <tt>proxy</tt> action:
+	def proxy
+    	    result = Net::HTTP.get_response(URI.parse(@params[:q]))
+    	    render :xml => result.body
+  	end
+You should probably do some checks to ensure the proxy is not abused but it is of your respnsibility.
+
+Another option can be passed to the GeoRssOVerlay constructor to set an icon to be used by the markers of the overlay: <tt>:icon</tt>. By default it is equal to the default icon (the classic red one).
+
+In the view, you should have something like the following:
+	<html>
+	<head><title>Testing GeoRss</title>
+	<%= GMap.header(:with_vml => false) %>
+	<%= javascript_include_tag("geoRssOverlay") %>
+	<%= @map.header_width_height(600,400) %>
+	<%= @map.to_html %>
+	</head>
+	<body>
+	<%= @map.div %>
+	</body>
+	</html> 
+Note the inclusion of the <tt>geoRssOverlay.js</tt> file.
+
 ====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). 
 
@@ -244,19 +313,20 @@ 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 Clusterer class
-- Addition of a PreTiledLayerFromAction class
+- Addition of a GeoRssOverlay to display overlays
+- Addition of a way to manage multiple keys in the same config file
+- Deprecation of the GMap instance method <tt>GMap#header</tt>, replaced with a GMap class method <tt>GMap.header</tt>, taking an option hash as parameter
 
 ==TODO
-- Add support for easy manipulation of external Google Maps-related libraries: Advanced tooltip manipulation, GeoRSS, KML,...
-- Documentation! Documentation! Documentation!
+- Add support for easy manipulation of external Google Maps-related libraries: Advanced tooltip manipulation, KML,...
+- Complete support of the currently standardizing GeoRss vocabulary.
 - 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).
+YM4R bundles JavaScript libraries from John Deck (WMS layers on Google Maps), Jef Poskanzer (Clusterer on Google Maps) and Mikel Maron (GeoRss on Google Maps).
 
 ==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.

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

@@ -0,0 +1,107 @@
+// GeoRssOverlay: GMaps API extension to display a group of markers from
+// a RSS feed
+//
+// Copyright 2006 Mikel Maron (email: mikel_maron yahoo com)
+//
+// The original version of this code is called MGeoRSS and can be found
+// at the following adress:
+// http://brainoff.com/gmaps/mgeorss.html
+//
+// Modified and bundled with YM4R in accordance with the following
+// license:
+//
+// This work is public domain
+
+function GeoRssOverlay(rssurl,icon,proxyurl){
+    this.rssurl = rssurl;
+    this.icon = icon;
+    this.proxyurl = proxyurl;
+    this.request = false;
+    this.markers = [];
+}
+
+GeoRssOverlay.prototype = new GOverlay();
+
+GeoRssOverlay.prototype.initialize=function(map) {
+    this.map = map;
+    this.load();
+}
+
+GeoRssOverlay.prototype.redraw = function(force){
+    //nothing to do : the markers are already taken care of
+}
+
+GeoRssOverlay.prototype.remove = function(){
+    for(var i= 0, len = this.markers.length ; i< len; i++){
+	this.map.removeOverlay(this.markers[i]);
+    }
+}
+
+GeoRssOverlay.prototype.copy = function(){
+    var oCopy = new GeoRssOVerlay(this.rssurl,this.icon,this.proxyurl);
+    oCopy.markers = [];
+    for(var i = 0 , len = this.markers.length ;i < len ; i++){
+	oCopy.markers.push(this.markers[i].copy());
+    }
+    return oCopy;
+}
+
+GeoRssOverlay.prototype.load=function() {
+    if (this.request != false) { 
+	return; 
+    }
+    this.request = GXmlHttp.create();
+    if (this.proxyurl != undefined) {
+	this.request.open("GET",this.proxyurl + '?q=' + encodeURIComponent(this.rssurl),true);
+    } else {
+	this.request.open("GET",this.rssurl, true);
+    }
+    var m = this;
+    this.request.onreadystatechange = function() {
+	m.callback();
+    }
+    this.request.send(null);
+}
+
+GeoRssOverlay.prototype.callback = function() {
+    if (this.request.readyState == 4) {
+	if (this.request.status == "200") {
+	    var xmlDoc = this.request.responseXML;
+	    var items = xmlDoc.documentElement.getElementsByTagName("item");
+	    for (var i = 0; i < items.length; i++) {
+		try {
+		    var marker = this.createMarker(items[i]);
+		    this.markers.push(marker);
+		    this.map.addOverlay(marker);
+		} catch (e) {
+		}
+	    }
+	}
+	this.request = false;
+    }
+}
+
+GeoRssOverlay.prototype.createMarker = function(item) {
+    var title = item.getElementsByTagName("title")[0].childNodes[0].nodeValue;
+    var description = item.getElementsByTagName("description")[0].childNodes[0].nodeValue;
+    var link = item.getElementsByTagName("link")[0].childNodes[0].nodeValue;
+    
+    /* namespaces are handled by spec in moz, not in ie */
+    if (navigator.userAgent.toLowerCase().indexOf("msie") < 0) {
+	var lat = item.getElementsByTagNameNS("http://www.w3.org/2003/01/geo/wgs84_pos#","lat")[0].childNodes[0].nodeValue;
+	var lng = item.getElementsByTagNameNS("http://www.w3.org/2003/01/geo/wgs84_pos#","long")[0].childNodes[0].nodeValue;
+    } else {
+	var lat = item.getElementsByTagName("geo:lat")[0].childNodes[0].nodeValue;
+	var lng = item.getElementsByTagName("geo:long")[0].childNodes[0].nodeValue;
+    }
+    
+    var point = new GLatLng(parseFloat(lat), parseFloat(lng));
+    var marker = new GMarker(point,{'title': title});
+    var html = "<a href=\"" + link + "\">" + title + "</a><p/>" + description;
+    
+    GEvent.addListener(marker, "click", function() {
+	marker.openInfoWindowHtml(html);
+    });
+    
+    return marker;
+}

data/lib/ym4r/google_maps/map.rb

@@ -20,10 +20,21 @@ module Ym4r
         @global_init = []
       end
 
-      #Outputs the header necessary to use the Google Maps API. By default, it also outputs a style declaration for VML elements.
+      #Deprecated. Use the static version instead.
       def header(with_vml = true)
-        a = "<script src=\"http://maps.google.com/maps?file=api&v=2&key=#{API_KEY}\" type=\"text/javascript\"></script>\n"
-        a << "<style type=\"text/css\">\n v\:* { behavior:url(#default#VML);}\n</style>" if with_vml
+        GMap.header(:with_vml => with_vml)
+      end
+
+      #Outputs the header necessary to use the Google Maps API. By default, it also outputs a style declaration for VML elements (can be changed with the option <tt>:with_vml</tt>). You can also pass a host with the <tt>:host</tt> option: If you use Rails, you should pass <tt>:host => @request.host</tt>. This host must have a corresponding API key in the config.yml file. If you don't care about multiple hosts or want to manage the keys yourself, you should not pass the <tt>:host</tt> option and the config.yml should only contain a single API key.
+      def self.header(options = {})
+        options[:with_vml] = true unless options.has_key?(:with_vml)
+        if options.has_key?(:host)
+          api_key = API_KEY[options[:host]]
+        else
+          api_key = API_KEY
+        end
+        a = "<script src=\"http://maps.google.com/maps?file=api&v=2&key=#{api_key}\" type=\"text/javascript\"></script>\n"
+        a << "<style type=\"text/css\">\n v\:* { behavior:url(#default#VML);}\n</style>" if options[:with_vml]
         a
       end
      

data/lib/ym4r/google_maps/mapping.rb

@@ -106,6 +106,7 @@ module Ym4r
     #Used to bind a ruby variable to an already existing JavaScript one. It doesn't have to be a variable in the sense "var variable" but it can be any valid JavaScript expression that has a value.
     class Variable
       include MappingObject
+      
       def initialize(variable)
         @variable = variable
       end
@@ -117,6 +118,8 @@ module Ym4r
       def to_s
         @variable + ";"
       end
+
+      UNDEFINED = Variable.new("undefined")
     end
   end
 end

data/lib/ym4r/google_maps/overlay.rb

@@ -92,7 +92,33 @@ module Ym4r
         a << ")"
       end
     end
-
+    #A basic Latitude/longitude point.
+    class GLatLng 
+      include MappingObject
+      attr_accessor :lat,:lng,:unbounded
+      
+      def initialize(latlng,unbounded = nil)
+        @lat = latlng[0]
+        @lng = latlng[1]
+        @unbounded = unbounded
+      end
+      def create
+        unless @unbounded
+          "new GLatLng(#{@lat},#{@lng})"
+        else
+          "new GLatLng(#{@lat},#{@lng},#{@unbounded})"
+        end
+      end
+    end
+    
+    #A rectangular bounding box, defined by its south-western and north-eastern corners.
+    class GLatLngBounds < Struct.new(:sw,:ne)
+      include MappingObject
+      def create
+        "new GLatLngBounds(#{sw},#{ne})"
+      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
@@ -117,11 +143,15 @@ module Ym4r
     #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
+      attr_accessor :markers,:icon, :max_visible_markers, :grid_size, :min_markers_per_cluster , :max_lines_per_info_box
 
       def initialize(markers = [], options = {})
         @markers = markers
-        @options = options
+        @icon = options[:icon] || GIcon::DEFAULT
+        @max_visible_markers = options[:max_visible_markers] || 150
+        @grid_size = options[:grid_size] || 5
+        @min_markers_per_cluster = options[:min_markers_per_cluster] || 5
+        @max_lines_per_info_box = options[:max_lines_per_info_box] || 10
       end
 
       def create 
@@ -129,40 +159,27 @@ module Ym4r
           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})"
+        "new Clusterer(#{js_marker},#{MappingObject.javascriptify_variable(@icon)},#{MappingObject.javascriptify_variable(@max_visible_markers)},#{MappingObject.javascriptify_variable(@grid_size)},#{MappingObject.javascriptify_variable(@min_markers_per_cluster)},#{MappingObject.javascriptify_variable(@max_lines_per_info_box)})"
       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 
+    class GeoRssOverlay
       include MappingObject
-      attr_accessor :lat,:lng,:unbounded
+      attr_accessor :url, :proxy, :icon
       
-      def initialize(latlng,unbounded = nil)
-        @lat = latlng[0]
-        @lng = latlng[1]
-        @unbounded = unbounded
-      end
-      def create
-        unless @unbounded
-          "new GLatLng(#{@lat},#{@lng})"
-        else
-          "new GLatLng(#{@lat},#{@lng},#{@unbounded})"
-        end
+      def initialize(url, options = {})
+        @url = url
+        @icon = options[:icon] || GIcon::DEFAULT
+        @proxy = options[:proxy] || Variable::UNDEFINED
       end
-    end
-    
-    #A rectangular bounding box, defined by its south-western and north-eastern corners.
-    class GLatLngBounds < Struct.new(:sw,:ne)
-      include MappingObject
-      def create
-        "new GLatLngBounds(#{sw},#{ne})"
+
+      def create 
+        "new GeoRssOverlay(#{MappingObject.javascriptify_variable(@url)},#{MappingObject.javascriptify_variable(@icon)},#{MappingObject.javascriptify_variable(@proxy)})"
       end
     end
 

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.2"
+  s.version = "0.4.1"
   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.2
-date: 2006-06-23 00:00:00 +05:00
+  version: 0.4.1
+date: 2006-07-01 00:00:00 +05:00
 summary: Using Google Maps and Yahoo! Maps from Ruby and Rails
 require_paths: 
 - lib
@@ -60,6 +60,7 @@ files:
 - 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/geoRssOverlay.js
 - lib/ym4r/google_maps/javascript/markerGroup.js
 - lib/ym4r/google_maps/javascript/wms-gs.js
 - tools/tile_image.rb