xAjax support :: Draft

Sahana framework incorporates xAjax php class library to provide ajax support for developers. Following example will demonstrate how to use this feature.

Example

Let us implement a registration form with user id validation. In this we will make an ajax call to the server and check if the entered user id exist or not.

Implement xajax.inc

In your module create a script called xajax.inc. All the ajax functions should be implemented in this file ( Like main.inc where all the actions are implemented).
Now we need to implement a function to validate user id. All ajax functions should have the module name as a prefix so lets name the function as 'skel_check_user'.
First register the function name as a ajax function as follows.
1. $global['xajax_functions'] is a array of all the ajax functions.

array_push($global['xajax_functions'],'skel_check_user');

Then implement the validate function.

function skel_check_user($user){
    global $global;
    if(in_array($user,$_SESSION['demo_users'])){
        // this will change the innerHTML of the element with an id named 'check'.
        $global['xajax_res']->addAssign('check','innerHTML','User id exists please select another');
    }
    else{
        $global['xajax_res']->addAssign('check','innerHTML','User id is available');
    }
    return $global['xajax_res']->getXML();
}

It takes a single argument which contains the user id we need to validate.
Use the xAjax Response object which is in $global['xajax_res'] variable to manipulate html of the page.
Finally return the xajax xml (Final return line is important and should be common to all xajax functions).

Implement Form

Now we are going to implement user registration form under a action call ajax_demo.
In the main.inc file we will define the following function.

function shn_skel_ajax_demo(){
    global $global;

Include the xajax library

    include_once $global['approot'].'/inc/lib_xajax.inc';

Register the xajax function we are going to use in this form. ( Since our validation function is “skel_check_user” lets register it)

    // this is the xajax function we are using to validate the user_id
    shn_xajax_registerFunction('skel_check_user');

Create the registration form.

    shn_form_fopen('ajax_demo');
    shn_form_fsopen('User Info');
 
    shn_form_text('User id','user_id',' onchange="skel_check_user(this.value)";');
 
    // this html element will be used to display the message
    echo "<span id='check'></span><br />";
    shn_form_text('Email','email');
    shn_form_fsclose();
    shn_form_submit('Add Me', 'onclick="return false"');
    shn_form_fclose();
}

Framework will create a JavaScript function which will map to the validation function we implement above.
To validate entered user id, assign skel_check_user() function to onchange of the textbox and pass the textbox value as an argument of that function.

You can find a working implementation of this demo under skeleton module in sahana maintrunk.

the shn_xajax_printJavascript() Function

This function can be used to output the generated xajax javascript at a convenient location in the page. By default it would be automatically called at the page footer, which wil some times result in a function not found error if your browser does javascript calls while the page is not fully loaded.

(In case you need to show a Loading… message or some thing while the page loads).

In this case you can call shn_xajax_printJavascript() explicitly in your code, before the javascript calls are made and it will ensure that the javascript is included only once per page.

include_once ($global['approot'].'/mod/snapshot/xajax.inc');
 
shn_xajax_registerFunction('snapshot_showLoading');
shn_xajax_registerFunction('snapshot_fillSnapshotDiv');
 
function shn_skel_admin_default() {
    shn_xajax_printJavascript(); // explicit inclusion of the xajax javascript. Only required in the following situation.
 
?>
    <input type="button" onclick="snapshot_showLoading()" />
    <div id="snapshotsDiv"></div>
    <script type="text/javascript">
        snapshot_showLoading(); // function that are executed on the fly while the page loads
        snapshot_fillSnapshotsDiv();
 
    </script><?php
}