AJAX AGENT - helping WEB become the platform

AJAX AGENT - Documentation

AJAX Agent can be used to invoke a remote scripting call in just three simple steps. Following is the PHP version of implementation.

1. Include the Ajax Agent library.

include_once('agent.php');

This will initialize the Agent framework & instantiate the server side agent. This line needs to be declared after the server function declarations & before the start of HTML tags in the document.

2. Initialize the server agent.

$agent->init();

This will create the client-side JavaScript block which initializes the client Agent when the browser renders the page. This line needs to be placed in the HEAD section of the document (between the <HEAD> & </HEAD> tag)

3. Use the 'call' method of the client Agent to invoke the server function.

agent.call('url','server_function', 'client_handle', param1, param2, ...);

The first parameter is the URL of the file where the server function exists. This URL which is typically a PHP script file should have the following lines at the end of the script.

<?php
  include_once("agent.php");
  $agent->init(); 
?>

If this parameter is left blank, the Agent will look for the server function in the same file & invoke it.

The second parameter is the server function name. In this case it's the PHP function. If this parameter is left blank, the Agent calls the URL sending the first parameter (param1) as post variable string.

The third parameter can either be a document object (like layer or form object) or a client callback function. The Agent looks into document to see if there is a document object by that name. If the Agent finds it, it updates the innerHTML or the value property (whichever is appropriate) of that object with the result from the call. If no such object exists in the document, it looks for a function with that name. If it finds one, it treats this function as a callback function, sends the result as the parameter to this function & triggers it. If it doesn't find the function, the Agent creates a variable by that name & assigns the result from the call as it's value. All these action happens asynchronously.

This parameter can be left blank. In this case, the Agent assumes that the call is synchronous. The result from the server function call will be return value of this call.

The fourth & the subsequent parameters (optional) are the parameters for the server function. These parameters can be integers, strings, associated arrays or objects.

Check the following code listing.

<?php 
  // server side function
  function hello() {
    return "Hello World from server! The server time is ".date("H:i:s");
  }
?>
<?php 
  // STEP 1: INCLUDING AJAX AGENT FRAMEWORK/LIBRARY
  include_once("agent.php");
?>

<html>
<head>
<title>My Ajax Agent Test Page</title>
<?php
  // STEP 2: INITIALIZING SERVER AGENT TO CREATE CLIENT AGENT
  $agent->init(); 
?>
</head>
<body>
  <script language="JavaScript">

    // client function  
    function call_hello() {
      // STEP 3: CALLING SERVER FUNCTION FROM CLIENT AGENT
      agent.call('','hello','callback_hello');
    }
    // client callback function
    function callback_hello(str) {
      alert(str);
    }
  </script>

<a href="javascript:call_hello();">Test the hello function</a>

</body>
</html>

Check the cool demos section to see this toolkit in action along with source code listings. You can download these demos from the downloads section. Check the FAQ section to learn more about this toolkit.