Introduction To Xajax

Abstract

The Xajax class has come far in its progress and now the API has stabilized it is ready for work. This tutorial brings the absolute basics to get started with Xajax.

Hello World

Like all things, starting at the beginning is best. This script provides the absolute basics to getting Xajax working. The process is quite simply when broken down into smaller chunks. Like any PHP library, the class definition needs to be included. With xajax it is the xajax.inc.php bootstrap file that loads up the xajax environment and makes ready the ajax processes internally.
Xajax generates javascript code and provides a bridge, or callback, to PHP functions. To let Xajax know which functions are to be called, they must first be registered. The simple API of Xajax provides a register() function for this task. In the example below, the showText PHP function is registered.
When the register function is called, the returned object can be used to set parameters. In this example, the object is assigned to a variable named $rqstButton which is used later in the HTML to gene rate the onclick event code.
With the function registered, the requested function can be processed. This means the javascript for required to make a callback to PHP is generated internally and is ready to be retrieved with either the printJavascript() or getJavascript() methods.
The printJavascript() method, as the name suggests, just prints the javascript. However, a little more separation is nice, so the generated javascript can be assigned to a variable with the getJavascript() method. In these examples, the getJavascript() method is used to provide an level of separation between the HTML display code, and the PHP logic.

In the HTML, a simple echo statement is used to display the javascript generated by xajax. A little further down a call is made with javascript onClick event. The value for the onClick event is held in the rqstButton object and is simply echoed and that is really about all the javascript knowledge needed to get started, Xajax will do the rest.
But what of the showText() function itself? This function now becomes the engine room for the process. The content is contain in this function, however, in larger applications, the data may be sourced from external resources such as a database or file. A new response object is created, which will contain the information needed by xajax to perform the required actions. Again, the simple API provides a method to assign the content contained in the $content variable, to the innerHTML property of the target div named "my_div". The object response is returned and the task is complete.


    /*** include the xajax bootstrap ***/
    include 'xajax/xajax_core/xajax.inc.php';

    /*** a new xajax object ***/
    $xajax = new xajax();

    /*** register a PHP function with xajax ***/
    $rqstButton = $xajax->register(XAJAX_FUNCTION, 'showText');

    /*** set the request button parameters ***/
    $rqstButton->setParameter(0, XAJAX_JS_VALUE, 0);

    /*** process the request ***/
    $xajax->processRequest();


    function showText()
    {
        /*** the content to assign to the target div ***/
            $content = 'Hello World';

        /*** a new response object ***/
        $objResponse = new xajaxResponse();

        /*** assign the innerHTML attribute to the new $content ***/
        $objResponse->assign("my_div","innerHTML", $content);

        /*** return the object response ***/
        return $objResponse;
    }

    /*** process the request ***/
    $xajax->processRequest();

    /*** the path is relative to the web root mmmk ***/
    $xajax_js = $xajax->getJavascript('/xajax');?>






echo $xajax_js; ?>


->printScript(); ?>">Click me
New text will happen here

Manually Calling Requests

In the above code, the javascript to create the onClick event was generated by an object returned by the register() function. While the registration of the function needs to occur, the assigning of the variable does not, and the call could be made manually in the HTML document.



    /*** include the xajax bootstrap ***/
    include 'xajax/xajax_core/xajax.inc.php';

    /*** a new xajax object ***/
    $xajax = new xajax();

    /*** register a PHP function with xajax ***/
    $xajax->register(XAJAX_FUNCTION, 'showText');

    /*** process the request ***/
    $xajax->processRequest();


    function showText()
    {
        /*** the content to assign to the target div ***/
        $content = 'Hello World';

        /*** a new response object ***/
        $objResponse = new xajaxResponse();

        /*** assign the innerHTML attribute to the new $content ***/
        $objResponse->assign("my_div","innerHTML", $content);

        /*** return the object response ***/
        return $objResponse;
    }

    /*** process the request ***/
    $xajax->processRequest();

    /*** the path is relative to the web root mmmk ***/
    $xajax_js = $xajax->getJavascript('/xajax');?>






echo $xajax_js; ?>


Click me
New text will happen here

Debugging

Perhaps the most important functionality in the Xajax library is the debug option. When set, the debug option sends a print-out of the whole request process. This will prove invaluable when a script is not behaving as expected.
The debug flag is set, in most instances, immediately after the xajax object is instantiated. This means it will look a little like this.


    /*** include the xajax bootstrap ***/
    include 'xajax/xajax_core/xajax.inc.php';

    /*** a new xajax object ***/
    $xajax = new xajax();

    /*** set the debug flag ***/
    $xajax->setFlag('debug', true);

    /*** rest of script follows ... ***/
?>