Category: Documentation

Documentation:xajax.inc.php

The xajax class generates the xajax Javascript for your page including the Javascript wrappers for the PHP functions that you want to call from your page. It also handles processing and executing the command messages in the XML responses sent back to your page from your PHP functions.

[edit] Global Constants

[edit] XAJAX_DEFAULT_CHAR_ENCODING string (defaults to "utf-8")

Used by both the xajax and xajaxResponse classes. You can manually define this in your own PHP script to override xajax's default.

[edit] XAJAX_GET int (defaults to 0)

Represents an xajax request using HTTP GET

[edit] XAJAX_POST int (defaults to 1)

Represents an xajax request using HTTP POST

[edit] Object Variables (protected)

[edit] $aFunctions

• Var: (array): Array of PHP functions that will be callable through javascript wrappers

[edit] $aObjects

• Var: (array): Array of object callbacks that will allow Javascript to call PHP methods (key=function name)

[edit] $aFunctionRequestTypes

• Var: (array): Array of RequestTypes to be used with each function (key=function name)

[edit] $aFunctionIncludeFiles

• Var: (array): Array of Include Files for any external functions (key=function name)

[edit] $sCatchAllFunction

• Var: (string): Name of the PHP function to call if no callable function was found

[edit] $sPreFunction

• Var: (string): Name of the PHP function to call before any other function

[edit] $sRequestURI

• Var: (string): The URI for making requests to the xajax object

[edit] $sWrapperPrefix

• Var: (string): The prefix to prepend to the javascript wraper function name

[edit] $bDebug

• Var: (boolean): Show debug messages (default false)

[edit] $bStatusMessages

• Var: (boolean): Show messages in the client browser's status bar (default false)

[edit] $bExitAllowed

• Var: (boolean): Allow xajax to exit after processing a request (default true)

[edit] $bWaitCursor

• Var: (boolean): Use wait cursor in browser (default true)

[edit] $bErrorHandler

• Var: (boolean): Use an special xajax error handler so the errors are sent to the browser properly (default false)

[edit] $sLogFile

• Var: (string): Specify what, if any, file xajax should log errors to (and more information in a future release)

[edit] $bCleanBuffer

• Var: (boolean): Clean all output buffers before outputting response (default false)

[edit] $sEncoding

• Var: (string): String containing the character encoding used

[edit] $bDecodeUTF8Input

• Var: (boolean): Decode input request args from UTF-8 (default false)

[edit] $bOutputEntities

• Var: (boolean): Convert special characters to HTML entities (default false)

[edit] $aObjArray

• Var: (array): Array for parsing complex objects

[edit] $iPos

• Var: (integer): Position in $aObjArray

[edit] Object Methods (public)

[edit] xajax (string $sRequestURI="", string $sWrapperPrefix="xajax_", string $sEncoding=XAJAX_DEFAULT_CHAR_ENCODING, boolean $bDebug=false)

Constructor. You can set some extra xajax options right away or use individual methods later to set options.

• $sRequestURI (string): defaults to the current browser URI
• $sWrapperPrefix (string): defaults to "xajax_";
• $sEncoding (string): defaults to XAJAX_DEFAULT_CHAR_ENCODING defined above
• $bDebug (boolean): defaults to false

[edit] setRequestURI (string $sRequestURI)

Sets the URI to which requests will be made.

Usage:

$xajax->setRequestURI("http://www.xajaxproject.org");

• $sRequestURI (string): the URI (can be absolute or relative) of the PHP script that will be accessed when an xajax request occurs

[edit] setWrapperPrefix ($sPrefix)

Sets the prefix that will be prepended to the Javascript wrapper functions (default is "xajax_").

[edit] debugOn ()

Enables debug messages for an xajax request.

[edit] debugOff ()

Disables debug messages for an xajax request (default behavior).

[edit] statusMessagesOn ()

Enables messages in the browser's status bar for xajax.

[edit] statusMessagesOff ()

