google_static_maps_helper 1.3.0 → 1.3.1

data/README.rdoc

@@ -30,6 +30,15 @@ If you are on Rails you can put it in your environment configuration file and wh
     ...
   end
 
+It is also possible to create paths:
+  point1 = {:lng => 1, :lat => 2}
+  point2 = {:lng => 3, :lat => 4}
+
+  GoogleStaticMapsHelper.url_for do
+    path point1, point2, :color => :red, :weight => 7
+  end
+
+..and of course you can add paths and markers in the same map.
 
 = A bit more "low-level" approach instantiating objects yourself
 
@@ -100,6 +109,10 @@ color is what will trigger the creation of polygons for the static map API.
   map << path
   map.url
 
+If you feel like it, you can add points at construction time:
+  GoogleStaticMapsHelper::Path.new(:color => :red, :points => [point1, point2])
+  # ..or
+  GoogleStaticMapsHelper::Path.new(point1, point2, :color => :red)
 
 == TODO
 * Ruby 1.9 support

data/VERSION

@@ -1 +1 @@
-1.3.0
+1.3.1

data/changelog.txt

@@ -1,3 +1,8 @@
+= v.1.3.1
+* Wrote better docs for all classes.
+* You can add points to Paths with Path.new(point, second_point, :color => :red, :fillcolor => :blue)
+* The "DSL" supports adding paths to the map.
+
 = v.1.3.0
 * It is now possible to create Paths which is used to represent lines and polygons in the map. This is not included in the little DSL we have though.
 * The map may now request a URL for a specified image format. As an exampe, set map.format = :jpg to get smaller images (but also less quality).

data/google_static_maps_helper.gemspec

@@ -1,15 +1,15 @@
 # Generated by jeweler
-# DO NOT EDIT THIS FILE
-# Instead, edit Jeweler::Tasks in Rakefile, and run `rake gemspec`
+# DO NOT EDIT THIS FILE DIRECTLY
+# Instead, edit Jeweler::Tasks in Rakefile, and run the gemspec command
 # -*- encoding: utf-8 -*-
 
 Gem::Specification.new do |s|
   s.name = %q{google_static_maps_helper}
-  s.version = "1.2.3"
+  s.version = "1.3.0"
 
   s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
   s.authors = ["Thorbj\303\270rn Hermansen"]
-  s.date = %q{2009-10-25}
+  s.date = %q{2009-10-28}
   s.description = %q{This gem provides a simple interface to the Google Static Maps V2 API.}
   s.email = %q{thhermansen@gmail.com}
   s.extra_rdoc_files = [
@@ -26,11 +26,15 @@ Gem::Specification.new do |s|
      "changelog.txt",
      "google_static_maps_helper.gemspec",
      "lib/google_static_maps_helper.rb",
+     "lib/google_static_maps_helper/location.rb",
      "lib/google_static_maps_helper/map.rb",
      "lib/google_static_maps_helper/marker.rb",
+     "lib/google_static_maps_helper/path.rb",
      "spec/google_static_maps_helper_spec.rb",
+     "spec/location_spec.rb",
      "spec/map_spec.rb",
      "spec/marker_spec.rb",
+     "spec/path_spec.rb",
      "spec/spec_helper.rb"
   ]
   s.homepage = %q{http://github.com/thhermansen/google_static_maps_helper}
@@ -42,7 +46,9 @@ Gem::Specification.new do |s|
     "spec/spec_helper.rb",
      "spec/marker_spec.rb",
      "spec/google_static_maps_helper_spec.rb",
-     "spec/map_spec.rb"
+     "spec/location_spec.rb",
+     "spec/map_spec.rb",
+     "spec/path_spec.rb"
   ]
 
   if s.respond_to? :specification_version then
@@ -58,3 +64,4 @@ Gem::Specification.new do |s|
     s.add_dependency(%q<rspec>, [">= 0"])
   end
 end
+

data/lib/google_static_maps_helper.rb

