ym4r 0.1.2 → 0.1.3

data/README

@@ -1,15 +1,47 @@
 =YM4R
-This is YM4R 0.1.2. The goal of YM4R (YM4R Maps For Ruby) is to ease the use of the Google Maps and Yahoo! Maps API's (including the Geocoding, Map Image, Traffic and Local Search API's) from Ruby and Rails.
+This is YM4R 0.1.3. The goal of YM4R (which naturally means Yellow Maps For Ruby...) is to ease the use of the Google Maps and Yahoo! Maps API's (including the Geocoding, Map Image, Traffic and Local Search API's) from Ruby and Rails.
 
 ===Operations
 ====Google Maps
-You can use the library to display maps easily from your rails application. Update through RJS is possible. Check out the tutorial at http://thepochisuperstarmegashow.com/2006/06/02/ym4r-georuby-spatial-adapter-demo/
+You can use the library to display Google maps easily with any ruby-based web framework. The version of the API used is v2. The library is engineered so updates to the map through Ajax are possible. I have made available 2 in-depth tutorials to show some of the functionalities of the library and how it can be integrated with GeoRuby and the Spatial Adapter for Rails:
+- http://thepochisuperstarmegashow.com/2006/06/02/ym4r-georuby-spatial-adapter-demo/
+- http://thepochisuperstarmegashow.com/2006/06/03/google-maps-yahoo-traffic-mash-up/
+Following is some notes about using the library:
 
-====Yahoo Maps
-There is at the moment preliminary support for the JS-Flash Yahoo! Maps API, although it is not very polished. Check back next version!
+=====Binding JavaScript and Ruby
+Since the Google Maps API uses JavaScript to create and manipulate a map, most of what the library does is outputting JavaScript, although some convenience methods are provided to simplify some common operations at initialization time. When you create a YM4R mapping object (a Ruby object which includes the MappingObject module) and call methods on it, these calls are converted by the library into JavaScript code. At initialization time, you can pass arbitrary JavaScript code to the <tt>GMap#record_init</tt> and <tt>GMap#record_global_init</tt>.Then, at update time, if you use Ruby-on-Rails as your web framework, you can update your map through RJS by passing the result of the method calls to the <tt>page.send :record,...</tt> method to have it then interpreted by the browser.
+
+For example, here is a typical initialization sequence for a map
+	@map = GMap.new("map_div")
+	@map.center_zoom_init([35.12313,-110.567],12)
+	@map.record_init @map.add_overlay(GMarker.new([35.12878, -110.578],:title => "Hello!"))
+
+While +center_zoom_init+ is one of the rare convenience methods that do not output JavaScript, the +add_overlay+ does. Actually, if you look at the code of the GMap class, you won't find any +add_overlay+ method, although in the documentation of the GMap2 class from the Google Maps API documentation, you will find something about the +addOverlay+ JavaScript method. In fact, when you call on a mapping object an unknow method, it is converted to a javascriptified version of it, along with its arguments, and a string of JavaScript code is output. So the <tt>@map.add_overlay...</tt> above is converted to <tt>"map.addOverlay(new GMarker(GLatLng.new(35.12878, -110.578),{title:\"Hello!\"}))"</tt>, which is then passed to the +record_init+ method of a Ruby GMap object to be later output along with the rest of the initialization code.
+
+=====Initialization of the map
+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 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.
+- <tt>GMap#to_html</tt>: Outputs the initialization code of the map. By default, it outputs the +script+ tags and initializes the map inside a +load+ function. These settings can however be overridden.
+
+You need to have an <tt>onload="load()"</tt> on the body of the HTML document, as well as place a DIV with the chosen ID to have the map correctly displayed.
+
+=====Update of the map
+You are able to update the map through Ajax. For example, in Ruby-on-Rails, you have something called RJS, which sends JavaScript created on the server as a response to an action, which is later interpreted by the browser. It is usually used for visual effects and replacing or adding elements. It can also accept arbitrary JavaScript and this is what YM4R uses.
+
+For example, if you want to add a marker to the map, you need to do a few things. First, you have to bind a Ruby mapping object to the global JavaScript map variable. By default its name is +map+, but you could have overriden that at initialization time. You need to do something like this:
+	@map = Variable.new("map")
++map+ in the Variable constructor is the name of the global JavaScript map variable. Then any method you call on <tt>@map</tt> will be converted in JavaScript to a method called on +map+. In your RJS code, you would do something like this to add a marker:
+	page.send :record, @map.add_overlay(GMarker.new([123123.1,12313.76],:info_window => "Hello again!"))
+
+=====Naming conventions
+The names of the Ruby class follow the ones in the JavaScript Google Maps API v2. To know what is possible to do, you should refer to the documentation available on Google website.
+
+On top of that, you have some convenience methods for initializing the map (in the GMap class). Also, the constructors of some classes accept different types of arguments to be converted later in the correct JavaScript format. For example, the +GMarker+ aclass accepts an array of 2 floats as parameter, in addition of a GLatLng object, to indicate its position. It also facilitates the attribution of an HTML info window, displayed when the user clicks on it, since you can pass to the constructor an options hash with the <tt>:info_window</tt> key and the text to display as the value.
 
 ====Yahoo Maps Building Block API
