XHTML and HTML pages have a hierarchical structure defined by the Document Object Model (DOM). Each page element is defined as an object and placed within the structure defined by the DOM. An early definition of this model as it related to HTML can be found here:

http://www.w3.org/TR/1998/REC-DOM-Level-1-19981001/introduction.html

More up-to-date definitions can be found via a web search for dom definition.

Therefore each element within an XHTML document can be related to every other element within the document by their relative positions within the DOM. So consider this part of an XHTML page:

<div id="fruit_list">
<ul>
<li>Apples</li>
<li>Pears</li>
<li>Oranges</li>
</ul>
</div>

Its DOM representation would be as shown below.

From this you can see that:

We can navigate up, down and across this structure using JavaScript.

However, first we must get to a starting point. All XHTML and HTML documents have a root ancestor element called "document" and we could start from this point and navigate down to the div containing the fruit list within the DOM. However, there is an easier way in which JavaScript allows us to navigate directly to a named element. In the example above there is one named object, the div element. Its name fruit_list is defined by the id attribute. The following JavaScript code creates four objects by first accessing the named div and then navigating from that point down through the DOM to access elements at each level below:

<script language="JavaScript" type="text/javascript">
var fruit_list_div = document.getElementById("fruit_list");
var the_ul = fruit_list_div.getElementsByTagName("ul")[0];
var li_elements = the_ul.getElementsByTagName("li");
var second_li_text = li_elements[1].innerHTML;
alert(second_li_text);
</script>

The output of this script is an alert box containing the word "Pears". That is the text contained within the second li element.

The Prototype library contains a set of functions that make navigating the DOM a little simpler. The JavaScript below does the same as the script above, but uses Prototype functions to simplify the script:

<script language="JavaScript" type="text/javascript">
var fruit_list_div = $("fruit_list");
var the_ul = fruit_list_div.down("ul");
var li_elements = the_ul.immediateDescendants();
var second_li_text = li_elements[1].innerHTML;
alert(second_li_text);
</script>

The key functions to point out are:

A full description of the Prototype API can be found here: http://www.prototypejs.org/api

This example demonstrates that it is easy to access an element within the DOM using $(element_id), if we uniquely identify the element with an ID. It is also fairly straightforward to navigate and collect elements near the named element.

If we return to our link_to_remote example, we need to identify an element as"output_place" that will be modified when the link is activated. The simplest solution is to add a div element at the place in the document where we want any new content to appear:

<div id="output_place"></div>

This can be anywhere within the page displayed when the view is rendered. We can then grab this element with $("output_place"). In fact, the link_to_remote helper even puts the ID within $(), so all the helper needs is the entry:

:update => "output_place"

Lastly we need to create the code that will generate content to be placed within the output_place div when the link is activated. So in the controller we add the following code to create a new action called say_hello.

def say_hello
render :text => "Well hello there!"
end

If we now navigate to the view containing the link_to_remote, and click on the link Say Hello, Rails will render the text Well hello there! within the output_place div.

When Rory starts thinking about what he requires he draws up the following list:

However, the simplest AJAX actions are to add and remove whole elements. Also, it is easier to replace a link than alter it. Therefore, the way the AJAX tools work lend themselves to a different arrangement.

To work through how to create the required show/hide effect, it is simplest to start with alternating links. Coming up is some view code that achieves a very simple show and hide effect with link_to_remote links.

<p>
<span id="show_alternative_link">
<%= link_to_remote "Show Alternative Partial",
:update => "output_place",
:url => {:action => 'show_alternative_stuff'},
:success => "$('show_alternative_link').hide()",
:complete => "$('show_initial_link').show()" %>
</span>
<span style="display: none;" id="show_initial_link">
<%= link_to_remote "Show Initial Partial",
:update => "output_place",
:url => { :action => 'show_initial_stuff' },
:success => "$('show_initial_link').hide()",
:complete => "$('show_alternative_link').show()" %>
</span>
</p>
<div id="output_place"><%= render :partial => 'initial_stuff' -%></div>

Before we can use this code, the show_initial_stuff and show_alternative_stuff actions will need to be configured in the controller:

#Renders a partial called some_stuff
def show_alternative_stuff
render :partial => "alternative_stuff"
end
def show_initial_stuff
render :partial => "initial_stuff"
end

The show_stuff action renders a partial. That is the partial passed to the browser to display within the target"output_place" div. The show_initial_stuff action renders the same partial that was initially displayed within the output_place div.

So lastly we need to create two partials and place them within the controller's view folder. For this example, the content of the _initial_stuff.rhtml file is:

<h2>This is the initial partial</h2>
<p>This is the original text to be displayed.</p>

The content of the _alternative_stuff.rhtml file is:

<h2 style="color:green;">This is the replacement partial</h2>
<p style="color:red;">This is some alternative text to be displayed.</p>

Now when we click on the link "Show Alternative Partial" the contents of _alternative_stuff.rhtml replaces the initial text in the output_place div. Then clicking on the "Show Initial Partial" link returns the contents of "output_place" div to its initial state.

As I stated earlier, JavaScript can be difficult to debug. One very useful tool to help debug our AJAX actions is Firebug (http://getfirebug.com/). Firebug is a Firefox plugin. The figure below shows the response information from activating the Show Initial Partial link

Such information is often essential when tracking down AJAX related problems.

Fortunately, the company address in Rory's index view is already being rendered as a partial. So instead of creating a new partial, all Rory has to do is alter the place where the partial is rendered. That is, instead of it being loaded as the page is built, it will be rendered as a response to a link_to_remote action.

The table cell is currently created with the following code in the view app/views/companies/index.rhtml:

<td><%= render :partial => 'addresses/show', :locals => {:address => company.address} %></td>

Rory needs to replace this content with two link_to_remote entries and an output div. He also needs to move the render code to a new action within the controller.

He starts by adding new actions to the controller app/controller/companies_controller.rb:

def show_address
@address = Address.find(params[:id])
render :partial => 'addresses/show', :locals => {:address => @address}
end
def hide_address
render :text => " "
end

For the show_address action, he moves the render statement from the view to the controller's action code. Then adds a method to identify the address and pass it to the partial. The render code is altered to use @address for the local address.

The hide_address simply renders a blank entry.

The content of the company list table cell is then updated from:

<td><%= render :partial => 'addresses/show', :locals => {:address => company.address} %></td>

...to:

<td><%
show_link = "show_address_#{company.id}"
hide_link = "hide_address_#{company.id}"
output_place = "address_#{company.id}"
%>
<span id="<%= show_link -%>">
<%= link_to_remote "Show",
:update => output_place,
:url => {:action => 'show_address', :id => company.address_id},
:before => "$('#{output_place}').update('Loading ...')",
:success => "$('#{show_link}').hide()",
:complete => "$('#{hide_link}').show()"
%>
</span>
<span id="<%= hide_link -%>" style="display: none;">
<%= link_to_remote "Hide",
:update => output_place,
:url => {:action => 'hide_address'},
:success => "$('#{hide_link}').hide()",
:complete => "$('#{show_link}').show()"
%>
</span>
<div id="<%= output_place -%>"></div>
</td>

A few things to note:

Mary comes to Rory with a new request. She is finding that telephone numbers are used more than anything else in the application and she wants a quick and easy way to enter and update them. Preferably she would like to change them without leaving the index view. Rory decides to extend what he has learned using link_to_remote to satisfy Mary's request.

The first step is to create a link_to_remote in the telephone cell of the company list. As it needs to appear with any existing data, he makes it very small, simply a plus sign. So in app/views/companies/index.rhtml he replaces:

<td><%= company.telephone %></td>

...with:

<td><%
tele_output = "telephone_#{company.id}"
-%>
<%= link_to_remote "+",
:update => tele_output,
:url => {:action => 'show_update_telephone', :id => company.id } -%>
<span id="<%= tele_output -%>"><%= company.telephone -%></span>
</td>

This is a simple link_to_remote.

Rory then updates app/controller/companies_controller.rb by adding two new methods:

def show_update_telephone
@company = Company.find(params[:id])
render :partial => 'update_telephone', :locals => { :company => @company}
end
def update_telephone
@company = Company.find(params[:id])
@company.telephone = params[:telephone]
@company.save
render :text => @company.telephone
end

The action show_update_telephone is used by the link_to_remote. It causes a partial _update_telephone.rhtm to be rendered and passes a company object to the partial. The partial contains an AJAX form and the method update_telephone handles the data returned by that form. Here is the content of app/views/companies/_update_telephone.rhtm:

<% tel_output = "telephone_#{company.id}"
tel_form = "telephone_form_#{company.id}" %>
<div id=<%= tel_form %>>
<%= form_remote_tag(:update => tel_output,
:url => { :action => :update_telephone },
:complete => "$('#{tel_form}').remove()" ) %>
<%= text_field_tag :telephone, company.telephone %>
<%= hidden_field_tag :id, company.id %>
<%= submit_tag "Update" %>
<%= end_form_tag %>
</div>
<div id="<%= tel_output %>"></div>

As with the previous link_to_remote tags, the company ID is appended to tag names so that each telephone entry within the list is uniquely identified.

The main new element is the form_remote_tag. This is quite like a standard form_tag, except that, it uses an AJAX XMLHttpRequest to submit the data. Therefore any data input into the form is passed to the server without refreshing the whole page. Most of the options used by link_to_remote are available to form_remote_tag, and Rory uses the :complete option to remove the form once a new entry has been submitted.

The rest of the form is generated using standard form elements. It is this that gives this technique such advantage over the in_place_editor. Any form element available to us in a standard form can be used in the form partial. While this form is used to update a single field, it would be easy to add additional fields and options (such as replacing a whole list row with an input form) become possible with only fairly small changes to the basic technique.

Prototype tools mainly allow users to access data from outside and then use it within, the user interface. The script.aculo.us tools concentrate on allowing a user to manipulate the interface itself. One of the simplest functions to make available to the user, is the ability to drag one element on a web page to another location on the same page. That is, to make the element draggable.

The behavior of a draggable object is defined within the AJAX class Draggable. To make an element draggable we need to create a new instance of an object of the JavaScript class Draggable, and associate that new object with the element. This can be done by adding the following code to a view:

<%= javascript_tag "new Draggable('element_id')" -%>

Where element_id is the id of the element to be dragged. Rails provides a helper method to simplify this still further:

<%= draggable_element :element_id -%>

Unlike objects in Rails, JavaScript can be sensitive to where an object is created and used. If the code that associates an element with a Draggable object, is put before the code that defines the element within the DOM, the code will not work as we desire it to. JavaScript will not look ahead in the HTML code for an element that matches the element_id. It will only look back through the DOM elements that have already been defined. It will, therefore, fail to find the element and then associate the Draggable object with a null. This will not raise an error — it just will not make the element draggable when it is placed on the page.

Therefore, this will not work as desired:

<%= draggable_element :element_id -%>
<div id="element_id">stuff to be dragged</div>

Whereas this will work:

<div id="element_id">stuff to be dragged</div>
<%= draggable_element :element_id -%>

We wish to make the addresses in the company list draggable. These addresses are displayed in a div element whose name is defined by output_place. We, therefore, already have an ID for the element to be dragged. Adding a draggable_element statement below the output_place div and using the output_place variable to define the element will make addresses draggable:

<div id="<%= output_place -%>"></div>
<%= draggable_element output_place -%>

Once the draggable functionality is implemented, it becomes possible to show any address and then drag it to another part of the company list page, where it will stay when released. It is worth playing with this behavior as it has some unexpected results. Drag an address to another part of the page and then click on the "hide" link for this address. The address disappears as expected. However, if we then click on the "show" link, the address does not appear in its normal position, but back in the place where we dragged it. This is because not only the content of the div was moved by dragging, but also the div itself. Therefore, when the link_to_remote call behind the "show" link is triggered, it inserts the address into the div at its new position. The :revert option causes a dragged element to return to its original position when dropped. In this instance, :revert provides a more predictable behavior.

There is also the issue of whether a user would know that an element is draggable. Unless we provide clues as to the draggability of an element, there is no clue for a user that an element can be dragged; the element will look just like the static elements around it. CSS is the obvious way to overcome this. We can define a "draggable" DOM class and use that to define style elements in the page's style sheet to alter the appearance.

The modification to the output_place element shown below incorporates both a :revert option and Draggable class definition.

<div class="draggable" id="<%= output_place -%>"></div>
<%= draggable_element output_place,
:revert => true -%>

To display visual clues to the user, we also add a definition of .draggable to base.css:

.draggable {
cursor : move;
}
.draggable:hover{
background : yellow;
}

This causes the pointer (cursor) appearance to change as the mouse pointer moves over the draggable element. It also turns the background color of a draggable element to yellow while the mouse is over that element.

Dragging elements around a page may have some use, but draggability becomes much more useful if we can use the fact that an element has been dragged somewhere to drive another event. This is particularly the case if we can pass information from the dragged element to the triggered event.

The simplest way to achieve this is to use another set of AJAX objects called droppables. These are DOM elements that can receive dragged elements. Using Rails, an element can be defined as droppable like this:

<div id="drop_place_id">drop it here</div>
<%= drop_receiving_element :drop_place_id %>

To demonstrate how to use droppables, let us create a new area at the bottom of the company list page, which includes:

<div id="address_drop">
<h2>Address drop</h2>
<p><span id="address_drop_output">Drop an address here.</span></p>
</div>
<%= drop_receiving_element :address_drop,
:update => "address_drop_output",
:url => {:action => 'show_address'},
:before => "$('address_drop_output').update('Loading ...')" -%>

Note that the drop_receiving_element method allows the same options that we have used before with link_to_remote:

We now have somewhere to drop our addresses. However, to use the dropping process to determine a particular event we need to pass information from the dropped element to the controller. Fortunately, the method drop_receiving_element provides a mechanism to do this: the dropped element's ID is passed to the controller and can be accessed at the controller via params[:id].

In Rory's application, it should then be fairly easy to use the element id with the companies_controller's show_address method to output the dropped address. However, the design of the show_address method and the link_to_remote code that use it means that there is a small complication. The Rails object ID used to create each address droppable's ID is a Company object, whereas show_address uses Address object IDs. There are two ways to handle this—detect the type of ID being

passed to the method and alter the way the method handles the ID to suit; or change the link_to_remote code so that it also uses the company ID. The first provides better performance (because we do not always first have to find a company before we can look up an address) the second is more scalable (because more of the code is reused, that is we are not using a different set of code for each option). There is a third option which is to use an address ID to identify the droppables, but there is a possibility that this would not create unique IDs on the page as two companies could share the same address. I will use the second option as it demonstrates the important components and how they can be used together.

First we will modify the link_to_remote to use the company ID, pass the same parameter name to the controller as the default drop_receiving_element (that is, :id), pass the same information (output_place) and alter the names of the elements so that they are a little more meaningful.

<%
show_link = "show_address_for_company_#{company.id}"
hide_link = "hide_address_for_company_#{company.id}"
output_place = "address_for_company_#{company.id}"
%>
<span id="<%= show_link -%>">
<%= link_to_remote "Show",
:update => output_place,
:url => {:action => 'show_address', :id => output_place},
:before => "$('#{output_place}').update('Loading ...')",
:success => "$('#{show_link}').hide()",
:complete => "$('#{hide_link}').show()"
%>
</span>

We then need to modify the companies_controller show_address method to handle the fact that the ID being passed to it will now be a Company ID and will have the prefix"address_for_company_" to deal with:

def show_address
@address = Company.find(params[:id].delete( "address_for_company_")).address
render :partial => 'addresses/show', :locals => { :address => @address}
end

With these changes implemented, the user is now able to choose an address and drag it to the area with the heading "Address drop". When they do this, the address will appear below the heading.

This example shows how some of the techniques used with link_to_remote can also be used with drag and drop elements to provide additional functionality. In particular, it demonstrates how drag and drop can be used to trigger events, and provide information to the process controlling the event that will allow it to alter its behavior (depending on the identity of the element dropped).