First off, you'll need both the scriptaculous and prototype javascript libraries (both available from script.aulo.us). Once you've downloaded these files, you'll need to reference them in the head of your file:

<script type="text/javascript"
src="scripts/prototype.js"></script>
<script type="text/javascript"
src="scripts/scriptaculous.js"></script>

Then, in your html file, make your list:

<ul id="items_list">
	<li id="item_1">Item 1</li>
	<li id="item_2">Item 2</li>
	<li id="item_3">Item 3</li>
<li id="item_4">Item 4</li>

Note that the ul and each li have unique ids. It is also important to note that the ids of the list items must have "_#" at the end (this number must be unique).

Next, add this after the list (because of IE):

<script type="text/javascript"
language="javascript">
Sortable.create("items_list",{dropOnEmpty:true,con
straint:false});
</script>

Cool! It works! But...

Now that you've done this, go ahead and check it out. Cool... You can now sort your list by dragging and dropping! This is all fine and dandy, but how do I actually store this new order in my database?

It's pretty simple actually. In comes "serialize", to make life easy. This little gem creates a string containing information on of the current state of the list being sorted. How do you use it?

var listorder = Sortable.serialize('items_list');

Let's say that you've sorted your list as follows:

• item 3
• item 2
• item 1
• item 4

When invoked, the variable listorder would return as "items_list[]=3&items_list[]=2&items_list[]=1&items_li st[]=4". And this is what you need to update your database. Notice, the values returned are associated to whatever is after the underscore (_) in the id of the list item.

Now that you have this information, you can easily update your database with a simple AJAX call pointing to your php file ('save_items_order.php' in this case):

function saveOrder() {
	listorder = Sortable.serialize('items_list');
	var url = 'save_items_order.php';
	var pars = listorder
		+ '&rnd='
		+ new Date().getTime();
	var myAjax = new Ajax.Request(
		url,
		{
			method: 'post',
			postBody: pars,
			onComplete:  showList
		});
}

Finally, the PHP/mySQL piece:

if($_POST) {
  $items = $_POST['items_list'];
  $i = 1; # will represent the actual order (starting at 1).
  foreach($items as $itemid) {
    $query = "
      UPDATE items_table SET order_col = $i WHERE id_col =
$itemid
    ";
    mysql_query($query);
    $i++;  # add 1 to the current value of i (the next order
in the list).
  }
}

There you have it. An example of how to sort a list, and then store the new order in your database.

In order to represent a working example of AJAX, there are a few things we're going to need.

• database
• HTML file
• JavaScript (located within the HTML file in this example)
• ColdFusion file (note: any programming language can be used)
• prototype JavaScript library

The Database

The database used in this example is an extremely basic MS Access database consisting of one table that contains 6 fields:

Now that we know what we are going to be storing, let's take a look at the ".html" file.

HTML File

This file will consist of the form fields needed to populate the database, along with the placeholder we will use to show the information being stored:

<form name="addEmployee">
First Name:<input type="text"
name="FirstName" id="FirstName"
value="" size="30" />
<br />
Last Name:<input type="text"
name="LastName" id="LastName"
value="" size="30" />
<br />
Job Title:<input type="text"
name="JobTitle" id="JobTitle"
value="" size="30" />
<br />
Phone:<input type="text" name="Phone"
id="Phone" value="" size="12"
/>
<br />
Fax:<input type="text" name="Fax"
id="Fax" value="" size="12"
/>
<br />
<input type="button" name="submit"
value="save"
onclick="insertEmployee();"/>
</form>
<div id="EmployeeList"></div> 
//placeholder div

Notice how there is no method or action in the form tag? Both of these will be taken care of by the JavaScript.

The JavaScript

Once you've gotten all the form fields you need, you're now ready to start writing the JavaScript that will handle the AJAX portion. First, make sure you are referencing "prototype.js" (<script src="/scripts/prototype-1.4.0.js"></script>) . Now that prototype is in place, we can begin writing the necessary code to populate the "Employee" table. Notice from the xhtml code (above) the onclick event attached to the save button: onclick="insertEmployee();". This function is going to be called everytime a user clicks the "save" button. Let's take a look at this function:

function insertEmployee() {
	// begin form variables
	var fname = $F('FirstName');
	var lname = $F('LastName');
	var jtitle = $F('JobTitle');
	var phone = $F('Phone');
	var fax = $F('Fax');
	// end form variables
	var url = 'employee.cfm';
	var pars = 'FirstName='
			   + fname
			   + '&LastName='
			   + lname
			   + '&JobTitle='
			   + jtitle
			   + '&Phone='
			   + phone
			   + '&Fax='
			   + fax
			   + '&Action=Insert&rnd='
			   + Math.random()*99999;
	var myAjax = new Ajax.Request(
	url,
	{
	        method: 'post',
	        postBody: pars,
	        onComplete: listEmployees
	});
}

