DOM scripting/AJAX function
As mentioned in my last article, I’m going to introduce you to some code that will simplify the use of basic Ajax-style functionality. I have a small collection of code snippets that allow you to do several things, but for now I’m going to concentrate on just one of them: loading data from a file on the server to a specific part of a web page without refreshing the whole page.
The name I thought of for this little function is Refresher. Other functions I’ve come up with using similar techniques are called Toggler, Sender, Swapper and Submitter. Snappy, eh? The functions and supporting code are all available to download from the experiments area on my website. These functions are all written in PHP, but they are simple enough to be converted to ASP or something else quite easily.
So, onto a bit of background. What we want to do is click a link which will send a request to a website, passing some additional parameters if required, then load the resulting content into a specified portion of the page. I could have got a whole lot more complex, using XML, forms and authentication, but this fitted the bill for my requirements at the time and I expect it will do much of what I need it to do for a long time.
So the bits of information we need are: the page we want to request, the parameters we want to send (if any), the resulting portion of the page to receive the result, and for good measure an optional timeout value. The timeout is the number of milliseconds the script should wait before executing. I’ll show you why I use timeout later on.
Instead we use the power of the DOM to target specific elements and assign actions to them for specific events. For this function I assign a "click" event to any element which is set as a "refresher" link, then send the parameters needed to perform the function using the elements ID. Sound complicated? It is, but I’ll try to explain it the best I can.
Creating the page
Firstly we need to create the web page. Something like this will do fine. Notice I’ve added a DIV to the page with the text "Current time:" and a link with the text "Click me to update the time". Further explanation should not be necessary for that.
Next we need to give the the DIV an id attribute which will uniquely identify it in the page. IDs must contain only the characters a-z (upper or lower case, but you need to to stick to the same capitalisation scheme throughout the document as this makes it much easier to read later on), 0-9, "-", "_" and ".". In this case I’m calling my DIV "showTheTime". Some browsers have problems with the underscore in id attributes, so I stick with alphanumeric characters, the period and the dash. Later on you’ll see why some special characters in id attributes are crucial to the working of the Refresher function.
Making the page all Refreshed
Next we include the Refresher function file in the head of the document. The code is simple:
<head>... <? include "refresher.php"; ?> ...</head>
<a href="" class="refresher">Click me to update the time</a>
Then we need to create a special id attribute for this link which can be used to pass the right parameters to the Refresher function. This is done using the PHP "refresherID" function:
<a href="" class="refresher" id="<? print refresherID('showTheTime','../loadtime.php','showtime=true',1000); ?>">Click me to update the time</a>
This is where Refresher really kicks in. There are four parameters passed to the refresherID function:
‘showTheTime’ is the name of the target elements (remember we called our DIV this a little while ago?)
‘../loadtime.php’ is the page we wish to call
‘showtime=true’ are the additional parameters to be sent to the processing page. These will be sent using the querystring (GET method) so they should be encoded
‘1000’ is the number of milliseconds before the function should execute
Have a look at the source code of the final demonstration page to see how it looks for our example.
How the script works
The Refresher script is actually a series of functions that do several things. Here they are in a nutshell (or an unordered list, for the pedantics among you):
- Sets up listeners to "listen" to every link that has class="refresher"
- When one of those links is clicked, start the Refreshment process
- The Refreshment process decodes the ID of the link clicked and creates the call to run the XmlHttpRequest function after the specified timeout interval
- The XmlHttpRequest process sends the request and receives the resulting HTML
- The HTML is then pasted back into the page inside the specified element
Running the whole thing
So, as you can see, nothing more needs to be done to get the whole caboodle ticking. As can be seen in the the demonstration page the function works with minimal HTML and just one PHP include file.