README

======================================================
GoogleMaps
======================================================
a rails plugin that and makes generating google maps easy as pie
NOTE:  This is a forked version of the original google_maps plugin by
bhedana:  http://github.com/bhedana/google_maps/

I have added static images from google's static image API, as well as
some basic street view functionality.

Additionally I have added the ability to use google map's premier ssl API,
if you have access or preference for that.

======================================================
INSTALL
======================================================
script/plugin install git://github.com/westin/google_maps.git




======================================================
PLUGIN CONFIGURATION
======================================================
1 - Set your Google Maps API Key in environment.rb (or somewhere else if you'd prefer)
	I'd suggest copying the configuration code out of your environment.rb and into an initializer named geokit

  # This key is good for localhost:3000, signup for more at http://www.google.com/apis/maps/signup.html
  GOOGLE_APPLICATION_ID = "ABQIAAAA3HdfrnxFAPWyY-aiJUxmqRTJQa0g3IQ9GZqIMmInSLzwtGDKaBQ0KYLwBEKSM7F9gCevcsIf6WPuIQ"

  # If you're using google map's premier service (which uses SSL connections) then set the environment variable as:
  GOOGLE_CLIENT_ID = {your_client_id}

======================================================
MAP CONTROLS
======================================================

maps_controller.rb
--------------------------
class MapsController < ApplicationController
	def	show
		@map = GoogleMap::Map.new
		
		# define control types shown on map
		@map.controls = [ :large, :scale, :type ]
		# valid controls options include
		# :large 
		# :small 
		# :overview
		# :large_3d
		# :scale
		# :type
		# :menu_type
		# :hierachical_type
		# :zoom
		# :zoom_3d
		# :nav_label
	        	
		# allow user to double click to zoom
		@map.double_click_zoom = true
		
		# not certain what this does
		@map.continuous_zoom = false
		
		# allow user to scroll using mouse wheel?
		@map.scroll_wheel_zoom = false
		
	end
end

======================================================
MAP CENTERING AND ZOOM
======================================================

maps_controller.rb
--------------------------
class MapsController < ApplicationController
	def	show
		@map = GoogleMap::Map.new
		@map.center = GoogleMap::Point.new(47.6597, -122.318) #SEATTLE WASHINGTON
		@map.zoom = 10 #200km
	end
end


======================================================
MAP CENTERING USING BOUNDS
======================================================

maps_controller.rb
--------------------------
class MapsController < ApplicationController
	def	show
		@map = GoogleMap::Map.new
		@map.bounds =  [GoogleMap::Point.new(47.6597, -121.318), GoogleMap::Point.new(48.6597, -123.318)] #SEATTLE WASHINGTON 50KM
		# static_img does not support bounds
	end
end



======================================================
SIMPLE MARKER USAGE
======================================================

maps_controller.rb
--------------------------
class MapsController < ApplicationController
	def	show
		@map = GoogleMap::Map.new
  		@map.markers << GoogleMap::Marker.new(	:map => @map, 
                                     			:lat => 47.6597, 
                                     			:lng => -122.318,
                                     			:html => 'My House')
	end
end

maps/show.html.erb
-------------------------
  <%= @map.to_html %>
  <div style="width: 500px; height: 500px;">
    <%= @map.div %>
  </div>
  
  <!-- OR -->
  <!-- Gets the url for a static image with this marker (:html not supported) -->
  <img src="<%=@map.static_img%>" />


======================================================
Advanced Marker Usage
======================================================

# Available icon classes:
# GoogleMap::LetterIcon.new(@map, 'A') # letter must be uppercase
# GoogleMap::SmallIcon.new(@map, 'yellow')

maps_controller.rb
--------------------------
class MapsController < ApplicationController
	def	show
		@map = GoogleMap::Map.new
  		@map.markers << GoogleMap::Marker.new(	:map => @map, 
												:icon => GoogleMap::SmallIcon.new(@map, 'blue'),
												:lat => 47.6597, 
												:lng => -122.318,
												:html => 'My House',
												:marker_icon_path => '/path/to/image',
												:marker_hover_text => 'String to show on Mouse Over',
												:open_infoWindow => true #opens marker by default
												)
	end
end 

maps/show.html.erb
-------------------------
  <%= @map.to_html %>
  <div style="width: 500px; height: 500px;">
    <%= @map.div %>
  </div>



maps_controller.rb
--------------------------
# Note that html, marker_icon_path, and marker_hover_text are not supported
# by static_img.  Likewise the following size, and color parameters do nothing
# for dynamic maps.
class MapsController < ApplicationController
  def show
    @map = GoogleMap::Map.new
    @map.markers << GoogleMap::Marker.new( :map => @map,
                      :lat => 47.6597,
                      :lng => -122.318,
                      :size => 'mid',  # Options:  tiny, mid, small
                      :color => 'red',
                      :icon => GoogleMap::LetterIcon.new('s') ) # Alphanumeric character
  end
end

maps/show.html.erb
-----------------------
  <!-- Creates a static image with the marker as specified -->
  <img src="<%=@map.static_img%>" />


======================================================
PLOTTING POLYLINE ROUTES
======================================================

maps_controller.rb
--------------------------
class MapsController < ApplicationController
	def	show
		@map = GoogleMap::Map.new
  		
		# plot points for polyline
        vertices = []
        object.gpxroute.gpxtrackpoints.each do |p|
          vertices << GoogleMap::Point.new(p.lat, p.lon)
        end
		
  		# plot polyline
  		# static_img supports the :fill_color option, but
  		# to_js doesn't use it.
		@map.overlays << GoogleMap::Polyline.new(	:map => @map, 
													:color=>'#FF0000', 
													:weight=>'2', 
													:opacity=>'.5', 
													:vertices=>vertices,
													:fill_color=>'#FF9999'
													)
	end
end

maps/show.html.erb
-------------------------
  <%= @map.to_html %>
  <div style="width: 500px; height: 500px;">
    <%= @map.div %>
  </div>
  <!-- Creates a static image with the route displayed -->
  <img src="<%=@map.static_img%>" />

  
======================================================
USING GOOGLE MAPS PREMIER SSL API
======================================================
maps_controller.rb
------------------------
class MapsController < ApplicationController
  def show
    @map = GoogleMap::Map.new(:center => GoogleMap::Point.new(47.6597, -122.318))
    
    # This is all you need, url's will now use the premier api and https
    # Don't forget to set a GOOGLE_CLIENT_ID in your environment file.
    @map.ssl = true
  end
end

======================================================
STREET VIEW OVERLAY 
(Static images currently cannot render street views,
maybe static image API 3.0?)
======================================================

maps_controller.rb
------------------------
class MapsController < ApplicationController
  def show
    # Creates a map that has a street view overlay
    # indicating with blue outlines which streets
    # currently support street view.
    @map = GoogleMap::Map.new(
      :overlays => [GoogleMap::StreetViewOverlay()],
      :center => GoogleMap::Point.new(47.6597, -122.318)
      :zoom => 10
    )
  end
end


maps/show.html.erb
--------------------------
  <%= @map.to_html %>
  <div style="width: 500px; height: 500px;">
    <%= @map.div %>
  </div>
  
  
  
=====================================================
STREET VIEW
=====================================================

maps_controller.rb
-----------------------
class MapsController < ApplicationController
  def show
    @map = GoogleMap::Map.new()
    
    # Adding the 'street_view' control will enable users to click anywhere on the map
    # and have the street view div re-populate with the clicked position.
    # If the location doesn't have a street view for it, nothing happens.
    @map.controls << [:street_view]
    
    # Consider adding the street view overlay so users know what they can click on
    @map.overlays << GoogleMap::StreetViewOverlay()
    
    # You don't have to set map.street_view to have street view for your map.
    # Setting the street view will setup your initial, default view in the div
    # before any user clicks or other interaction.  yaw, pitch, and zoom can't be changed just yet
    # dynamically from the generated javascript, only in this initial setup.
    # Note that the street viewer that google creates provides the ability for users
    # to adjust the angle, pitch, and zoom themselves with simple mouse interaction.
    #
    # If you don't set street_view, but still send the :street_view control, the street view
    # div will start out empty and will appear after you click somewhere on the map.
    #
    # Likewise, if you set this street_view object but not the :street_view control,
    # you will get a default street view at the location set, but interaction with the map
    # won't affect the view itself.
    @map.street_view = GoogleMap::StreetView.new(
      :map => @map, 
      :lat => 47.6597, 
      :lng => -122.318,
      :yaw => 95.3487,  # rotation angle in degrees.  0 is true north, 90 is true east.
      :pitch => -20, # Angle 'up' or 'down', 90 is straight up, -90 is straight down.
      :zoom => 0 # Zoom level, 0 is fully zoomed out
    ) 
    
    # Creating a marker on your map with the :street_view control or a street_view object set
    # will cause the street view to automatically change to the location of the marker when a user
    # clicks on it if street view data is available for it (must set the :click_street_view option to true,
    # defaults to false)
    @map.markers << GoogleMap::Marker.new( :map => @map, :lat => 48.6597, :lng => -123.318, :click_street_view => true )
  end
end

Even if you didn't set a street_view object implicitly, setting the control :street_view
will give you a shell street_view object to still collect a div tag for.

If a user doesn't have flash, a message to visit the adobe website will appear in the noflash_div tag.
maps/show.html.erb
------------------------
  <%= @map.to_html %>
  <div style="width: 500px; height: 1000px;">
    <%= @map.div('100%', '50%') %>
    <%= @map.street_view.div('100%', '50%') %>
  </div>
  <div style="width: 500px;">
    <%= @map.noflash_div %>
  </div>
  
  
====================================================
 STREET VIEW - SWAP OUT SAME WINDOW
====================================================

maps_controller.rb
----------------------
class MapsController < ApplicationController
  def show
    lat = 47.6597
    lng = -122.318
    @map = GoogleMap::Map.new
    
    # Notes:
    #   For the street view object, be sure you set the dom id to the exact same dom id as the map itself, as below
    #   Also, if you want to be able to close the street view and view map view again (swap back and forth),
    #   make sure you add the close control => true for the street view object.  Making your dom id's equal will
    #   allow your street view to use the same div tag as your map (it will appear above the map).
    @map.street_view = GoogleMap::StreetView.new(:map => @map, :dom_id => @map.dom_id, :close_control => true)
    
    @map.markers << GoogleMap::Marker.new(:map => @map, :lat => lat, :lng => lng, :html => "My House!")
    
    # the visible option sets the starting visibility of the overlay, which will be toggled by the control
    # defined later.
    @map.overlays << GoogleMap::StreetViewOverlay.new(:map => @map, :visible => false)
    
    # This is a custom control for the map view.  It creates a button in the upper-right that will activate the
    # street view defined by the map's street_view property.  It will always open up the street view in the same
    # location, as defined by lat and lng.  Future changes may give it the ability to change this, or to have a separate
    # street view link on each marker etc, but for now if you define this control, you also define where it sets the street
    # view.
    # the face_point option will cause the street viewer to automatically find the nearest street view, and face the camera towards
    # the given location.  Defaults to false (faces true north instead)
    street_view_button = GoogleMap::StreetViewButtonControl.new(:map => @map, :lat => lat, :lng => lng, :text => "See Street", :face_point => true)
    
    # Another custom control to have the ability to toggle on and off the street view overlay defined by that object in overlays
    # the icon option let's you set a custom image for the control.  For both of these custom controls :text, and :icon are both
    # optional - They have default text they display if not defined.
    street_view_overlay_control = GoogleMap::StreetViewOverlayControl.new(:map => @map, :icon => '/images/street_overlay.png')
    
    # Note that the controls property can now contain both pre-defined symbols, predefined 'custom' control objects, and any
    # custom control objects that you want to define yourself.
    @map.controls = [:zoom, street_view_button, street_view_overlay_control]
    
    # You may also wish to add the :street_view symbol control to controls which will additionally allow you to click on the map to
    # activate street view (and close street view with the street view's close control)
  end
end

maps/show.html.erb
-------------------
  <%= @map.to_html %>
  <div style='width: 500px; height: 500px;'>
    <%= @map.div %>
  </div>
  <div style="width: 500px;">
    <%= @map.noflash_div %>
  </div>