@@ -4,7 +4,21 @@ require File.dirname(__FILE__) + '/google_static_maps_helper/location'
 require File.dirname(__FILE__) + '/google_static_maps_helper/marker'
 require File.dirname(__FILE__) + '/google_static_maps_helper/path'
 
+# 
+# The Google Static Map Helper provides a simple interface to the
+# Google Static Maps V2 API (http://code.google.com/apis/maps/documentation/staticmaps/).
+#
+# The module is build up of classes maping more or less directly to the entities you'd except:
+# <tt>Map</tt>::      A map is what keeps all of the state of which you'll build a URL for.
+# <tt>Marker</tt>::   One or more markers can be added to the map. A marker can be customized with size, label and color.
+# <tt>Path</tt>::     A path will create lines or polygons in your map.
+# 
+# == About
+#
+# Author:: Thorbjørn Hermansen (thhermansen@gmail.com)
+#
 module GoogleStaticMapsHelper
+  # The basic url to the API which we'll build the URL from
   API_URL = 'http://maps.google.com/maps/api/staticmap'
 
   class OptionMissing < ArgumentError; end # Raised when required options is not sent in during construction
@@ -15,7 +29,35 @@ module GoogleStaticMapsHelper
 
   class << self
     attr_accessor :key, :size, :sensor
-
+    
+    #
+    # Provides a simple DSL stripping away the need of manually instantiating classes
+    #
+    # *NOTE* Paths are not supported by the DSL yet.
+    #
+    # Usage:
+    #
+    #   # First of all, you might want to set your key etc
+    #   GoogleStaticMapsHelper.key = 'your google key'
+    #   GoogleStaticMapsHelper.size = '300x600'
+    #   GoogleStaticMapsHelper.sensor = false
+    #   
+    #   # Then, you'll be able to do:
+    #   url = GoogleStaticMapsHelper.url_for do
+    #     marker :lng => 1, :lat => 2
+    #     marker :lng => 3, :lat => 4
+    #   end
+    #
+    #   # You can send in key, size etc to url_for
+    #   url = GoogleStaticMapsHelper.url_for(:key => 'your_key', :size => [300, 600]) do
+    #     # ...
+    #   end
+    #
+    #   # If you need to, the map object is yielded to the block, so you can do:
+    #   url = GoogleStaticMapsHelper.url_for do |map|
+    #     map.marker object_which_responds_to_lng_lat
+    #   end
+    #
     def url_for(map_options = {}, &block)
       map = Map.new(map_options)
       block.arity < 1 ? map.instance_eval(&block) : block.call(map)

data/lib/google_static_maps_helper/location.rb

@@ -1,17 +1,26 @@
 module GoogleStaticMapsHelper
-
-  # Represents a location (latitude and longitude)
   #
-  # This class will also hold logic like travel_to(heading, distance) which will make
-  # drawing paths and polygons easier.
+  # Represents a location with lat and lng values.
+  # 
+  # This classed is used internally to back up Markers' location
+  # and Paths' points.
+  #
   class Location
-    class NoLngMethod < NoMethodError; end
-    class NoLatMethod < NoMethodError; end
-    class NoLatKey < ArgumentError; end
-    class NoLngKey < ArgumentError; end
+    class NoLngMethod < NoMethodError; end # Raised if incomming object doesnt respond to lng
+    class NoLatMethod < NoMethodError; end # Raised if incomming object doesnt respond to lat
+    class NoLatKey < ArgumentError; end # Raised if incomming Hash doesnt have key lat
+    class NoLngKey < ArgumentError; end # Raised if incomming Hash doesnt have key lng
 
     attr_accessor :lat, :lng
 
+    # :call-seq:
+    #   new(location_object_or_options, *args)
+    #
+    # Creates a new Location which is used by Marker and Path object
+    # to represent it's locations.
+    #
+    # <tt>:args</tt>: Either a location which responds to lat or lng, or a Hash which has :lat and :lng keys.
+    #
     def initialize(*args)
       raise ArgumentError, "Must have some arguments." if args.length == 0
       
