Hello World (rails with mappa - Part I)

Posted by nito, Sun Dec 30 20:57:00 UTC 2007

As promised, here’s the first in a little series of mappa.rb usage tutorials for Ruby on Rails.

These tutorials should provide something for all users, but for the sake of clarity and to help any rails virgin, I’ve written this tutorial in particular from the perspective of the beginner. So, we’re pretty much starting from the scratch. I’m assuming the you, the reader, aren’t a complete command line newbie, know how to use an editor of some sort and are familiar with command line navigation and command execution.

If you are not a beginner, ignore anything you consider beneath you and demonstrate your superior knowledge by just extracting the knowledge you require from the content below :-)..

Subsequent tutorials will make assumptions about your knowledge level based upon what you will have picked up already, and will probably assume “you already know it”, or have already read this tutorial.

Because I use OS X - a unix operating system, I’m using a Unix operating system in my examples. If you are using a non-unix based operating system, I recommend you translate my example command line instructions into those relevant to your operating system.

And, for the non-beginner (and beginner too!), I recommend you look at the forthcoming, more detailed, Mappa api article that will provide detail on all the key api methods.

[Clearly, you will need to have ruby and Ruby on Rails installed on your computer. Installation is beyond the scope of this article. For more information got to: Ruby on Rails]

Ready? Let’s begin!

1) Create a project and install the plugin

Enter the directory you wish to use to hold your rails project, copy the mappa.tar.gz file into that directory.

If you haven’t already downloaded it, go and get it from: Here.

Type or cut and paste the following code:


rails gmapping
cd gmapping/vendor/plugins
cp ../../../mappa.tar.gz .
tar xzvf mappa.tar.gz
cd ../..

This should leave us in the gmapping directory, ready to create a rails controller.

2) Create the controller.

In the top level gmapping directory, generate a map controller by typing the following:


ruby script/generate controller map index

Once you’ve done this, open a new shell, change to your gmapping directory and type: 


ruby script/server

Once the server starts, open a browser and point it to http://localhost:3000/map You should see this:

Map#index Find me in app/views/map/index.rhtml

Clearly not what we want, yet… but we’re nearly there. First, let’s edit the controller, and then we’ll edit the view.

Change directory to the app/controllers directory (cd app/controllers should do it ;-) ). Using your favourite editor (really, whatever you want - this isn’t the place for editor wars. I’m a ‘textmate’ or ‘vi’ person myself, but you know, if you wish to twist your brain with emacs, that’s up to you.), open the map_controller.rb file and replace: 

def index
  end

with this: 

def index

    @page_title = 'Hello world!'

    #Create our new Gmap object
    @gmap = Mappa::GMap.new()

    # the gmap api key for localhost:3000 - remember to change this!
    @gmap.api_key = 'ABQIAAAArjtwNyA-0TDmcb74hMzhHBTJQa0g3IQ9GZqIMmInSLzwtGDKaBRSDWK-cqMmi3YB5dD-8a6Kwe1Qmg'

    # set the longitude and latitiude of the centre point of our map
    @gmap.lat = 51.775362610
    @gmap.lng = -0.00100011

    # set the zoom level of our map. This number is in the range of 1-18. 1 is lowest zoom and 18 is highest
    # we've picked a nice middling 12.
    @gmap.zoom = 12

    # by default gmap.onload is set to true. setting it to false allows (and expects)
    # you to want your javascript within the <body> section and not the <head>
    @gmap.onload = false

  end

Now we’re ready to create our view.

3) Create the view

First, we’re going to create a layout file. A layout is basically a special template that controls the global layout of our page: the html, the header and often the body definition, the kind of things that get repeated across many pages. Using the Google Maps API requires that we have a google map API key, so we are going to put that inside our layout file. Change into the app/views/layout directory and create a file called map.rhtml. edit that file, and add the following:

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" 
  "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" lang="en" xml:lang="en">
  <head>
    <title><%= @page_title || 'map' %></title>
    <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
    <%= yield :map_headers %> 
  </head>
  <body>
    <%= yield %>
  </body>
</html>

Now, let’s create our action specific view. Change directory until you are in gmapping/app/views/map (cd ../map shoud do it ;-) ) open the index.rhtml file in an editor and replace :

<h1>Map#index</h1>
<p>Find me in app/views/map/index.rhtml</p>

with this:

<% content_for :map_headers do %>
    <%= map_header(@gmap) %>
<% end %>

<div style="height:400px;width:400px" id="gmap"></div>

<%= map_body(@gmap) %>

4) That’s all folks

No really. try it. http://localhost:3000/map. Go on, I dare you.

What did we just do??

“Whowa there.” I hear you say as, already, I’ve mired and obscured your beginners knowledge. What’s with that “content_for :map” jive?? Ah, yes. A little niftiness. As it says, it’s the content for map_headers. Pretty self explanatory, isn’t it? No? Scroll up a bit and look at the layout file. See the lines: 

<head>
    <title><%= @page_title || 'map' %></title>
    <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
    <%= yield :map_headers %> 
  </head>

There you go. Your first rails trick. dynamically generating content for the containing layout using content_for. I’ll let you in on a secret: we don’t really need it here… but we will do… later… when we want to put all our javascript in the header section of our layout, dynamically.

Virtually Every rails template should contain a <%= yield %> line, and this is where the content generated for your view will end up. In our case, whatever is generated by the index.rhtml file is slotted in there EXCEPT that content generated by :

<% content_for :map_headers do %>
    <%= map_header(@gmap) %>
<% end %>

which ends up being picked up by the <%= yield :map_headers %> part of the rails template. What you see there is a call to a helper method that you get with mappa.rb, called map_header. map_header will then generate the relevant html header required (normally to include javascript files).

The 

<%= map_body(@gmap) %>

line at the bottom of the index.rhtml did the rest of the dirty work. Another Mappa.rb helper method, map_body takes our @gmap variable, created in our index method in the controller, and generates the javascript required. This Javascript makes use of a div with the id of ‘gmap’ to act as the container for the map. This is the default value, but, as you’ll see in later tutorials, is easily cahnged. Now and finally, Take a look at the html source to see what it produced.

NEXT markers and onload

Filed Under: Geekliness Tutorial | Tags:

Comments

Leave a response

  1. Christian Frugard 05.14.08 / 10AM

    You could easily place your API key in the environment.rb file. That would make it available to all of your controllers.

  2. Christian Frugard 05.14.08 / 10AM

    You could easily place your API key in the environment.rb file. That would make it available to all of your controllers.

Have your say

A name is required. You may use HTML in your comments.