First of all, we're putting the values within each form field into variables. We'll then use these variables to pass them to the ColdFusion file, which in turn will insert these values into the database. The next step is to declare a variable that will contain the actual URL of this CF file. In this example, we're calling this variable url, and we're giving it the value of "employee.cfm". This value tells us that the CF file is located in the same directory as the ".html" file. Now that we have the values of each form field and the URL of the CF file declared, we're going to create another variable "pars" which will contain all the name/value pairs that will be passed to the CF file. In the code, we've written these name/value pairs separated by new lines, which improves readability. As you can see, these name/value pairs are passed to the CF file much like you'd pass them in a URL string. For example:

employee.cfm?FirstName=John&LastName=Doe&JobTitl e=Accountant...

One thing to take note of, however, is the fact that we are passing 2 additional name/value pairs that are not part of the form: "Action=Insert" and "rnd=[a random number]". The "Action=Insert" will make sense when we take a closer look at the CF file. The "rnd=[a random number]" is explained in detail in my previous post.

Now that we've got a good understanding of "pars" and "url", let's take a look at the actual request that we'll use to send to back-end:

    var myAjax = new Ajax.Request(
        url,
        {
            method: 'post',
            postBody: pars,
            onComplete: listEmployees
        });

What the above says, is that we're going to open an XMLHttpRequest that will "POST" the name/value pairs (pars) to "employee.cfm". Then, once the request is complete, the "listEmployees" function will be run. Now that we've got the insert request taken care of, let's take a look at what the CF file is doing on the back-end.

The ColdFusion File - "employee.cfm"

We know that we want to populate the database with the values in the form, and we know that the AJAX request will be "POSTing" this information. Since the request is using the "POST" method, we know we'll have to use the "FORM" variable (not URL) for grabbing the parameters being sent. Let's take a look at the CF code:

<cfif (IsDefined('Form.Action') AND Form.Action
EQ "Insert")>
    <cflock name="Insert"
type="EXCLUSIVE" timeout="30">
		        <cfquery name="insertemployee"
Datasource="employee">
			            INSERT INTO Employee (FirstName, LastName,
JobTitle, Phone, Fax)
			            VALUES ('#Form.FirstName#',
'#Form.LastName#', '#Form.JobTitle#',
'#Form.Phone#', '#Form.Fax#')
		        </cfquery>
    </cflock>
</cfif>

As you can see from the first line, this set of code will not be run unless the "Action" form parameter is defined, and that it's equal to "Insert". This is where the "&Action=Insert" name/value pair, added to the "pars" variable in the JavaScript code, comes into play. The next set of code uses a standard SQL statement to insert the data that is passed into the "Employee" table. The next set of code to get run is the query that will select everything from the "Employee" table, and then return these values in a table:

<cfquery name="listemployees"
datasource="employee">
    SELECT *
    FROM Employee
    ORDER BY LastName
</cfquery>
<table cellpadding="4">
<thead>
    <tr>
        <td><b>Last Name</b></td>
        <td><b>First Name</b></td>
        <td><b>Job Title</b></td>
        <td><b>Phone</b></td>
        <td><b>Fax</b></td>
    </tr>
</thead>
<tbody>
<cfoutput query="listemployees">
    <tr id="#EmpID#">
        <td>#LastName#</td>
        <td>#FirstName#</td>
        <td>#JobTitle#</td>
        <td>#Phone#</td>
        <td>#Fax#</td>
    </tr>
</cfoutput>
</tbody>
</table>

This table is what gets returned to the ".html" page. Remember we said that the "listEmployees" function would be run when the request is completed. It is this function that is responsible for making this table appear on the page:

function listEmployees(originalRequest){
    $('EmployeeList').innerHTML =
originalRequest.responseText;
    var doc = document.addEmployee;
    doc.FirstName.value = '';
    doc.LastName.value = '';
    doc.JobTitle.value = '';
    doc.Phone.value = '';
    doc.Fax.value = '';
}

When this function is run, the innerHTML of the "EmployeeList" placeholder div will contain the table that was created in "employee.cfm". Also added to this function is the clearing out of all the form fields.

