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.


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.
  • Then implement the validate function.
function skel_check_user($user){
    global $global;
        // 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');
        $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
  • Create the registration form.
    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_submit('Add Me', 'onclick="return false"');
  • 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');
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

xAjax Response Object

To learn more about how to use the xAjax response object visit http://xajaxproject.org/wiki/Documentation:xajaxResponse.inc.php

  • Navigate