Disables messages in the browser's status bar for xajax (default behavior).

[edit] waitCursorOn ()

Enables the wait cursor to be displayed in the browser (default behavior).

[edit] waitCursorOff ()

Disables the wait cursor to be displayed in the browser.

[edit] exitAllowedOn ()

Enables xajax to exit immediately after processing a request and sending the response back to the browser (default behavior).

[edit] exitAllowedOff ()

Disables xajax's default behavior of exiting immediately after processing a request and sending the response back to the browser.

[edit] errorHandlerOn ()

Turns on xajax's error handling system so that PHP errors that occur during a request are trapped and pushed to the browser in the form of a Javascript alert.

[edit] errorHandlerOff ()

Turns off xajax's error handling system (default behavior).

[edit] setLogFile (string $sFilename)

Specifies a log file that will be written to by xajax during a request (used only by the error handling system at present). If you don't invoke this method, or you pass in "", then no log file will be written to.

Usage:

$xajax->setLogFile("/xajax_logs/errors.log");

[edit] cleanBufferOn ()

Causes xajax to clean out all output buffers before outputting a response (default behavior).

[edit] cleanBufferOff ()

Turns off xajax's output buffer cleaning.

[edit] setCharEncoding (string $sEncoding)

Sets the character encoding for the HTTP output based on <kbd>$sEncoding</kbd>, which is a string containing the character encoding to use. You don't need to use this method normally, since the character encoding for the response gets set automatically based on the <kbd>XAJAX_DEFAULT_CHAR_ENCODING</kbd> constant.

Usage:

$xajax->setCharEncoding("ISO-8859-1");
// or:
$xajax->setCharEncoding("utf-8");
// etc.

• $sEncoding (string): the encoding type to use (utf-8, ISO-8859-1, etc.)

[edit] decodeUTF8InputOn ()

Causes xajax to decode the input request args from UTF-8 to the current encoding if possible. Either the iconv or mb_string extension must be present for optimal functionality.

[edit] decodeUTF8InputOff ()

Turns off decoding the input request args from UTF-8 (default behavior).

[edit] outputEntitiesOn ()

Tells the response object to convert special characters to HTML entities automatically (only works if the mb_string extension is available).

[edit] outputEntitiesOff ()

Tells the response object to output special characters intact. (default behavior).

[edit] registerFunction (mixed $mFunction, string $sRequestType=XAJAX_POST)

Registers a PHP function or method to be callable through xajax in your Javascript. If you want to register a function, pass in the name of that function. If you want to register a static class method, pass in an array like so:

array("myFunctionName", "myClass", "myMethod")

For an object instance method, use an object variable for the second array element (and in PHP 4 make sure you put an & before the variable to pass the object by reference). Note: the function name is what you call via Javascript, so it can be anything as long as it doesn't conflict with any other registered function name.

Usage:

$xajax->registerFunction("myFunction");
// or:
$xajax->registerFunction(array("myFunctionName", &$myObject, "myMethod"));

• $mFunction (mixed): contains the function name or an object callback array
• $sRequestType (mixed): request type (XAJAX_GET/XAJAX_POST) that should be used for this function. Defaults to XAJAX_POST.

[edit] registerExternalFunction (mixed $mFunction, string $sIncludeFile, string $sRequestType=XAJAX_POST)

Registers a PHP function to be callable through xajax which is located in some other file. If the function is requested the external file will be included to define the function before the function is called.

Usage:

$xajax->registerExternalFunction("myFunction","myFunction.inc.php",XAJAX_POST);

• $mFunction (string): contains the function name or an object callback array (see registerFunction for more info on object callback arrays)
• $sIncludeFile (string): contains the path and filename of the include file
• $sRequestType (mixed): the RequestType (XAJAX_GET/XAJAX_POST) that should be used for this function. Defaults to XAJAX_POST.

[edit] registerCatchAllFunction (mixed $mFunction)