@@ -22,7 +31,10 @@ module GoogleStaticMapsHelper
       end
     end
     
-    def to_url
+    #
+    # Returning the location as a string "lat,lng"
+    #
+    def to_url # :nodoc:
       [lat, lng].join(',')
     end
 

data/lib/google_static_maps_helper/map.rb

@@ -1,10 +1,12 @@
 module GoogleStaticMapsHelper
-  # Represents the map we are generating
-  # It holds markers and paths and iterates over them to build the URL
-  # to be used in an image tag.
+  #
+  # The Map keeps track of the state of which we want to build a URL for.
+  # It will hold Markers and Paths, and other states like dimensions of the map,
+  # image format, language etc.
+  #
   class Map
     include Enumerable
-
+    
     MAX_WIDTH = 640
     MAX_HEIGHT = 640
 
@@ -12,15 +14,27 @@ module GoogleStaticMapsHelper
     VALID_MAP_TYPES = %w{roadmap satellite terrain hybrid}
 
     REQUIRED_OPTIONS = [:key, :size, :sensor]
-    OPTIONAL_OPTIONS = [:center, :zoom, :format, :maptype, :mobile, :language, :format, :maptype]
+    OPTIONAL_OPTIONS = [:center, :zoom, :format, :maptype, :mobile, :language]
     
     attr_accessor *(REQUIRED_OPTIONS + OPTIONAL_OPTIONS)
     attr_accessor :width, :height
 
-    # Initialize a new Map object
     #
-    # Takes a hash of options where :key, :size and :sensor are required.
-    # Other options are center, zoom, format, maptype, mobile and language
+    # Creates a new Map object
+    #
+    # <tt>:options</tt>::   The options available are the same as described in
+    #                       Google's API documentation[http://code.google.com/apis/maps/documentation/staticmaps/#Usage].
+    #                       In short, valid options are:
+    #                       <tt>:key</tt>::       Your Google maps API key
+    #                       <tt>:size</tt>::      The size of the map. Can be a "wxh", [w,h] or {:width => x, :height => y}
+    #                       <tt>:sensor</tt>::    Set to true if your application is using a sensor. See the API doc.
+    #                       <tt>:center</tt>::    The center point of your map. Optional if you add markers or path to the map
+    #                       <tt>:zoom</tt>::      The zoom level you want, also optional as center
+    #                       <tt>:format</tt>::    Defaults to png
+    #                       <tt>:maptype</tt>::   Defaults to roadmap
+    #                       <tt>:mobile</tt>::    Returns map tiles better suited for mobile devices with small screens.
+    #                       <tt>:language</tt>::  The language used in the map
+    #
     def initialize(options)
       inject_defaults_from_module_class_attribute!(options)
       validate_required_options(options)
@@ -30,6 +44,9 @@ module GoogleStaticMapsHelper
       @map_enteties = []
     end
 
+    #
+    # Builds up a URL representing the state of this Map object
+    #
     def url
       raise BuildDataMissing, "We have to have markers, paths or center and zoom set when url is called!" unless can_build?
       
@@ -56,10 +73,19 @@ module GoogleStaticMapsHelper
       out
     end
 
+    #
+    # Returns all the markers which this map holds
+    #
     def markers
       @map_enteties.select {|e| e.is_a? Marker}
     end
 
+    #
+    # Returns the markers grouped by it's label, color and size.
+    #
+    # This is handy when building the URL because the API wants us to
+    # group together equal markers and just list the position of the markers thereafter in the URL.
+    #
     def grouped_markers
       markers.inject(Hash.new {|hash, key| hash[key] = []}) do |groups, marker|
         groups[marker.options_to_url_params] << marker
@@ -67,10 +93,16 @@ module GoogleStaticMapsHelper
       end
     end
 
+    # 
+    # Returns all the paths which this map holds
+    #
     def paths
       @map_enteties.select {|e| e.is_a? Path}
     end
     
