With the improved user interface, the number of visitors to the Head First Climbers site has soared. The trouble is, so many incidents are being logged that there are too many for people to easily read through them.

The index page of the site displays the information in two ways.

Neither of these are entirely satisfactory. It’s hard to locate the incidents from the list, and that’s why we added a map. But the map doesn’t display all of the data available. So what should we do?

The ideal solution would be to make the map do more. If it could be changed to display more useful information about the incidents, we could probably just remove the the list of incidents and make the front page one big multi-functional map. That would mean we wouldn’t need to go to separate pages in order to enter more data, for example.

There’s just one problem: the map partial was downloaded. It’s simple enough to use, but should we really change the code? Fortunately, there’s a development technique the map partial uses that means we don’t need to touch the downloaded code itself. But what is it?

The people who wrote the map partial figured that pretty soon people would want to extend the way the map worked. And because the map partial calls Google Maps, and Google Maps is built using Ajax, it made sense that the way to extend the map is with Ajax.

At the moment, the map works by making a request back to the server asking for an XML file containing the details of all of the mountaineering incidents recorded on the system. By default, the map displays the title and description contained in the XML.

But the map partial also allows you to pass it the name of an action that will display the information for an incident. And that action can be whatever you like, so if you wanted, you could generate something that looked like the original version of the incident show page.

We need the _map.html.erb partial to make Ajax requests, so this means it will need access to the Prototype library. We can allow this in the same way we did before, by adding a reference to the JavaScript library in the layout file like this:

The first thing we need to do to change the front page is remove the list of incidents and make the map larger:

We also need to tell the map partial the name of the action that will display the incident information. That’s quite a few changes, but it will actually make the index.html.erb template a lot simpler than it was before.

In fact, this is all we’ll be left with:

When the map partial is called like this, it changes its behavior. Before, when an incident was clicked, the partial ran a piece of default JavaScript that displayed the title and description in the pop-up information window. Making this change means that when an incident is clicked on the map, the partial calls the show action and displays the action’s response in the window.

Or at least it will, once we make the show action generate the correct output.

We already have a show action, and this generates a web page containing the details of an incident and a map with the incident’s location.

But that’s way more than we need now. The show action only needs to generate the text details of an incident, and because the information is going to be displayed next to a point on a map, we won’t need to display the latitude and longitude either.

There’s one other thing that’s different: we only need a page fragment. We don’t want the standard HTML boilerplate that will be produced by a page template. So this means our action will need to generated from a partial template. We’ll call this _show.html.erb.

Sharpen your pencil

Complete the line in the “show” method of the controller to call the _show.html.erb partial:

def show
   @incident = Incident.find(params[:id])
   respond_to do |format|
     format.html {
      _____________________________________________________________________________________________
     }
     format.xml {
       render :text=>@incident.to_xml(
         :only=>[:latitude,:longitude,:title,:description],
         :root=>"data")
    }
  end
end

Code Magnets

Complete the code for the new _show.html.erb partial. Remember you won’t need to display all of the information.

<p>
  <b>________________</b>
  <%=h_______________________%>
</p>

<p>
  <b>________________</b>
  <%=h_______________________%>
</p>
<p>
  <b>________________</b>
  <%=h_______________________%>

</p>
<p>
  <b>________________</b>
  <%=h_______________________%>
</p>

Sharpen your pencil Solution

Complete the line in the “show” method of the controller to call the _show.html.erb partial:

def show
   @incident = Incident.find(params[:id])
   respond_to do |format|
     format.html {
       render :partial=>'show', :locals=>{:incident=>@incident}_______________
     }
     format.xml {
       render :text=>@incident.to_xml(
         :only=>[:latitude,:longitude,:title,:description],
         :root=>"data")
     }
   end
end

Code Magnets Solution

Complete the code for the new _show.html.erb partial. Remember -you won’t need to display all of the information.

Test Drive

Now if we go along to the index page, sure enough—the list of incidents has disappeared and the map is much larger. But more important is what happens when the user clicks on one of the incidents on the map:

When the map detects a mouse click on an incident, it generates an Ajax request to the show action, and this generates the details in HTML for the incident. The map receives the HTML and uses it to replace the content of the incident’s information window. This then gets displayed to the user.

The new map functionality is greeted enthusiastically by the climbers. They no longer need to scroll past a long list of incidents to get to the map. Now they can get all the information they need direct from the map itself. There’s just one thing...