Registers a PHP function to be called when xajax cannot find the function being called via Javascript. Because this is technically impossible when using "wrapped" functions, the catch-all feature is only useful when you're directly using the xajax.call() Javascript method. Use the catch-all feature when you want more dynamic ability to intercept unknown calls and handle them in a custom way.

Usage:

$xajax->registerCatchAllFunction("myCatchAllFunction");

The first argument of the PHP function contains the name of the function called. The second argument is an array that contains the arguments.

For example:

function myCatchAllFunction($calledFunctionName, $args) { }

• $mFunction (string): contains the function name or an object callback array (see registerFunction for more info on object callback arrays)

[edit] registerPreFunction (mixed $mFunction)

Registers a PHP function to be called before xajax calls the requested function. xajax will automatically add the request function's response to the pre-function's response to create a single response. Another feature is the ability to return not just a response, but an array with the first element being false (a boolean) and the second being the response. In this case, the pre-function's response will be returned to the browser without xajax calling the requested function.

Usage:

$xajax->registerPreFunction("myPreFunction");

• $mFunction (string): contains the function name or an object callback array (see registerFunction for more info on object callback arrays)

It is useful if you want to do some security check before execute the requested function. You can use registerPreFunction() to register a security check function. If security check succeed, return $objResponse will let xajax to continue calling the requested function. Otherwise, return array(FALSE, $objResponse) and xajax will stop calling anything.

[edit] canProcessRequests ()

Returns true if xajax can process the request, false if otherwise. You can use this to determine if xajax needs to process the request or not.

• Return: boolean

[edit] getRequestMode ()

Returns the current request mode (XAJAX_GET or XAJAX_POST), or -1 if there is none.

• Return: mixed

[edit] processRequests ()

This is the main communications engine of xajax. The engine handles all incoming xajax requests, calls the appropriate PHP functions (or class/object methods) and passes the XML responses back to the Javascript response handler. If your RequestURI is the same as your Web page then this function should be called before any headers or HTML has been sent.

NOTE: This function should only be called once after all of your xajax functions have been registered. If you call this function twice, any functions registered between the first and any subsequent calls to processRequests will be ignored. This is only an issue if your web page uses multiple files to deal with any xajax registering of functions.

Example:

$xajax->registerFunction("foo");
$xajax->processRequests();
$xajax->registerFunction("bar");
$xajax->processRequests();

Any attempt to call xajax_bar() in your html will fail. A call to xajax_foo() will work.

NOTE: All code from the start of a file to the xajax processRequests call will be executed every time an xajax call is made in your client.

$xajax->registerFunction("foo");
$result = big_long_ugly_CPU_intensive_function_call();
$xajax->processRequests();
another_big_function_call($result);

When you call xajax_foo() from your client, this file will execute everything up to the call to processRequests(), so the big, ugly function will be run, even though it's result isn't needed, because execution will stop after processRequests() recognizes that it has a pending request.

[edit] printJavascript (string $sJsURI="", string $sJsFile=NULL)

Prints the xajax Javascript header and wrapper code into your page by printing the output of the getJavascript() method. It should only be

<head> </head>

Remember, if you only want to obtain the result of this function, use {* Link: xajax::getJavascript()} instead.

Usage:

<head>
    ...
   <?php $xajax->printJavascript(); ?>
    ...
</head>

• $sJsURI (string): the relative address of the folder where xajax has been installed. For instance, if your PHP file is "http://www.myserver.com/myfolder/mypage.php" and xajax was installed in "http://www.myserver.com/anotherfolder", then $sJsURI should be set to "../anotherfolder". Defaults to assuming xajax is in the same folder as your PHP file.
• $sJsFile (string): the relative folder/file pair of the xajax Javascript engine located within the xajax installation folder. Defaults to xajax_js/xajax.js.
• ONLY IN xajax 0.2, NOW REMOVED $sJsFullFilename can be set to the absolute file path of the xajax.js file wherever it is located. You only need to use this argument if your xajax_js folder has been moved to a completely different location than from within the xajax installation folder.

