Category: Tutorials for xajax 0.2

Tutorials:Creating Custom Response Commands

Xajax can be extended with all kinds of additional custom functionality. The extendability of xajax is made possible by the addScript() method of the xajaxResponse class and by PHP's object oriented ability to extend classes.

Using addScript()

The addScript() method of the response class allows you to return custom Javascript code from function registered with xajax to be run on the client side.

For instance, let's say that you need to use xajax to dynamically add options to select box elements. To accomplish this using the xajaxResponse class, you would construct the necessary Javascript in a string and then invoke the xajaxResponse addScript() method. Like this:

$objResponse = new xajaxResponse();

$sScript  = "var objOption = new Option('New Option', '1');";
$sScript .= "document.getElementById('select1').options.add(objOption);";
$objResponse->addScript($sScript);

return $objResponse;

This response will send the javascript back to client where xajax will run it, adding an option with the text "New Option" and the value of "1" to the select box with id "select1". That works pretty well. However, if the application you are programming requires that you frequently add options like this to various select boxes, and you copy and modify this code throughout your application, the code can quickly become cluttered, hard to read, and difficult to change and maintain.

Additionally, while asynchronously passing Javascript with the addScript() method seems cool and can be useful, in order to take advantage of browser caching and not have to pass back the Javascript every time, it is better to create a Javascript function in client side code/markup of your application or in an external Javascript file, and then call it using the addScript() method. Like this:

Client side:

<script type="text/javascript">
function addOption(selectId, txt, val)
{
    var objOption = new Option(txt, val);
    document.getElementById(selectId).options.add(objOption);
}
</script>

Server side:

$objResponse->addScript("addOption('select1', 'New Option', '13');");

By placing the Javascript function on the client side and invoking it via the addScript() method, we allow the browser to cache and reuse the Javascript and we avoid having to pass back the entire Javascript code in every xajax response. Using this approach improves performance and maintainability.

Extending the xajaxResponse class

To further improve the maintainability and readability of your code, you can leverage the object oriented aspects of the PHP language to create a custom response class that extends the standard xajaxResponse class by adding custom methods for the functionality you frequently use, while still providing all of the standard response methods.

For instance, continuing our example from above, you might extend the xajaxResponse class to include a generic method for adding select box options like this:

class myXajaxResponse extends xajaxResponse
{  
    function addCreateOption($sSelectId, $sOptionText, $sOptionValue)  
    {  
        $sScript  = "var objOption = new Option('".$sOptionText."', '".$sOptionValue."');";
        $sScript .= "document.getElementById('".$sSelectId."').options.add(objOption);";
        $this->addScript($sScript);
    }
}

Or, if you have created a Javascript function to take advantage of browser caching and to avoid having to pass back the Javascript code in every response, as described above, you would created your custom response class like this:

class myXajaxResponse extends xajaxResponse
{  
    function addCreateOption($sSelectId, $sOptionText, $sOptionValue)  
    {  
        $this->addScript("addOption('".$sSelectId."', '".$sOptionText."', '".$sOptionValue."');");
    }
}

Now, instead of instantiating an xajaxResponse object in functions registered with xajax, you instantiate and use your custom myXajaxResponse object:

$objResponse = new myXajaxResponse();

//standard methods are still available
$objResponse->addAssign("div1", "innerHTML", "Some Text");   

//you can use your custom methods as well
$objResponse->addCreateOption("select1", "New Option", "13");
 
return $objResponse;

Using an extended response class allows you to efficiently re-use common code and makes your code significantly easier to read, maintain, and extend. Once you have added a method to create new select box options, you could add another method that takes an array of options and creates them. Like this:

class myXajaxResponse extends xajaxResponse
{  
    function addCreateOption($sSelectId, $sOptionText, $sOptionValue)  
    {  
        $this->addScript("addOption('".$sSelectId."', '".$sOptionText."', '".$sOptionValue."');");
    }

    function addCreateOptions($sSelectId, $aOptions)
    {
        foreach($aOptions as $sOptionText => $sOptionValue)
        {
            $this->addCreateOption($sSelectId, $sOptionText, $sOptionValue);
        }
    }
}

Now you can dynamically add groups of options to select boxes like this:

$objResponse = new myXajaxResponse();
    
$aOptions['One'] = 1;
$aOptions['Two'] = 2;
$aOptions['Three'] = 3;
$objResponse->addCreateOptions("select1", $aOptions);
 
return $objResponse;

As you can see, the possibilities are virtually limitless.

Extending the xajaxResponse class in this way can also help you integrate third party Javascript libraries into your xajax applications. Just as we extended the response class to be able call our client side Javascript function for adding select box options, we can extend the class to add response methods for calling the 3rd party Javascript functions.

Another advantage of extending the response class is that it keeps your custom needs separate from the xajax core library so that when you upgrade to new versions of xajax you wont have to go through the new code to add whatever custom functionality you might have unfortunately hacked into the previous version. Using extended response classes, you will only have to install the new xajax library, possibly make any necessary changes in your customized xajax classes, and then continue to use your extended classes throughout your application code.

Hopefully, this tip/trick will help developers make better use of xajax in their application development. If you have extended the response class and added custom methods that other xajax users might find useful, please post them in the forum for the benefit of the community. Some of your ideas could very well make their way into future xajax releases!