Climbers want to report new incidents using the map.

They can use GPS units to find their latitude and longitude and type that in, but the site would be a lot easier for them if they could simply plot a point on the map and fill in the other details right there. That would make data-entry quicker for the climbers.

So how does entering data on the map compare with what we’re currently doing?

If someone wants to create a new incident report, they currently have to go through the following steps:

So what needs to change?

Rather than go through all these steps, the users want the interface to be much simpler. They just want to click on the map and fill in the details using a form in the pop-up window.

To make that change, we need to generate the “new” form using Ajax. We also need the map to call the form when someone clicks on a new spot. But how?

So far we’ve looked at showing the incident details on the map. But how do we go about creating new incidents?

The _map.html.erb partial lets us specify an action to handle new incidents, in the same way it lets us specify an action for showing incident details. This means that we can add a “new” action to the index.html.erb file like this:

If someone clicks a new spot on the map, the _map.html.erb will create a new marker and pop up an information window containing whatever is returned by the “new” action.

We already have a “new” action defined for the application, but it’s generating a full web page. Rather than display a full web page, we need the “new” action to create a page fragment that will be displayed inside the pop-up information window. Also, we need to make sure that when the user submits the “new” form, it stays on the map.

So we’ll create a partial called _new.html.erb that generates an Ajax form.

Exercise

You need to create a _new.html.erb partial for the form. Complete the code for the form. Remember - people won’t need to enter values for the latitude and longitude, but the form will still need to record them.

When the map calls the “new” action, it sends the location of the new incident as request parameters. Complete the code in the incidents_controller.rb new method so that it calls the partial correctly:

format.html {
  @incident.latitude=params['latitude']
  @incident.longitude=params['longitude']
  _________________________________________________
}

Exercise Solution

You need to create a _new.html.erb partial for the form. Complete the code for the form. Remember - people won’t need to enter values for the latitude and longitude, but the form will still need to record them.

When the map calls the “new” action is sends the location of the new incident as request parameters. Complete the code in the incidents_controller.rb new method so that it calls the partial correctly:

format.html {
  @incident.latitude=params['latitude']
  @incident.longitude=params['longitude']
  app
  render :partial=>'new', :locals=>{:incident=>@incident}
}

Test Drive

Now if a user goes to the front page and clicks on a fresh point on the map, they can enter details for the incident using a pop-up form. When the “Create” button is clicked, the form remains on the screen, but a new record is displayed on the database.

So is everything OK?

The climbers are confused.

Even though the form works fine and incidents are being saved to the database, it actually looks like nothing is happening. When the user clicks on the “Create” button, there’s no feedback indicating the record was saved. This means that the users are repeatedly hitting the Create button, and the database is starting to get lots of duplicate records.

Something needs to be done. Back in the old days when we just had scaffolding, when a user reported an incident with the “new” page, the browser would immediately switch to the “show” page. This confirmed that the data was saved to the database.

Could we have something like that in the Ajax app?

The system really needs to show the created record in the pop-up window using the “show” action. So if someone enters details of an incident, the pop-up should change to show a read-only version of the incident.

That way, the pop-up information window will work like a little browser, forwarding to the new information. Except of course, our code can’t just forward the browser to the new information. We need to keep climbers on the same page... just with new information showing.

Even though it looks almost like a desktop application, Google Maps basically boils down to just HTML and JavaScript. It’s just a web page. That means that the pop-up information window—and everything else—are just pieces of HTML.

The contents of the pop-up window are defined in a <div> element with:

id='map_info'

This is important because we’re using an Ajax form to create a new incident report, and Ajax forms can be used to dynamically update parts of a web page using their ids.

So if we can get the form to update the map_info <div> with the contents of the “show” action for the incident, it should give the users the feedback they need.

Sharpen your pencil

This is part of the code for the “new” form. Bearing in mind that the form will need to update the page with the form response, complete the code:

The “new” form submits itself to the “create” action. This is the create method on the controller. Mark any changes you think are needed.

Sharpen your pencil Solution

This is part of the code for the “new” form. Bearing in mind that the form will need to update the page with the form response, complete the code:

The “new” form submits itself to the “create” action. This is the create method on the controller. Mark any changes you think are needed.

Test Drive

So now what happens when the user creates an incident?

Clicking on a new point on the map displays the Ajax form, just like before:

