AJASON

Digg it

del.icio.us

Blink it

Installation

Extract the archive into a temporary directory. Move the file php/Ajax.php and the directory php/Ajax into the folder of your web project where you store your php libraries, for example htdocs/mywebproject/php. Move the files from javascript into your project specific JavaScript folder (e.g. htdocs/mywebproject/javascript).

Using

The first thing you want to do is to include the JavaScript files ajax.js and json.js in your PHP/HTML document where you are going to use AJASON functionality. It is very important that these scripts are included before any AJASON generated JavaScript code:

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

In your PHP document load the file Ajax.php and create an instance of the Ajax class:

	require_once( 'php/Ajax.php' );
	$ajax = new Ajax();

Now register all funtions and class/object methods which should be callable from the JavaScript client:

	$ajax->registerFunction( 'exampleFunction' );
	$ajax->registerMethod( 'ExampleClass', 'exampleMethod' );

If you are going to register a method please note that you can only use static methods or methods of objects which do not require mandatory parameters in the constructor. Constructors will always be called without any parameter! Also keep in mind that the first parameter of registerMethod() is the name of the class not an object.

Now it's time spawn the server object of Ajax and check whether a server request has occured:

	$ajaxServer = $ajax->getServer();
	if ( $ajaxServer->isRequest() )
	{
	  echo $ajaxServer->handleRequest();
	  exit();
	}

If isRequest() returns true a server request is in the process. Let's handle the request and exit the script. If not then there's more to do:

	$ajaxClient = $ajax->getClient();

The client is reponsible for creating the JavaScript code. Use the method getJavaScript() to render it at the appropriate position somewhere in your HTML document:

	<head>
	...
	<script type="text/javascript" src="javascript/json.js"></script>
	<script type="text/javascript" src="javascript/ajax.js"></script>
	<script type="text/javascript">
	<?php echo $ajaxClient->getJavaScript(); ?>
	</script>
	...
	</head>

Now let me explain to you how you call a PHP function/method with JavaScript. First have a look at the following code snippet:

	<script type="text/javascript">
	function example_cb( response )
	{
    	document.getElementById( 'inputExample' ).value = response;
	}
	</script>

	<form>
	<input type="text" id="inputExample" name="inputExample" />
	<input type="button" id="buttonExample" name="buttonExample"
    	onclick="x_ExampleClass.exampleMethod( "hello world!", example_cb );" 
    	value="Click me" />
	</form>

In the onclick event of the button the method exampleMethod of the class ExampleClass - which we registered previously - is being called. You can pass a variable amount of parameters whereas the last argument can be a function which is then used as a callback function. A callback function will be called as soon as the response from the server has been completely arrived. The response data, which can be a scalar value, an array, an object or any combination of these (e.g. array of objects) is passed to the callback function as the first parameter. You don't need to use a callback function but if you are going to please note that the number of parameters passed to the PHP function/method is n-1 because the callback function won't be passed to the server.

You may have noticed that the name of the class has changed from ExampleClass to x_ExampleClass within JavaScript. This is the default behaviour for all function and class names which are prepended with "x_".