At this point, it is recommended that you follow the procedure laid out below, when migrating from xajax 0.2.x to xajax 0.5

Contents

• 1. Install Xajax
• 2. Update your include directives
• 3. Update to the new syntax
  • 3.1 Response Commands
  • 3.2 Method Renaming
• 4. new syntax example
• 5. Update deprecated functions to their new versions
• 6. Quick reference

1. Install Xajax 0.5

Assuming that you have already downloaded the latest release, we recommend to backup your old install and php files first, before you start migrating to xajax 0.5. Afterwards delete your old xajax install and copy all files from the Zip files to your xajax directory. Do not copy the new version into your xajax folder before removing the old files! That will save you a lot of time and headaches.

2. Update your include directives

The xajax folder structure has changed to allow seperation of PHP and Javascript files. All PHP files are in xajax_core and all Javascript files are in xajax_js.

3. Update to the new syntax

Currently, xajax 0.5 rc2 is the latest version. At this point you should not notice a large number of syntax changes. The most changes can be done via search/replace in your favourite editor and should not take longer than a few minutes, depending on your project's size.
There are, however, a number of functions that have been marked as deprecated. As soon as possible, you should update your scripts to use the new versions of these functions as they will be removed from xajax in a future update.

Response Commands

xajaxResponse has been refactored to allow future support for other data transport methods. Currently, response commands are stored in an array; the array is converted to XML just before the response is sent. Previously, the XML was built as commands were added to the response, via string concatination.

Method Renaming

Please Note: You can use all of the old methods by instanciating new legacyXajax() instead of new xajax() and new $objResponse = new legacyXajaxResponse() instead of $objResponse = new xajaxResponse().

xajax Methods

$xajax->processRequests(); has become $xajax->processRequest();

All boolean settings such as $xajax->debugOn(); and $xajax->outputEntitiesOn(); have become $xajax->setFlag('debug',true); and $xajax->setFlag('outputEntities',true);

$xajax->setFlags(); can also take arrays like $xajax->setFlags(array('debug'=>true,'outputEntities'=>true));

$xajax->registerFunction is marked as depreciated due to the new function $xajax->register();

xajaxResponse Methods

Most xajaxResponse methods have changed. The confusing 'add' prefix has been removed from most of the functions; so, xajaxResponse->addScript() becomes xajaxResponse->script(), xajaxResponse->addAssign() becomes xajaxResponse->assign().
This makes it fun to chain responses together with PHP5:

Code: php

$response
 ->alert("Hi!")
 ->assign("myDiv", "innerHTML", $stuff)
 ->plugin('script.aculo.us')->highlight("myDiv")
 ->call('finishEditing', $newID);
 

xajaxResponse->getXML() is gone; just return the xajaxResponse object.

4. new syntax example

Old 0.2.x syntax

Code: php

require("./xajax/xajax.inc.php");
 $xajax->new xajax();
 $xajax->debugOn();
 $xajax->registerFunction('my_xajax_function');
 
 function my_xajax_function($aFormValues)
 {
 $objResponse = new xajaxResponse();
 $objResponse->addAssign('my_div_id','innerHTML','Xajax 0.5 is finally out!');
 $objResponse->addAlert('There are new updates available');
 return $objResponse->getXML();
 }
 
 $xajax->processRequests();
 ?>
 
 
 printJavaScript("/lib/xajax/"); ?>
 
 

same code in new xajax 0.5 syntax

Code: php

require("./xajax/xajax_core/xajax.inc.php");
 $xajax->new xajax();
 $xajax->setFlag('debug',true);
 $xajax->configure('javascript URI','/lib/xajax');
 
 $xajax->register(XAJAX_FUNCTION,'my_xajax_function');
 
 function my_xajax_function($aFormValues)
 {
 $objResponse = new xajaxResponse();
 $objResponse->assign('my_div_id','innerHTML','Xajax 0.5 is finally out!');
 $objResponse->alert('There are new updates available');
 return $objResponse;
 }
 
 $xajax->processRequest();
 ?>
 
 
 
 printJavaScript(); ?>
 

5. Update deprecated functions to their new versions

Most noteworthy are the following changes:

Code: php

 
$xajax->debugOn();                   is now     $xajax->configure('debug', true);
$xajax->setRequestURI(...);          is now     $xajax->configure('requestURI', ...);
$xajax->registerFunction(...);       is now     $xajax->register(XAJAX_FUNCTION, ...);
$xajax->registerCallableObject(...); is now
$xajax->register(XAJAX_CALLABLE_OBJECT, ...);
 

If you use a 'loading...' message on your page, you will need to update your javascript code. xajax 0.5 is quite flexible in this regard, so here are the three methods you can use to declare a loading message in javascript:

Configure it globally so all requests use it:

Code: javascript

 
xajax.callback.global.onRequest = function()
 {
 xajax. $('loadingMsg').style.display = 'block';
 };
 xajax.callback.global.onComplete = function()
 {
 xajax. $('loadingMsg').style.display = 'none';
 };
 

Configure it locally, so only certain requests use it:

Code: javascript

 
 
myCallback = xajax.callback.create(100, 10000);
 myCallback.onRequest = function()
 {
 xajax. $('loadingMsg').style.display = 'block';
 };
 myCallback.onComplete = function()
 {
 xajax. $('loadingMsg').style.display = 'none';
 };
 
 // then, on the PHP side, specify the callback option when registering your function:
 $xajax->register(XAJAX_FUNCTION, 'myFunction', array(
 'callback' => 'myCallback'
 ));
 

Configure it for a single request:

Code: php

 
$xajax->register(XAJAX_FUNCTION, 'myFunction', array(
 'onRequestDelay' => 'showLoadingMessage'
 ));
 

6. Quick reference

Old Code	New Code
require_once('xajax.inc.php');	require('xajax_core/xajax.inc.php');
xajax->debugOn();	xajax->configure('debug',true);
xajax->debugOff();	xajax->configure('debug',false);
xajax->statusMessagesOn();	xajax->configure('statusMessages',true);
xajax->statusMessagesOff();	xajax->configure('statusMessages',false);
xajax->decodeUTF8InputOn();	xajax->configure('decodeUTF8Input',true)
xajax->registerExternalFunction('function','file.php');	xajax->register(XAJAX_FUNCTION, new xajaxUserFunction('function', 'file.php'));
xajax->processRequests();	xajax->processRequest();
xajaxResponse->loadXML($response);	xajaxResponse->loadCommands($response);
return xajaxResponse->getXML();	return xajaxResponse;
xajaxResponse->addAlert();	xajax->alert();
xajaxResponse->addAppend();	xajax->append();
xajaxResponse->addAssign();	xajax->assign();
xajaxResponse->addClear();	xajax->clear();
xajaxResponse->addCreateInput();	xajax->createInput();
xajaxResponse->addCreate();	xajax->create();
xajaxResponse->addInsertAfter();	xajax->insertAfter();
xajaxResponse->addRedirect();	xajax->redirect();
xajaxResponse->addRemove();	xajax->remove();
xajaxResponse->addScript();	xajax->script();
xajaxResponse->addScriptCall();	xajax->call();
xajax.createInput()	xajax.forms.createInput()
xajax.create()	xajax.dom.create()
xajax.remove()	xajax.dom.remove()
xajax.loadingFunction = function(){};	xajax.callback.global.onRequest= function(){};
xajax.doneLoadingFunction = function(){};	xajax.callback.global.onComplete= function(){};
new function	xajax.callback.global.onFailure = function(args) { alert("In global.onFailure...HTTP status code: " + args.request.status); }