I've been tagged [This link opens in a new window]

Simple AJAX and ColdFusion example

When I was first putting AJAX elements in to my websites, I must admit, it was a bit daunting at the time. The most annoying thing was trying to find an example on the web that would help me out, without going to in-depth... this was harder to find than doing the AJAX itself! Well surely I wasn't the only one, and there must be others out there now asking the same question, so I'm going to try and show you a really simple example below.

The good thing about using AJAX is once you understand the principal of how things work, you can pretty much work the rest out yourself, I know I did!

My example below will be using the fantastic Prototype Javascript framework, which makes things even easier than they already are. Download the .js from their site now, as you will need it. I use the prototype.js file for all my websites now, it has many shortcuts that save alot of time, and isn't only used for AJAX requests.

Once you have downloaded the prototype.js file you are ready to start the AJAX application. So firstly, add the prototype.js file to your applications <head> like so:

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

Now you have prototype.js running on your site you can start the real stuff. This example will show how to submit a simple name, email and message form to your inbox without the need to reload the page (well to the user anyway). So obviously you will need your simple HTML form, like below:

<div id="actiondiv"></div>
<form method="post" onsubmit="return false;">

<!--- Name --->
<label for="name">Name:</label>
<input type="text" name="name" id="name" />

<!--- Email --->
<label for="email">Email:</label>
<input type="text" name="email" id="email" />

<!--- Message --->
<label for="message">Message:</label>
<textarea name="message" id="message"></textarea>

<!--- Submit --->
<input type="button" value="Post" 
onclick="sendForm($F('name'),$F('email'),$F('message'));">
</form>

For now, ignore the onclick events that are in there, we will come to those later. As it stands, this form will do nothing, there's no submit button, and the form is being prevented from submitting at the moment. Well this is what we want as we don't want the page to reload do we, wouldn't be AJAX otherwise, so now this is where the Javascript steps in to take control of the form.

In the <head> of your document (ideally, but you can put this inline on the page if you want) add the following chunk of Javascript:

<script type="text/javascript">
function sendForm(name,email,message){
new Ajax.Updater('actiondiv','actions.cfm',{parameters:
{'name':name,'email':email,'message':message}});}</script>

This is the only Javascript you will need to submit the form via AJAX, now lets go through it.

We are creating a simple function that will capture the onclick event of the button in the HTML form earlier, so track back to the HTML form and find the onclick="sendForm($F('name'),$F('email'),$F('message'));". What this is doing is sending the values of the form fields (you can see all three of them in there [name, email and message]) to the Javascript in the <head>. So when the user presses the button, the onclick event is triggered and the contents of the form fields are sent dynamically to the <script> block in the head. At this point you may be thinking, what on earth is $F('')? Well this is a special prototype utility that captures a form fields value, its a shortcut for document.forms.formname.email.value. Prototype has several utilities that make 'javascripting' a lot easier, have a read about them here.

You will also notice a onsubmit="return false;" in the <form> tag, this tells the form NOT to submit if a user hits return.

Now we know how the form is submitting the form fields, lets look at the Javascript and see how that sends the request to ColdFusion. Its a simple function like all other Javascript functions, just with a few new prototype.js items in there.

Firstly we are telling Javascript we have a function called sendForm() on the page, and we are naming the values that are being sent from this with the (name,email,message) in the function brackets. To keep it simple, I've kept the names the same as the actual form fields, but you can name these something different if you want... Just don't get them mixed up later.

Now we use the first prototype.js method, the new Ajax.Updater method. This is the part that makes the AJAX request for you, how it works is like:

new Ajax.Updater('[element id]','[file to call]',{parameters:
{[parameters]}});

The Ajax.Updater will basically call the [file to call] in the element on the page with an id of [element id]. In this case we have a <div> with an id of actiondiv. When this function is called, it will simply process the actions.cfm file inside the <div> with the id of actiondiv. This actions.cfm file will contain all your ColdFusion to send the form to the email address (or store in a database... whatever you want to do).

If you have output in this actions.cfm file, upon this function being called, you will see those contents displayed in the <div> dynamically, alternatively, have no output in the actions.cfm file and just have cfml in there and the user will never know anything happened.

That's it, your form is now dynamically sending its contents to your ColdFusion page via AJAX, simple!

That is the basic principal of AJAX, and these rules can be followed for many other AJAX functions. Prototype as many more functions, have a read of their documentation and it will explain everything. Once you have got a few AJAX applications working, have a look at script.aculo.us for some fancy features to add on top of prototype.js

  • Del.icio.us [This link opens in a new window]
  • Digg [This link opens in a new window]
  • Technorati [This link opens in a new window]
  • Reddit [This link opens in a new window]
  • Stumble Upon [This link opens in a new window]
  • Furl [This link opens in a new window]

Article Archive

RSS Feed

Latest Projects

Latest Articles