There you have it: an example of inserting information into a database using AJAX and ColdFusion. As you can see from this example, you can use any programming language you prefer. The point of this tutorial was to explain the step-by-step process of using AJAX from front-end to back-end to front-end again, all without refreshing the users browser.

You can see this example in action by checking out a sample demo I've created for this tutorial. In this demo, you will see a little more functionality. Feel free to view the source of this file to see how other functions are handled.

Getting Started

First off, you should download an AJAX library. I recommend the Prototype javascript library. What is prototype.js anyway?

Prototype is a JavaScript framework that aims to ease development of dynamic web applications. Featuring a unique, easy-to-use toolkit for class-driven development and the nicest AJAX library around, Prototype is quickly becoming the codebase of choice for web application developers everywhere.

Basically, a guy named Sam Stephenson spent, I'm sure, an inordinate amount of time writing this great javascript file in order to make life easier on all of us. Using this file makes writing your AJAX code much easier. As mentioned earlier, the hardest part about getting started was finding documentation. So, in order to make it simpler for you, I'm going to include links to the documentation that I used to get started.

• Developer Notes for prototype.js - This documentation was exactly what I needed, and could quite possibly be the only thing you'll need. It contains some really great examples in the beginning of the document, and the contains more detailed information later on. After reading the first few paragraphs, I was able to get started, and then used the rest of the document for reference (this part of the document conveniently happens to be named "Reference for Prototype.js") haha.
• Working With Events In Prototype - How to use prototype with Keystrokes, Mouse Clicks, Mouse Hovers, etc.
• Eas y Ajax with Prototype

What To Watch Out For

Internet Explorer loves to cache everything. This is particularly a problem when you are using AJAX. What works well in Firefox, may not seem like it's working in IE. I learned this the hard way. The application I implemented AJAX on is my personal online checkbook register. So the idea was to allow a user to stay on one page, add a new transaction, submit it, and have the list show the latest transaction while also changing the account balance all without refreshing the window. This worked great in Firefox, yet nothing seemed to be happening in IE. When in actuality, the database inserts were definitely happening, yet the list and account balance refresh was not. It took me a while to figure out what and why this was happening, but finally figured it out when I came across this article "Ajax IE caching issue". It seems as though IE believes that GET requests (method="get") need to be cached, while POST requests do not. This meant changing all my requests from GETs to POSTs. Finding out how to do this took a bit of research as well, so I'm going to just give this to you here (if you already know how to do this, then feel free to ignore the following). The solution, as you'll see is extremely simple (changes are marked in bold & italic):
Example GET request:

function insertRow() {
  var url = 'ajax_file.cfm';
  var param1 = $F('p1');
  var param2 = $F('p2');
  var param3 = $F('p3');
  var pars = 'P1='
      + param1
      + '&P2='
      + param2
      + '&P3='
      + param3;
  var myAjax = new Ajax.Request(
    url,
    {
      method: 'get',
      parameters: pars,
      onComplete: runNextFunction
    });
}

Example changed to a POST request:

function insertRow() {
  var url = 'ajax_file.cfm';
  var param1 = $F('p1');
  var param2 = $F('p2');
  var param3 = $F('p3');
  var pars = 'P1='
      + param1
      + '&P2='
      + param2
      + '&P3='
      + param3;
  var myAjax = new Ajax.Request(
    url,
    {
      method: 'post',
      postBody: pars,
      onComplete: runNextFunction
    });
}

Well there you have it. The IE issue is fixed, right? Well... Not exactly. This solution only seemed to work part of the time. So, after some more digging, I found the definitive solution. Although not elegant, it fixes the problem. That solution is to add a random number parameter onto the end of the parameters that get passed. "Why would this work?" you might ask. Well this random number will basically fool the browser into thinking it has to return a page from a URL it's never been to before, rather than thinking it has it in cache (learn more).

POST Example with Random Number

function insertRow() {
  var url = 'ajax_file.cfm';
  var param1 = $F('p1');
  var param2 = $F('p2');
  var param3 = $F('p3');
  var pars = 'P1='
      + param1
      + '&P2='
      + param2
      + '&P3='
      + param3;
      + '&rnd='
      + Math.random()*99999; //using rather large multiplier to ensure uniqueness
  var myAjax = new Ajax.Request(
    url,
    {
      method: 'post',
      postBody: pars,
      onComplete: runNextFunction
    });
}

I feel that the information in this article is exactly what is needed to get your feet wet with AJAX. I plan to create a tutorial that will walk you through a real world working example of AJAX using ColdFusion and a simple MS Access Database.