[edit] getJavascript (string $sJsURI="", string $sJsFile=NULL)

Returns the xajax Javascript code that should be added to your HTML page between the <head></head> tags.

Usage:

<?php $xajaxJSHead = $xajax->getJavascript(); ?>
<head>
    ...
    <?php echo $xajaxJSHead; ?>
    ...
</head>

• $sJsURI (string): the relative address of the folder where xajax has been installed. For instance, if your PHP file is "http://www.myserver.com/myfolder/mypage.php" and xajax was installed in "http://www.myserver.com/myfolder/my_scripts/xajax", then $sJsURI should be set to "my_scripts/xajax". Defaults to assuming xajax is in the same folder as your PHP file.
• $sJsFile (string): the relative folder/file pair of the xajax Javascript engine located within the xajax installation folder. Defaults to xajax_js/xajax.js.
• Return: string

[edit] getJavascriptConfig ()

Returns a string containing inline Javascript that sets up the xajax runtime (typically called internally by xajax from get/printJavascript).

• Return: string

[edit] getJavascriptInclude (string $sJsURI="", string $sJsFile=NULL)

Returns a string containing a Javascript include of the xajax.js file along with a check to see if the file loaded after six seconds (typically called internally by xajax from get/printJavascript).

• $sJsURI (string): the relative address of the folder where xajax has been installed. For instance, if your PHP file is "http://www.myserver.com/myfolder/mypage.php" and xajax was installed in "http://www.myserver.com/anotherfolder", then $sJsURI should be set to "../anotherfolder". Defaults to assuming xajax is in the same folder as your PHP file.
• $sJsFile (string): the relative folder/file pair of the xajax Javascript engine located within the xajax installation folder. Defaults to xajax_js/xajax.js.
• Return: string

[edit] autoCompressJavascript (string $sJsFullFilename=NULL)

This method can be used to create a new xajax.js file out of the xajax_uncompressed.js file (which will only happen if xajax.js doesn't already exist on the filesystem).

• $sJsFullFilename (string): an optional argument containing the full server file path of xajax.js.

[edit] Object Methods (protected)

[edit] _detectURI ()

Returns the current URL based upon the SERVER vars.

• Access: private
• Return: string

[edit] _isObjectCallback (string $sFunction)

Returns true if the function name is associated with an object callback, false if not.

• $sFunction (string): the name of the function
• Access: private
• Return: boolean

[edit] _isFunctionCallable (string $sFunction)

Returns true if the function or object callback can be called, false if not.

• $sFunction (string): the name of the function
• Access: private
• Return: boolean

[edit] _callFunction (string $sFunction, array $aArgs)

Calls the function, class method, or object method with the supplied arguments.

• $sFunction (string): the name of the function
• $aArgs (array): arguments to pass to the function
• Access: private
• Return: mixed the output of the called function or method

[edit] _wrap (string $sFunction, mixed $sRequestType=XAJAX_POST)

Generates the Javascript wrapper for the specified PHP function.

• $sFunction (string): the name of the function
• $sRequestType (mixed): the request type
• Access: private
• Return: string

[edit] _xmlToArray (string $rootTag, string $sXml)

Takes a string containing xajax xjxobj XML or xjxquery XML and builds an array representation of it to pass as an argument to the PHP function being called.

• $rootTag (string): the root tag of the XML
• $sXml (string): XML to convert
• Access: private
• Return: array

[edit] _parseObjXml (string $rootTag)

A recursive function that generates an array from the contents of $this->aObjArray.

• $rootTag (string): the root tag of the XML
• Access: private
• Return: array

[edit] _decodeUTF8Data (string $sData)

Decodes string data from UTF-8 to the current xajax encoding.

• $sData (string): data to convert
• Access: private
• Return: string converted data

[edit] Functions

[edit] xajaxErrorHandler ($errno, $errstr, $errfile, $errline)

This function is registered with PHP's set_error_handler() function if the xajax error handling system is turned on.