+    #
+    # Pushes either a Marker or a Path on to the map
+    #
     def <<(entity)
       @map_enteties << entity
       @map_enteties.uniq!
@@ -89,11 +121,26 @@ module GoogleStaticMapsHelper
       @map_enteties.length
     end
 
-    def marker(*args)
-      marker = Marker.new(*args)
-      self << marker
+    #
+    # Used internally to make the DSL work. Might be changed at any time
+    # to make a better implementation.
+    #
+    def marker(*args) # :nodoc:
+      self << Marker.new(*args)
+    end
+
+    #
+    # Used internally to make the DSL work. Might be changed at any time
+    #
+    def path(*args) # :nodoc:
+      self << Path.new(*args)
     end
     
+    #
+    # Sets the size of the map
+    #
+    # <tt>size</tt>::   Can be a "wxh", [w,h] or {:width => x, :height => y}
+    #
     def size=(size)
       unless size.nil?
         case size
@@ -112,11 +159,19 @@ module GoogleStaticMapsHelper
         self.height = height if height
       end
     end
-
+    
+    #
+    # Returns size as a string, "wxh"
+    #
     def size
       [@width, @height].join('x')
     end
-
+    
+    #
+    # Defines width and height setter methods
+    #
+    # These methods enforces the MAX dimensions of the map
+    #
     [:width, :height].each do |name|
       define_method "#{name}=" do |dimension|
         dimension = dimension.to_i
@@ -126,11 +181,22 @@ module GoogleStaticMapsHelper
       end
     end
 
+
+    #
+    # Sets the format of the map
+    #
+    # <tt>format</tt>:: Can be any values included in VALID_FORMATS.
+    #
     def format=(format)
       @format = format.to_s
       raise UnsupportedFormat unless VALID_FORMATS.include? @format
     end
 
+    #
+    # Sets the map type of the map
+    #
+    # <tt>type</tt>:: Can be any values included in VALID_MAP_TYPES.
+    #
     def maptype=(type)
       @maptype = type.to_s
       raise UnsupportedMaptype unless VALID_MAP_TYPES.include? @maptype
@@ -138,6 +204,9 @@ module GoogleStaticMapsHelper
 
 
     private
+    #
+    # Returns an answer for if we can build the URL or not
+    #
     def can_build?
       !@map_enteties.empty? || (center && zoom)
     end

data/lib/google_static_maps_helper/marker.rb

@@ -1,9 +1,8 @@
 module GoogleStaticMapsHelper
-  # Simple wrapper around an object which should respond to lat and lng.
-  # The wrapper keeps track of additional parameters for the Google map
-  # to be used, like size color and label.
+  #
+  # A marker object is representing a marker with a customizable label, color and size.
+  #
   class Marker