-Building Block API's (Geocoding, Map Image, Traffic and Local Search) are supported. You have to pass to the +get+ method of the module a hash whose keys are a rubyfied version of the request parameters. You get back a ruby object, with accessors that let you get the returned data in a easy way. You get an exception if not all the parameters have been passed, if the connection to the service could not be made or if the parameters you have passed are of the incorrect value.
+Building Block API's (Geocoding, Map Image, Traffic and Local Search) are supported. You have to pass to the +get+ method of the module a hash whose keys are a rubyfied version of the request parameters detailed in the documentation for these API's. You get back a ruby object, with accessors that let you get the returned data in a easy way. You get an exception if not all the parameters have been passed, if the connection to the service could not be made or if the parameters you have passed are of the incorrect value.
 
 To know what parameters to pass to the +get+ methods and what results you should expect, you should consult the documentation for the building block API's on Yahoo!'s website : http://developer.yahoo.com/maps/index.html#mapsBuildingBlocks . 
 
@@ -22,7 +54,7 @@ Here is an example of request:
                              	  :city => "Cupertino",
                                   :state => "CA",
                                   :zip => "95014")
-+results+ is an array of Geocoding::Result objects. The API can return up to 50 results for one request. Read the documentation page of the Geocoding::Result class to know how to access the data.
++results+ is an array of Geocoding::Result objects. The API can return up to 50 results for one request. You can access the data in the result with attributes which are rubyfied versions of the XML elements forming the answer from the service: See the Yahoo! Geocoding documentation to know what these are and their meanings.
 
 =====Map Image
 Here is an example of request:
@@ -57,6 +89,9 @@ Here is an example of request:
                                    :query => "chinese")
 +results+ is a LocalSearch::ResultSet object (subclass of +Array+), containing LocalSearch::Result objects, each containing information about one hit on the Yahoo! local search.
 
+====Yahoo! Maps JS-Flash API
+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 support for the Google Maps API
 - Addition of preliminary support for the Yahoo! Maps JS-Flash API

data/lib/ym4r/google_maps/api_key.rb

@@ -2,6 +2,7 @@ require 'yaml'
 
 module Ym4r
   module GoogleMaps
+    #The key to be used by the google maps API. It is valid only for the subdiretories of the URL you applied for on this page : http://www.google.com/apis/maps/
     API_KEY = YAML::load_file(File.dirname(__FILE__) + '/config/config.yml')
   end
 end

data/lib/ym4r/google_maps/control.rb

@@ -2,36 +2,42 @@ require 'ym4r/google_maps/mapping'
 
 module Ym4r
   module GoogleMaps
+    #Small map control. Report to the Google Maps API documentation for details.
     class GSmallMapControl
       include MappingObject
       def create
         "new GSmallMapControl()"
       end
     end
+    #Large Map control. Report to the Google Maps API documentation for details.
     class GLargeMapControl
       include MappingObject
       def create
         "new GLargeMapControl()"
       end
     end
+    #Small Zoom control. Report to the Google Maps API documentation for details.
     class GSmallZoomControl
       include MappingObject
       def create
         "new GSmallZoomControl()"
       end
     end
+    #Scale control. Report to the Google Maps API documentation for details.
     class GScaleControl
       include MappingObject
       def create
         "new GScaleControl()"
       end
     end
+    #Map type control. Report to the Google Maps API documentation for details.
     class GMapTypeControl
       include MappingObject
       def create
         "new GMapTypeControl()"
       end
     end
+    #Overview map control. Report to the Google Maps API documentation for details.
     class GOverviewMapControl
       include MappingObject
       def create
