Terry Martin edited this page Dec 21, 2016 · 55 revisions

Retrieving data

Markers are the core of the gmaps4rails gem which provides useful methods to retrieve all data from the model bearing acts_as_gmappable.

Say your User model contains acts_as_gmappable, then:

@markers = User.all.to_gmaps4rails    #@markers contain valid json to pass to the view


@markers = User.your_scope.to_gmaps4rails    #@markers contain valid json to pass to the view

Customize what is displayed

Info windows

Standard infowindows

To add an infowindow (visible when you click a marker), add this method in your model (or better, in controller):

    def gmaps4rails_infowindow
      # add here whatever html content you desire, it will be displayed when users clicks on the marker

The infowindow can contain whatever you want. Example:

    def gmaps4rails_infowindow
      "<img src=\"#{self.picture}\"> #{}"

If you want to use your partials, see this section

If you want your infowindows to be created client side (with stuff like mustache or handlebars).

Create your js function and make it return the html you need. It takes one parameter, the marker_container containing all information related to the current marker. This function will be evaluated for each marker of the map. = function(marker_container){
  //whatever you need
  return your_html;

Custom infowindows

Gmaps4rails now supports the InfoBox plugin you see here.

Here are the steps to reproduce the example in the source.

  1. create your css class for the infobox (it's a div)

     .yellow { border: 1px solid black; margin-top: 8px; background: yellow; padding: 5px; }
  2. Pass the options the plugin provides to gmaps4rails: = function(boxText) {
      return {
         content: boxText
        ,disableAutoPan: false
        ,maxWidth: 0
        ,pixelOffset: new google.maps.Size(-140, 0)
        ,zIndex: null
        ,boxStyle: { 
          background: "url('') no-repeat"
          ,opacity: 0.75
          ,width: "280px"
        ,closeBoxMargin: "10px 2px 2px 2px"
        ,closeBoxURL: ""
        ,infoBoxClearance: new google.maps.Size(1, 1)
        ,isHidden: false
        ,pane: "floatPane"
        ,enableEventPropagation: false
  3. call gmaps4rails

    <%= gmaps("markers" => {"data" => @json, "options" => {"custom_infowindow_class" => "yellow" } }) %> 

Add a title to your marker

To add a title (visible when you are over a marker), add this method in your model (or better, in controller):

    def gmaps4rails_title
      # add here whatever text you desire

Customize each marker

Include this method in your model (or better, in controller) to customize markers:

def gmaps4rails_marker_picture
  "picture" => ,          # string,  mandatory
   "width" =>  ,          # integer, mandatory
   "height" => ,          # integer, mandatory
   "marker_anchor" => ,   # array,   facultative, [0, 0] is the upper left corner 
                          #                       and [width, height] is the bottom right
   "shadow_picture" => ,  # string,  facultative
   "shadow_width" => ,    # string,  facultative
   "shadow_height" => ,   # string,  facultative
   "shadow_anchor" => ,   # string,  facultative
   "rich_marker" =>   ,   # html, facultative
                          # If used, all other attributes skipped except "marker_anchor". This array is used as follows:
                          # [ anchor , flat ] : flat is a boolean, anchor is an int. 
                          # See doc here: 


  • the picture should be properly resized.

  • you could leverage the google's chart api to have customized marker, see answer on stackoverflow


def gmaps4rails_marker_picture
   "picture" => "/images/#{name}.png",
   "width" => 20,
   "height" => 20,
   "marker_anchor" => [ 5, 10],
   "shadow_picture" => "/images/morgan.png" ,
   "shadow_width" => "110",
   "shadow_height" => "110",
   "shadow_anchor" => [5, 10],

Example with rich marker:

def gmaps4rails_marker_picture
    "rich_marker" =>  "<div class='my-marker'>It works!<img height='30' width='30' src=''/></div>"

And enable in your view:

<%= gmaps("markers" => {"data" => @json, "options" => {"rich_marker" => true } }) %>

Create a list of your Markers in your html

in your model (or better, in controller)

def gmaps4rails_sidebar
  "<span class="foo">#{name}</span>" #put whatever you want here

In your view, you must add a <ul>

<ul id="markers_list">  </ul>

and call gmaps4rails properly:

<%= gmaps("markers" => {"data" => @json, "options" => {"list_container" => "markers_list" } }) %>

Creating your own json


If you want to use your own json to initialize the map, create your json with the following attributes

    @markers = '[
             {"description": "", "title": "", "sidebar": "", "lng": "", "lat": "", "picture": "", "width": "", "height": ""},
             {"lng": "", "lat": "" }

Only lat and lng are mandatory. (previous to 0.10.x they were latitude and longitude)

You can customize any single marker with the other attributes:

  • picture, width and height are related to the marker

  • description could contain whatever html you want to be displayed in the infowindow.

  • sidebar contains the data to be displayed in the list of marker

Displaying your markers


In your view:

<%= gmaps("markers" => { "data" => @markers }) %>


In your view:

<%= gmaps4rails(@markers) %>

This displays the markers with auto-adjust option set to true. No other option could be passed this way.


Options for markers are:

  • marker_picture

  • marker_width

  • marker_length

  • do_clustering, to cluster markers, default to false

  • clusterer_gridSize, the more the quicker but the less precise, default to 50

  • clusterer_maxZoom, define at which zoom level clusterer is disabled, default to 10

  • draggable, allow drag markers, default to false

  • randomize: false, Google maps can't display two markers which have the same coordinates. This randomizer enables to prevent this situation from happening.

  • max_random_distance: 100 in meters. Each marker coordinate could be altered by this distance in a random direction

  • list_container: null, if a string is passed, it will be assumed that it's the id of the <ul> in which you want the list of markers to be included. Define gmaps4rails_sidebar method in your model to customize what you want to be displayed in each <li>

  • custom_clusterer_pictures: see help below

These options set default styling for your markers.

You can pass options this way:

<%= gmaps("markers" => { "data" => @markers, "options" => { "picture" => your_pic, "width" => 22, "length" => 32 } }) %>

Disable Clusterer Icons

Simply un-define the default clusterer with:

handler ="Google", { markers: { clusterer: undefined  } })

Customize Clusterer Images

You can customize the pics used by the clusterer by setting the js function in your code.

Here is an example: = function() {
  var url = "";
  return [{
    textSize: 10, 
    textColor: '#ff0000',
    url: url + 'heart30.png',
    height: 26,
    width: 30,
    textSize: 14, 
    textColor: '#ffff00',
    url: url + 'heart40.png', 
    height: 35,
    width: 40,
    textSize: 18, 
    textColor: '#0000ff',
    url: url + 'heart50.png',
    width: 50,
    height: 44,

Another way to do it is to specify custom clusterer images in your

  1. Navigate to: app/assets/javascripts/gmaps4rails/
  2. Change the @customClusterer value from false, to the custom image values you want to use.

Here is an example with three custom clusterer image sizes:

@customClusterer    = ->  
    textSize: 10, 
    textColor: '#fff',
    url: "assets/your_custom_cluster_image_small.png", // <- your custom image is specified here
    height: 56,
    width: 56
    textSize: 10, 
    textColor: '#fff',
    url: "assets/your_custom_cluster_image_mid.png", // <- and here
    height: 59,
    width: 59
    textSize: 10, 
    textColor: '#fff',
    url: "assets/your_custom_cluster_image_large.png", // <- and here
    width: 66,
    height: 66