But when they hit the “Create” button, not only does the system save the record to the database, it also returns a page fragment containing the incident details, which the Ajax form now uses to update the map_info <div> inside the pop-up window.

So far we’ve allowed users to see more detailed information on the map, and also create new incidents onto it direct. But what about edits?

There are two places where scaffolding gives you an edit option.

On the original scaffolded version of the “index” page, you could click the “Edit” link next to any of the records and jump to the edit form. But we can’t do anything like that now because the list of incidents on the index page has been replaced by the map. And we know that the map partial doesn’t have any “Edit” functions built in.

So where else could we edit things in the original scaffolding? Well, another place is in the incident “show” page. In the scaffolded version of the application, there was an “Edit” link on the “show” page.

So could we do something like that? How about if we add an “Edit” link to the set of details that are displayed in the pop-up window.

Would that work?

We need to add an “edit” link to the details that appear when someone selects an incident from the map. When someone clicks on the “edit” link, we switch the contents of map_info <div> to display an edit form and then use that to amend the record.

We already have the “show” function built. The “edit” form should be similar to the “new” form, and we already have the back-end code in the controller to amend the record.

How hard can it be?

We need some way of generating an edit form that will appear in the pop-up window. We’ll create a partial called _edit.html.erb. The partial looks pretty similar to the _new.html.erb:

So why have two partials?

The two partials are basically the same code, but it’s a good idea to keep them separate. At the moment they both look the same, but that might not always be the case.

As an example, we might want to change what functionality is available through the “new” and “edit” pages. We might decide that we need users to insert the date of an incident, but we may want to stop them editing it afterwards. Another possibility is that we might want to make the two pages look different from each other.

Rails knows if the form’s model object has been previously saved to the database.

So the code that the form_for helper generates changes depending upon whether it is dealing with an unsaved object (in which case, the form will call the “create” action) or an object that’s already been saved in the past (in which case, the form will call the “update” action).

Talking of actions, as well as creating the partial, we need to modify the “edit” action method in the controller to return the “edit” partial when it’s called:

def edit
  @incident = Incident.find(params[:id])
  render :partial=>'edit', :locals=>{:incident=>@incident}
end

There are no Dumb Questions

Q:	Q: How does Rails know if an object has already been saved?
A:	A: It calls a method called “new_record?”. That return true if the object has never been saved.
Q:	Q: Why does “new_record?” have a question mark at the end?
A:	A: It’s a Ruby convention. Most methods returning true or false, have a question-mark in their name.
Q:	Q: Why do we have to have hidden fields for latitude and longitude?
A:	A: We don’t want people to edit them.
Q:	Q: Yeah - I know that. But why even mention them at all?
A:	A: The form object gets converted into the fields in the form. If they weren’t mentioned in the form fields, they would disappear.
Q:	Q: But we don’t have fields for id, created_at and updated_at fields?
A:	A: No - but Rails knows that they’re needed, so the form_for helper will create them for you.

We should now be able to generate an edit form, but how will the user get to it? We need an “Edit” link to appear when the user looks at the details of the incident. The link will need to be added to the _show.html.erb partial.

To generate the link, we’ll use the link_to helper.

The link_to helper takes two parameters: the name of the text in the link and the place we’re going to.

<p><%= link_to "Edit", "/incidents/#{incident.id}/edit" %></p>

That’s a very good point.

So far we have created lots of paths and URLs using strings. But what if we change the format of the links in the future? We can fix things in the routes pretty quickly, but we will have a lot of redundant strings in the code containing paths.

Having the same sort of information in two places is bad because it breaks an important Rails principle:

But if the routes already record the structure of the paths and URLs, maybe it’s worth looking at routes in a little more detail.

Restful Routes up Close

So far we’ve created individual routes in config/routes.rb using the map.connect command:

map.connect 'incidents/map/:id', :action=>'show_with_map', :controller=>'incidents'

But you may have noticed when you were editing the routes.rb file that Rails scaffolding generates its routes with a different command:

map.resources :incidents

This single command generates of set of standard routes called the RESTful routes. The routes provide access to the standard CRUD operations with the application. You can examine the routes from the console using the rake tool:

Each of these lines is a single route, and in some cases, the routes are named. So edit_incident is the name of the “/incidents/:id/edit” route.

But how does that help us tidy the path in the code?

Rails provides helpers for each named route

Those RESTful route names are important, because they help you refer to a route from inside your code. They let you turn this:

"/incidents/#{incident.id}/edit"

into this:

edit_incident_path(@incident)

For every named route, Rails gives you helpers to generate paths on the local server and complete URLs.

Paths on the local server

edit_incident_path(@incident) returns /incidents/3/edit if @incident has id = 3

Complete URLs

edit_incident_url(@incident) returns http://localhost:3000/incidents/3/edit

They’re called RESTful route helpers because they can accept resources, or model objects, as parameters. Remember - one of the principles of REST design is to think of web applications as containers for resources.

The helpers for incidents and new_incident are called without resources—for example, as incidents_url or incidents_path.

The route helpers will not only remove redundant path formats from your code, but they are also easier to read and reduce the chances of you making an error in a path description.

So what does that do to our code? It changes from this:

<p><%= link_to "Edit", "/incidents/#{incident.id}/edit" %></p>

into this:

<p><%= link_to "Edit", edit_incident_url(incident) %></p>

Test Drive

So once the “Edit” link has been added to the “show” partial, what happens when we click on an existing incident on the map?

The link simply took the browser to:

http://localhost:3000/incidents/5/edit

The trouble is, this now sends the contents of the _edit.html.erb partial back to the browser like it was another page.

We really need to stay on the same page in the browser, so how do we fix it?

The “new” form we created earlier was able to replace the contents of the pop-up information window because it made an Ajax call to the server. It used the server response to replace the contents of the map_info <div>.

But the link we just added didn’t do that. It just told the browser to link to another page. If we create an Ajax link instead of a browser link, we can get around the problem.

An Ajax link works a lot like an Ajax form. When you click on an Ajax link, it doesn’t tell the browser to go to a different page, instead it generates an Ajax request to the server and uses the response to update part of the page. If this sounds familiar, it’s because Ajax links are almost identical to the Ajax buttons we used earlier on to refresh the seating list at Coconut Airways.

To convert the link into an Ajax link, we have to change this:

<p><%= link_to "Edit", edit_incident_url(incident) %></p>

to this:

The link should now generate an edit form from the server and display it in the pop-up window. Let’s see how it works now.

Test Drive

When we click on an incident, the information window looks exactly the same as before.

The link looks the same, but remember that behind the scenes, it’s no longer a simple link. Instead there’s a whole lot of JavaScript mojo going on, waiting to generate an Ajax request when the link is clicked. So what happens when we click it?

Instead of displaying the edit form, we get this weird “Unknown action” error. So what the heck happened?

We need to dig a little deeper into the routes...

When Rails receives the Ajax request from the link, the Ajax link sends out a request correctly to:

http://localhost:3000/incidents/5/edit

Instead of matching the request to the edit_incident route, it matches to one of the default routes:

Rails tries to match it to the default route near the bottom, and it sets the :action parameter to ‘5’ and the :id parameter to ‘edit’. There’s no action called ‘5’, so it fails.

But how can that be? Our URL (http://localhost:3000/incidents/5/edit) is the same path format as the edit_incident route (/incidents/:id/edit). So why didn’t it match? After all, the link worked fine before we converted it to Ajax.

There’s one column in the routes that we’ve not really looked at:

So what are those GET, POST, PUT and DELETE words about?

They are the HTTP methods—also called the HTTP verbs. Every request uses a particular HTTP method, and Rails uses the method as well as the path to decide which route to use.

But what exactly are they?

Despite the name, HTTP methods are really nothing like the Ruby methods you find in, say, a controller. Instead, an HTTP method is mentioned in the low-level HTTP-talk that happens when a client contacts the server:

So why did the two versions of the link do different things? Well - ordinary HTML hyperlinks send GET requests to the server. But, by default, Ajax links send POST requests.

So to make the link work, we also need to tell the link what HTTP method to use like this:

<p><%= link_to_remote "Edit", :update => "map_info",
        :url=>edit_incident_url(incident), :method=>'get' %></p>

Test Drive

It works!

When we click on an incident link, we see the information displayed with an “Edit” link. When we click on the link, it creates an Ajax request for the edit form, which is used to replace the contents of the pop-up.

And what about the form? Well that works pretty like the “new” form did. It updates the incident and then redisplays it:

The mountaineers are loving the application. But we think you can do a better job.

It’s time to lay your thing down and seriously pimp this application. Add more details, add more widgets, add more eye candy. Here are some ideas:

You’ve got Chapter 9 under your belt, and now you’ve added the ability to add more advanced Rails functionality to your web apps.