@@ -39,7 +45,8 @@ module Ym4r
       end
     end
 
-    #The first argument of the constructor is oneof the following : :top_right, :top_left, :bottom_right, :bottom_left
+    #An object representing a position of a control.
+    #The first argument of the constructor is one of the following : :top_right, :top_left, :bottom_right, :bottom_left.
     class GControlPosition < Struct.new(:anchor,:offset)
       include MappingObject
       def create

data/lib/ym4r/google_maps/helper.rb

@@ -1,17 +1,20 @@
 
 Ym4r::GoogleMaps::GPolyline.class_eval do
+  #Creates a GPolyline object from a georuby line string. Assumes the points of the line strings are stored in Longitude(x)/Latitude(y) order.
   def self.from_georuby(line_string,color = nil,weight = nil,opacity = nil)
     GPolyline.new(line_string.points.collect { |point| GLatLng.new([point.y,point.x])},color,weight,opacity)
   end
 end
 
 Ym4r::GoogleMaps::GMarker.class_eval do
+  #Creates a GMarker object from a georuby point. Accepts the same options as the GMarker constructor. Assumes the points of the line strings are stored in Longitude(x)/Latitude(y) order.
   def self.from_georuby(point,options = {})
     GMarker.new([point.y,point.x],options)
   end
 end
 
 Ym4r::GoogleMaps::GLatLng.class_eval do
+  #Creates a GLatLng object from a georuby point. Assumes the points of the line strings are stored in Longitude(x)/Latitude(y) order.
   def self.from_georuby(point,unbounded = nil)
     GLatLng.new([point.y,point.x],unbounded)
   end

data/lib/ym4r/google_maps/map.rb

@@ -1,12 +1,16 @@
 module Ym4r
   module GoogleMaps 
+    #The Ruby-space class representing the Google Maps API class GMap2.
     class GMap
       include MappingObject
       
+      #A constant containing the declaration of the VML namespace, necessary to display polylines under IE.
       VML_NAMESPACE = "xmlns:v=\"urn:schemas-microsoft-com:vml\""
       
+      #The id of the DIV that will contain the map in the HTML page. 
       attr_reader :container
       
+      #By default the map in the HTML page will be globally accessible with the name +map+.
       def initialize(container, variable = "map")
         @container = container
         @variable = variable
@@ -14,20 +18,24 @@ 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.
       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
         a
       end
 
+      #Outputs a style declaration setting the dimensions of the DIV container of the map. This info can also be set manually in a CSS.
       def header_width_height(width,height)
         "<style type=\"text/css\">\n##{@container} { height: #{height}px;\n  width: #{width}px;\n}\n</style>"
       end
 
+      #Records arbitrary JavaScript code and outputs it during initialization inside the +load+ function.
       def record_init(code)
         @init << code
       end
 
+      #Initializes the controls: you can pass a hash with keys <tt>:small_map</tt>, <tt>:large_map</tt>, <tt>:small_zoom</tt>, <tt>:scale</tt>, <tt>:map_type</tt> and <tt>:overview_map</tt> and a boolean value as the value (usually true, since the control is not displayed by default)
       def control_init(controls = {})
         @init << add_control(GSmallMapControl.new) if controls[:small_map]
         @init << add_control(GLargeMapControl.new) if controls[:large_map]
@@ -37,6 +45,7 @@ module Ym4r
         @init << add_control(GOverviewMapControl.new) if controls[:overview_map]
       end
 
+      #Initializes the initial center and zoom of the map. +center+ can be both a GLatLng object or a 2-float array.
       def center_zoom_init(center, zoom)
         if center.is_a?(GLatLng)
           @init << set_center(center,zoom)
@@ -45,15 +54,17 @@ module Ym4r
         end
       end
 
+      #Records arbitrary JavaScript code and outputs it during initialization outside the +load+ function (ie globally).
       def record_global_init(code)
         @global_init << code
       end
       
+      #Initializes an icon  and makes it globally accessible through the JavaScript variable of name +variable+.
       def icon_init(icon , variable)
         @global_init << icon.declare(variable)
       end
       
-      #allow :script, :no_script and :load in the method parameter. If the :load parameter has been chose, the load_method parameter must be filled too.
+      #Outputs the initialization code for the map. By default, it outputs the script tags, performs the initialization inside a function called +load+ and makes the map globally available.
       def to_html(options = {})
         no_load = options[:no_load]
         load_method = options[:load_method] || "load"