-    # These options are the one we build our parameters from
     DEFAULT_OPTIONS = {
       :color => 'red',
       :size => 'mid',
@@ -12,33 +11,41 @@ module GoogleStaticMapsHelper
 
     attr_accessor :location, *DEFAULT_OPTIONS.keys
 
-    # Initialize a new Marker 
-    # 
-    # Can wither take an object which responds to lng and lat
-    # GoogleStaticMapsHelper::Marker.new(location)
+    # :call-seq:
+    #   new(location_object_or_options, *args)
+    #
+    # Creates a new Marker object. A marker object will, when added to a Map, represent
+    # one marker which you can customize with color, size and label.
+    #
+    # <tt>:location_object_or_options</tt>::  Either an object which responds to lat and lng or simply a option hash
+    # <tt>:args</tt>::                        A hash of options. Can have keys like <tt>:color</tt>,
+    #                                         <tt>:size</tt>, and <tt>:label</tt>.
+    #                                         See Google's API documentation[http://code.google.com/apis/maps/documentation/staticmaps/#MarkerStyles] for more information.
+    #                                         If a location object hasn't been given you must also include <tt>:lat</tt>
+    #                                         and <tt>:lng</tt> values.
+    #
     #
-    # Or it can take a has which includes lng and lat
-    # GoogleStaticMapsHelper::Marker.new(:lng => 1, :lat => 2)
+    # Usage:
+    #
+    #   # Sets location via object which responds to lng and lat
+    #   GoogleStaticMapsHelper::Marker.new(location {:label => :a})
+    #   
+    #   # ..or include the lng and lat in the option hash
+    #   GoogleStaticMapsHelper::Marker.new(:lng => 1, :lat => 2, :label => :a)
     #
-    # You can also send in options like color, size and label in the hash,
-    # or as a secnond parameter if the first was an object.
     def initialize(*args)
       raise ArgumentError, "Must have one or two arguments." if args.length == 0
-
-      if args.first.is_a? Hash
-        extract_location_from_hash!(args.first)
-      else
-        extract_location_from_object(args.shift)
-      end
-
+      extract_location!(args)
       options = DEFAULT_OPTIONS.merge(args.shift || {})
       validate_options(options)
       options.each_pair { |k, v| send("#{k}=", v) }
     end
 
-    # Returns a string wich is what Google Static map is using to
-    # set the style on the marker. This ill include color, size and label
-    def options_to_url_params
+    # 
+    # Returns a string representing this marker
+    # Used by the Map when building url.
+    #
+    def options_to_url_params # :nodoc:
       params = DEFAULT_OPTIONS.keys.map(&:to_s).sort.inject([]) do |params, attr|
         value = send(attr)
         params << "#{attr}:#{URI.escape(value)}" unless value.nil?
@@ -48,35 +55,35 @@ module GoogleStaticMapsHelper
       params.join('|')
     end
 
-    # Concatination of lat and lng value, used when building the url
-    def location_to_url
+    # 
+    # Concatenation of lat and lng value. Used when building URLs and returns them in correct order
+    #
+    def location_to_url # :nodoc:
       @location.to_url
     end
     
-    def label
+    def label # :nodoc:
       @label.to_s.upcase if @label
     end
 
-    def color
+    def color # :nodoc:
       @color.downcase if @color
     end
 
 
+    #
+    # Proxies calls to the internal object which keeps track of this marker's location.
+    # So, if @location responds to method missing in this object, it will respond to it.
+    #
     def method_missing(method, *args)
       return @location.send(method, *args) if @location.respond_to? method
       super
     end
 
     private
-    def extract_location_from_hash!(location_hash)
-      to_object = {}
-      to_object[:lat] = location_hash.delete :lat if location_hash.has_key? :lat
-      to_object[:lng] = location_hash.delete :lng if location_hash.has_key? :lng
-      @location = Location.new(to_object)
-    end
-
-    def extract_location_from_object(location)
-      @location = Location.new(location)
+    def extract_location!(args)
+      @location = Location.new(*args)
+      args.shift unless args.first.is_a? Hash
     end
 
     def validate_options(options)

data/lib/google_static_maps_helper/path.rb

@@ -1,4 +1,8 @@
 module GoogleStaticMapsHelper
+  #
+  # A Path is used to draw things in the map, either lines or Polygons.
+  # It is build up of points and if a fill color is set you'll get a Polygon.
+  #
   class Path
     include Enumerable
 
@@ -6,13 +10,33 @@ module GoogleStaticMapsHelper
 
     attr_accessor :points, *OPTIONAL_OPTIONS
 
-    def initialize(options = {})
+    #
+    # Creates a new Path which you can push points on to to make up lines or polygons
+    #
+    # The following options are available, for more information see the 
+    # Google API documentation[http://code.google.com/apis/maps/documentation/staticmaps/#Paths].
+    #
+    # <tt>:weight</tt>::    The weight is the thickness of the line, defaults to 5
+    # <tt>:color</tt>::     The color of the border can either be a textual representation like red, green, blue, black etc
+    #                       or as a 24-bit (0xAABBCC) or 32-bit hex value (0xAABBCCDD). When 32-bit values are
+    #                       given the two last bits will represent the alpha transparency value.
+    # <tt>:fillcolor</tt>:: With the fill color set you'll get a polygon in the map. The color value can be the same
+    #                       as described in the <tt>:color</tt>. When used, the static map will automatically create
+    #                       a closed shape.
+    # <tt>:points</tt>::    An array of points. You can mix objects responding to lng and lat, and a Hash with lng and lat keys.
+    #
+    def initialize(*args)
       @points = []
-      options.each_pair {|k, v| send("#{k}=", v)}
+    
+      extract_options!(args)
+      add_points(args)
     end
 
-    
-    def url_params
+    #
+    # Returns a string representation of this Path
+    # Used by the Map when building the URL
+    #
+    def url_params # :nodoc:
       raise BuildDataMissing, "Need at least 2 points to create a path!" unless can_build?
       out = 'path='
      
@@ -30,6 +54,11 @@ module GoogleStaticMapsHelper
     end
 
   
+    #
+    # Sets the points of this Path.
+    # 
+    # *WARNING* Using this method will clear out any points which might be set.
+    #
     def points=(array)
       raise ArgumentError unless array.is_a? Array
       @points = []
@@ -48,20 +77,44 @@ module GoogleStaticMapsHelper
       length == 0
     end
 
+    #
+    # Pushes a new point into the Path
+    #
+    # A point might be a Hash which has lng and lat as keys, or an object responding to
+    # lng and lat. Any points pushed in will be converted internally to a Location
+    # object.
+    #
     def <<(point)
       @points << ensure_point_is_location_object(point)
       @points.uniq!
       self
     end
 
+
     private
+    #
+    # Extracts the lng and lat values from incomming point and creates a new Location
+    # object from it.
+    #
     def ensure_point_is_location_object(point)
       return point if point.instance_of? Location
       Location.new(point)
     end
-
+    
+    # 
+    # Do we have enough points to build a path?
+    #
     def can_build?
       length > 1
     end
+
+    def extract_options!(args)
+      options = args.last.is_a?(Hash) ? args.pop : {}
+      options.each_pair {|k, v| send("#{k}=", v)}
+    end
+
+    def add_points(points)
+      points.each {|point| self << point}
+    end
   end
 end

data/spec/google_static_maps_helper_spec.rb

@@ -29,6 +29,17 @@ describe GoogleStaticMapsHelper do
         out.should include('size=600x400')
       end
 
+      it "should be able to add paths" do
+        point = {:lat => 1, :lng => 2}
+        point2 = {:lat => 3, :lng => 4}
+
+        out = GoogleStaticMapsHelper.url_for do
+          path point, point2, :color => :red
+        end
+
+        out.should include('path=color:red|1,2|3,4')
+      end
+
       it "should be possible to use inside a class, using attributes of that class" do
         class TestingClass
           attr_reader :location

data/spec/path_spec.rb

@@ -19,6 +19,23 @@ describe GoogleStaticMapsHelper::Path do
         path.send(attribute).should == @@options.fetch(attribute)
       end
     end
+
+    describe "points" do
+      before do
+        @point = GoogleStaticMapsHelper::Location.new(:lat => 1, :lng => 2)
+        @point2 = GoogleStaticMapsHelper::Location.new(:lat => 1, :lng => 2)
+      end
+
+      it "should be able to add points via options during initialization" do
+        path = GoogleStaticMapsHelper::Path.new(@@options.merge(:points => [@point, @point2]))
+        path.points.should == [@point, @point2]
+      end
+
+      it "should be able to add points before option hash" do
+        path = GoogleStaticMapsHelper::Path.new(@point, @point2, @@options)
+        path.points.should == [@point, @point2]
+      end
+    end
   end
 
   describe "points" do

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification 
 name: google_static_maps_helper
 version: !ruby/object:Gem::Version 
-  version: 1.3.0
+  version: 1.3.1
 platform: ruby
 authors: 
 - "Thorbj\xC3\xB8rn Hermansen"
@@ -9,7 +9,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2009-10-28 00:00:00 +01:00
+date: 2009-10-31 00:00:00 +01:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency