In the months following publication of the final part of the very popular series on integrating Google Maps into PHP applications, I've spent quite a bit of time working with another popular Web technology: Ruby on Rails. As it turns out, Rails developers have been hard at work creating a few amazing plugins capable of adding powerful mapping capabilities to your applications. In this new series, I'll introduce you to these powerful plugins, showing you a number of tips and tricks along the way.
I'll presume you're familiar with mapping fundamentals, including the basic ideas surrounding the Google mapping API syntax. If you haven't had the opportunity to experiment with the API, take some time to read this tutorial before continuing.
Introducing the YM4R/GM Plugin
Although there's nothing preventing you from linking to Google's mapping JavaScript API and referencing the library directly from your views, jumping between Ruby/Rails syntax and JavaScript can quickly become a tedious affair. The YM4R/GM plugin remedies this issue nicely, abstracting the API calls through Ruby's familiar object-oriented syntax. With it you can do everything from render simple maps to build complex maps complete with custom markers, information windows, and clusters for facilitating the rendering of large numbers of markers.
Installing and Configuring YM4R/GM
To install the YM4R/GM plugin, execute the following command from your project directory:
%>ruby script/plugin install
svn://rubyforge.org/var/svn/ym4r/Plugins/GM/trunk/ym4r_gm
YM4R/GM manages the Google API keys within a file named gmaps_api_key.yml, found in the project's config directory. The developers save you the trouble of having to create your own API key for local testing purposes by including an API key that has already been tied to http://localhost:3000. However, if you're testing on a different host, you'll first need to create an API key and add it to this file (instructions for creating a key are provided in the aforementioned introductory tutorial).
Creating Your First Map
To get acquainted with YM4R/GM's syntax, you can begin by creating the map displayed in Figure 1.
Figure 1: Centering the map over Youngstown, Ohio
As is standard Rails practice, you'll use the controller method to define the map and its features, and the view to render the results. In the following example, you'll define a map in the index controller's index action, complete with a pan/zoom control but minus the map type selector:
def index
# Create a new map object, also defining the div ("map")
# where the map will be rendered in the view
@map = GMap.new("map")
# Use the larger pan/zoom control but disable the map type
# selector
@map.control_init(:large_map => true,:map_type => false)
# Center the map on specific coordinates and focus in fairly
# closely
@map.center_zoom_init([41.023849,-80.682053], 10)
end
Next, in the index action's corresponding view, add the following code:
<html>
<head>
<title>Test</title>
<%= GMap.header %>
<%= @map.to_html %>
</head>
<body>
<%= @map.div(:width => 400, :height => 300) %>
</body>
</html>
The GMap.header call will output references to both the Google Maps API and YM4R/GM JavaScript libraries. The @map.to_html call outputs JavaScript code generated by YM4R/GM according to the specifications set forth in the action. Finally, the @map.div call outputs the map to a div as specified in the action's GMap.new call.
Also, you'll see that the map dimensions are defined in the view rather than the controller. This is keeping with the convention of separating application logic and design; the view designer can choose any dimension he pleases; the map will simply fill to the desired size. The initial zoom level is, however, defined in the controller, although the user can easily subsequently adjust the zoom using the control.
IE 7
Firefox 2.0