@@ -79,11 +90,13 @@ module Ym4r
         html
       end
       
+      #Outputs in JavaScript the creation of a GMap2 object 
       def create
         "new GMap2(document.getElementById(\"#{@container}\"))"
       end
     end
 
+    #Map types of the map
     module GMapType
       G_NORMAL_MAP = Variable.new("GMapType.G_NORMAL_MAP")
       G_SATELLITE_MAP = Variable.new("GMapType.G_SATELLITE_MAP")

data/lib/ym4r/google_maps/mapping.rb

@@ -1,9 +1,11 @@
 module Ym4r
   module GoogleMaps
+    #The module where all the Ruby-to-JavaScript conversion takes place. It is included by all the classes in the YM4R library.
     module MappingObject
+      #The name of the variable in JavaScript space.
       attr_reader :variable
       
-      #creates javascript code for missing methods
+      #Creates javascript code for missing methods
       def method_missing(name,*args)
         args.collect! do |arg|
           javascriptify_variable(arg)
@@ -11,6 +13,7 @@ module Ym4r
         "#{to_javascript}.#{javascriptify_method(name.to_s)}(#{args.join(",")});\n"
       end
 
+      #Transforms a Ruby object into a JavaScript string
       def javascriptify_variable(arg)
         if arg.is_a?(MappingObject)
           arg.to_javascript
@@ -21,28 +24,29 @@ module Ym4r
         end
       end
       
