Darren Pangan

Developing Ajax Applications with Sajax

Have you ever tried making your web applications super interactive by using Ajax? If you're proficient in Javascript and any server-side scripting language (PHP, ASP, etc.) you wouldn't have any problem and you can probably learn and start developing Ajax-powered web application in a few hours after reading up on some online tutorials about the XMLHttpRequest object and Ajax. But as you go on developing your Ajax-powered application, you'll probably think about making your work easier by creating another utility class (server-side and Javascript) that should make your web development easier. I know I have and I have created several Javascript functions that I used in some AJAX-powered web applications that I've created in the past.

But later on, I learned about this programming toolkit that should make Ajax development much easier. After using it for a while, I realized that I'm already using it in almost every Ajax-powered scripts that I make. This is because it's so easy to use and saves me a lot of time. The programming toolkit I'm talking about is called Sajax. Sajax, actually, stands for Simple Ajax Toolkit and it's an open-source software written in several server-side scripting languages including ASP, Coldfusion, Perl, Python, and of course, PHP. In this tutorial, I'm going to show how to use Sajax. I plan on writing lots tutorials about Ajax-powered web applications using Sajax so this will be a good introduction.

The Sajax Toolkit

First of all, download the Sajax toolkit. Like I said earlier, it can be used on several server-side programming languages but in this tutorial, we're only going to cover PHP. Of course, you will need a webserver that supports PHP (almost all popular web hosting companies support PHP) to test the samples here. If you have such web hosting account, good. If you run a test web server that supports PHP on your local PC, ever better.

Once you have downloaded and unpacked the archive, browse through the directories and look for Sajax.php (located under the directory named "php"). This is the only file you need to include in your web applications in order to run Sajax. Create a directory in your web server where you will run the samples. In this tutorial, only 2 files will be used - the Sajax include file and the PHP script that will run a very simple Ajax web application.

Defining server-side functions that will be called through Ajax

The program that we're going to make in this tutorial is really very simple. We're going to write one PHP function that will return a string value. Then we'll execute this function using Sajax and some Javascript function. The string value returned will be printed out in the browser screen without refreshing the page.

Basically, using Sajax involves six steps:

1. Include the Sajax library.
2. Define your functions.
3. Call sajax_init() function.
4. Export the PHP functions using sajax_export().
5. Call sajax_handle_client_request() function.
6. Place the Javascript code in the client page using sajax_show_javascript().

The code below shows all these six steps implemented. Examine this sample code. I've placed lots of comments to guide you through the whole process.

This sample code shows exactly how it's done. Just keep in mind that you should call sajax_show_javascript() within >script< tags because the output of this function are Javascript codes.

Calling server-side functions using Sajax

Now that the server-side function is all set, the next thing we need to do is create a function (or set of functions) that will utilize this server-side script. Remember that our user-defined, server-side function simply returns a string value - "Hello, World!". What we need to do now is catch this return value and place it in an HTML container element (we'll use a div). We need two functions to do this, one will catch the return value and pass it to the next function. The other function will place it in the container. These two functions can be found implemented in the sample code below.

In the first function, you'll notice that there's a function named "x_greet". This function is automatically defined by Sajax to call the server-side function "greet". To call, server-side functions exported to Sajax, simply ad "x_" before the function name. You can then use this function as a Javascript function. Just keep in mind that the very last parameter of this javascript function will be another Javascript function that will handle the return value of the server-side script. All parameters prior to that must be the parameters required by the server side function. That meas if our "greet" server-side function requires one parameter:

The javascript function generated by sajax should be called this way:

Take note that the server-side function can have many parameters. When this is the case, just make sure that the return value handler name is the last parameter of the generated Sajax javascript function.

Let's see if it works

Everything is all set now except for the HTML user interface. The HTML interface in this example only needs two elements - the container div (should be named "greetings") and the link or button (let's use a link) that will call the Javascript "js_greet" function. These two elements can be found in the sample code below.

Putting it all together, the code should look something like this (minus the comments):

If you have this script uploaded to your web server along with the Sajax library in the same directory, you can test to see if it works. When you click the link that says "Greet!", the string "Hello, World!" should print in the browser screen without refreshing the page. If it doesn't work, check your code, make sure you followed all the steps correctly.

Posted on: May 18, 2008     Filed under: AJAX