-      #lifted from rails
+      #Escape string to be used in JavaScript. Lifted from rails.
       def escape_javascript(javascript)
         javascript.gsub(/\r\n|\n|\r/, "\\n").gsub(/["']/) { |m| "\\#{m}" }
       end
       
-      #transform a ruby-type method name (like qsd_fghj) to a Yahoo! Map style one (like qsdFghj)
+      #Transform a ruby-type method name (like add_overlay) to a JavaScript-style one (like addOverlay).
       def javascriptify_method(method_name)
         method_name.gsub(/_(\w)/){|s| $1.upcase}
       end
       
-      #Declare Mapping Object (Map, Tool, Marker,...) of name variable
+      #Declares a Mapping Object bound to a JavaScript variable of name +variable+.
       def declare(variable)
         @variable = variable
         "var #{variable} = #{create};\n"
       end
       
+      #Binds a Mapping object to a previously declared JavaScript variable of name +variable+.
       def assign_to(variable)
         @variable = variable
         "#{variable} = #{create};\n"
       end
       
-      #Returns a Javascript script representing the object
+      #Returns a Javascript code representing the object
       def to_javascript
         unless @variable.nil?
           @variable
@@ -51,16 +55,15 @@ module Ym4r
         end
       end
       
-      #Creates a Mapping Object in Javascript
+      #Creates a Mapping Object in JavaScript.
       #To be implemented by subclasses if needed
       def create
       end
     end
 
-
+    #Used to bind a ruby variable to an already existing JavaScript one.
     class Variable
       include MappingObject
-        
       def initialize(variable)
         @variable = variable
       end

data/lib/ym4r/google_maps/overlay.rb

@@ -2,10 +2,11 @@ require 'ym4r/google_maps/mapping'
 
 module Ym4r
   module GoogleMaps
+    #A graphical marker positionned through geographic coordinates (in the WGS84 datum). An HTML info window can be set to be displayed when the marker is clicked on.
     class GMarker
       include MappingObject
       attr_accessor :point, :options, :info_window, :info_window_tabs
-      #options keys can be : :icon, :clickable and :title: Defaults to G_DEFAULT_ICON, true and empty. :info_window can also be input. However in order to be taken into account, the marker has to be declared at some point
+      #The +points+ argument can be either a GLatLng object or an array of 2 floats. The +options+ keys can be: <tt>:icon</tt>, <tt>:clickable</tt>, <tt>:title</tt>, <tt>:info_window</tt> and <tt>info_window_tabs</tt>. The value of the +info_window+ key is a string of HTML code that will be displayed when the markers is clicked on. The value of the +info_window_tabs+ key is an array of GInfoWindowTab objects.
       def initialize(point, options = {})
         if point.is_a?(Array)
           @point = GLatLng.new(point)
@@ -16,6 +17,7 @@ module Ym4r
         @tab_info_window = options.delete(:info_window_tabs)
         @options = options
       end
+      #Creates a marker: If an info_window or info_window_tabs is present, the response to the click action from the user is setup here.
       def create
         if @options.empty?
           creation = "new GMarker(#{@point.to_javascript})"
@@ -37,6 +39,7 @@ module Ym4r
       end
     end
     
+    #Represents a tab to be displayed in a bubble when a marker is clicked on.
     class GInfoWindowTab < Struct.new(:tab,:content)
       include MappingObject
       def create
@@ -44,17 +47,18 @@ module Ym4r
       end
     end
         
-    #Icon class. You can pass rubyfied versions of the attributes detailed in the Google Maps API documentation. You can initialize global icons to be used in the application by passing a icon object, along with a variable name, to GMap#icon_init. If you want to declare an icon outside this, you will need to declare it first. 
+    #Represents a definition of an icon. You can pass rubyfied versions of the attributes detailed in the Google Maps API documentation. You can initialize global icons to be used in the application by passing a icon object, along with a variable name, to GMap#icon_init. If you want to declare an icon outside this, you will need to declare it first, since the JavaScript constructor does not accept any argument.
     class GIcon
       include MappingObject
       DEFAULT = Variable.new("G_DEFAULT_ICON")
       attr_accessor :options, :copy_base
 
-      #Options can contain all the attributes (in rubifiedformat) of an GIconobject (see Google's doc) + :copy_base, which indicates if the icon is copied from another one
+      #Options can contain all the attributes (in rubyfied format) of a GIcon object (see Google's doc), as well as <tt>:copy_base</tt>, which indicates if the icon is copied from another one.
       def initialize(options = {})
         @copy_base = options.delete(:copy_base)
         @options = options
       end
+      #Creates a GIcon.
       def create
         if @copy_base
           "new GIcon(#{@copy_base.to_javascript})"
@@ -62,6 +66,7 @@ module Ym4r
           "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)
         @options.each do |key,value|
@@ -71,10 +76,11 @@ module Ym4r
       end
     end
      
-    #A polyline. Can take an array of GLatLng or an array of 2D arrays. A method to build a polyline from a GeoRuby linestring is provided in the helper.rb file.
+    #A polyline.
     class GPolyline
       include MappingObject
       attr_accessor :points,:color,:weight,:opacity
+      #Can take an array of +GLatLng+ or an array of 2D arrays. A method to directly build a polyline from a GeoRuby linestring is provided in the helper.rb file.
       def initialize(points,color = nil,weight = nil,opacity = nil)
         if !points.empty? and points[0].is_a?(Array)
           @points = points.collect { |pt| GLatLng.new(pt) }
@@ -85,6 +91,7 @@ module Ym4r
         @weight = weight
         @opacity = opacity
       end
+      #Creates a new polyline.
       def create
         a = "new GPolyline([#{@points.collect{|pt| pt.to_javascript}.join(",")}]"
         a << ",#{javascriptify_variable(@color)}" if @color
@@ -114,6 +121,7 @@ module Ym4r
       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

data/lib/ym4r/google_maps/point.rb

@@ -2,16 +2,18 @@ require 'ym4r/google_maps/mapping'
 
 module Ym4r
   module GoogleMaps
+    #A point in pixel coordinates
     class GPoint < Struct.new(:x,:y)
       include MappingObject
       def create
         "new GPoint(#{x},#{y})"
       end
     end
+    #A rectangular that contains all the pixel points passed as arguments
     class GBounds
       include MappingObject
       attr_accessor :points
-      
+      #Accepts both an array of GPoint and an array of 2-element arrays
       def initialize(points)
         if !points.empty? and points[0].is_a?(Array)
           @points = points.collect { |pt| GPoint.new(pt[0],pt[1]) }
@@ -23,12 +25,12 @@ module Ym4r
         "new GBounds([#{@points.map { |pt| pt.to_javascript}.join(",")}])"
       end
     end
+    #A size object, in pixel space
     class GSize < Struct.new(:width,:height)
       include MappingObject
       def create
         "new GSize(#{width},#{height})"
       end
-
     end
   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.1.2"
+  s.version = "0.1.3"
   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.1.2
-date: 2006-06-03 00:00:00 +05:00
+  version: 0.1.3
+date: 2006-06-04 00:00:00 +05:00
 summary: Using Google Maps and Yahoo! Maps from Ruby and Rails
 require_paths: 
 - lib