copyright. inc.php
Examples
googleMap. inc.php
tableUpdater. inc.php
Tests
Xajax_core
Xajax_js
Xajax_controls
Index

xajax_core.js

This file contains the definition of the main xajax javascript core.

This is the client side code which runs on the web browser or similar web enabled application.  Include this in the HEAD of each page for which you wish to use xajax.

Summary
xajax_core.js
This file contains the definition of the main xajax javascript core.
xajax core javascript library
Please see copyright.inc.php for a detailed description, copyright and license information.
xajax. config
This class contains all the default configuration settings.
Functions
setDefault
This function will set a default configuration option if it is not already set.
Variables
waitCursor
statusMessages
baseDocument
The base document that will be used throughout the code for locating elements by ID.
requestURI
The URI that requests will be sent to.
defaultMode
The request mode.
defaultHttpVersion
The Hyper Text Transport Protocol version designated in the header of the request.
defaultContentType
The content type designated in the header of the request.
defaultResponseDelayTime
The delay time, in milliseconds, associated with the <xajax.callback.global.onRequestDelay> event.
defaultExpirationTime
The amount of time to wait, in milliseconds, before a request is considered expired.
defaultMethod
The method used to send requests to the server.
defaultRetry
The number of times a request should be retried if it expires.
defaultReturnValue
The value returned by xajax.call when in asynchronous mode, or when a syncrhonous call does not specify the return value.
maxObjectDepth
The maximum depth of recursion allowed when serializing objects to be sent to the server in a request.
maxObjectSize
The maximum number of members allowed when serializing objects to be sent to the server in a request.
xajax. config. status
Provides support for updating the browser’s status bar during the request process.
Functions
update
Constructs and returns a set of event handlers that will be called by the xajax framework to set the status bar messages.
dontUpdate
Constructs and returns a set of event handlers that will be called by the xajax framework where status bar updates would normally occur.
xajax. config. cursor
Provides the base functionality for updating the browser’s cursor during requests.
Functions
update
Constructs and returns a set of event handlers that will be called by the xajax framework to effect the status of the cursor during requests.
dontUpdate
Constructs and returns a set of event handlers that will be called by the xajax framework where cursor status changes would typically be made during the handling of requests.
xajax. tools
This contains utility functions which are used throughout the xajax core.
Functions
$
Shorthand for finding a uniquely named element within the document.
doubleQuotes
Replace all occurances of the single quote character with a double quote character.
singleQuotes
Replace all occurances of the double quote character with a single quote character.
_escape
Determine if the specified value contains special characters and create a CDATA section so the value can be safely transmitted.
_objectToXML
Convert a javascript object or array into XML suitable for transmission to the server.
_nodeToObject
Deserialize a javascript object from an XML node.
getRequestObject
Construct an XMLHttpRequest object dependent on the capabilities of the browser.
getBrowserHTML
Insert the specified string of HTML into the document, then extract it.
willChange
Tests to see if the specified data is the same as the current value of the element’s attribute.
getFormValues
Build an associative array of form elements and their values from the specified form.
_getFormValues
Used internally by xajax.tools.getFormValues to recursively get the value of form elements.
_getFormValue
Used internally by xajax.tools._getFormValues to extract a single form value.
stripOnPrefix
Detect, and if found, remove the prefix ‘on’ from the specified string.
addOnPrefix
Detect, and add if not found, the prefix ‘on’ from the specified string.
xajax. tools. queue
This contains the code and variables for building, populating and processing First In Last Out (FILO) buffers.
Functions
create
Construct and return a new queue object.
retry
Maintains a retry counter for the given object.
rewind
Rewind the buffer head pointer, effectively reinserting the last retrieved object into the buffer.
setWakeup
Set or reset a timeout that is used to restart processing of the queue.
process
While entries exist in the queue, pull and entry out and process it’s command.
push
Push a new object into the tail of the buffer maintained by the specified queue object.
pushFront
Push a new object into the head of the buffer maintained by the specified queue object.
pop
Attempt to pop an object off the head of the queue.
xajax. responseProcessor
Functions
xml
Parse the response XML into a series of commands.
xajax.js
Contains the functions for javascript file and function manipulation.
Functions
includeOnce
Add a reference to the specified script file if one does not already exist in the HEAD of the current document.
includeScript
Adds a SCRIPT tag referencing the specified file.
removeScript
Locates a SCRIPT tag in the HEAD of the document which references the specified file and removes it.
sleep
Causes the processing of items in the queue to be delayed for the specified amount of time.
confirmCommands
Prompt the user with the specified text, if the user responds by clicking cancel, then skip the specified number of commands in the response command queue.
execute
Execute the specified string of javascript code, using the current script context.
waitFor
Test for the specified condition, using the current script context; if the result is false, sleep for 1/10th of a second and try again.
call
Call a javascript function with a series of parameters using the current script context.
setFunction
Constructs the specified function using the specified javascript as the body of the function.
wrapFunction
Construct a javascript function which will call the original function with the same name, potentially executing code before and after the call to the original function.
makeWrapper
Helper function used in the wrapping of an existing javascript function.
xajax.dom
Functions
assign
Assign an element’s attribute to the specified value.
append
Append the specified value to an element’s attribute.
prepend
Prepend the specified value to an element’s attribute.
replace
Search and replace the specified text.
remove
Delete an element.
create
Create a new element and append it to the specified parent element.
insert
Insert a new element before the specified element.
insertAfter
Insert a new element after the specified element.
contextAssign
Assign a value to a named member of the current script context object.
contextAppend
Appends a value to a named member of the current script context object.
contextPrepend
Prepend a value to a named member of the current script context object.
xajax.css
Functions
add
Add a LINK reference to the specified .css file if it does not already exist in the HEAD of the current document.
remove
Locate and remove a LINK reference from the current document’s HEAD.
waitForCSS
Attempt to detect when all .css files have been loaded once they are referenced by a LINK tag in the HEAD of the current document.
xajax. forms
Functions
getInput
Create and return a form input element with the specified parameters.
createInput
Create a new input element under the specified parent.
insertInput
Insert a new input element before the specified element.
insertInputAfter
Insert a new input element after the specified element.
xajax. events
Functions
setEvent
Set an event handler.
addHandler
Add an event handler to the specified element.
removeHandler
Remove an event handler from an element.
xajax. callback
Functions
create
Create a blank callback object.
setupTimer
Create a timer to fire an event in the future.
clearTimer
Clear a callback timer for the specified function.
execute
Execute a callback event.
xajax. callback. global
The global callback object which is active for every request.
xajax
Variables
response
The response queue that holds response commands, once received from the server, until they are processed.
responseSuccessCodes
This array contains a list of codes which will be returned from the server upon successful completion of the server portion of the request.
responseErrorsForAlert
This array contains a list of status codes returned by the server to indicate that the request failed for some reason.
responseRedirectCodes
An array of status codes returned from the server to indicate a request for redirect to another URL.
commands
The array of command handlers that are currently available.
Functions
initializeRequest
Initialize a request object, populating default settings, where call specific settings are not already provided.
processParameters
Processes request specific parameters and generates the temporary variables needed by xajax to initiate and process the request.
prepareRequest
Prepares the XMLHttpRequest object for this xajax request.
request
call
Initiates a call to the server.
submitRequest
Create a request object and submit the request using the specified request type; all request parameters should be finalized by this point.
_internalSend
This function is used internally by xajax to initiate a request to the server.
abortRequest
Abort the request.
responseReceived
Process the response.
getResponseProcessor
This function attempts to determine, based on the content type of the reponse, what processor should be used for handling the response data.
parseAttributes
Take the parameters passed in the command of the XML response and convert them to parameters of the args object.
parseChildren
Parses the child nodes of the command of the response XML.
executeCommand
Perform a lookup on the command specified by the response command object passed in the first parameter.
completeResponse
Called by the response command queue processor when all commands have been processed.
$
Shortcut to xajax.tools.$.
getFormValues
Shortcut to xajax.tools.getFormValues.
Variables
isLoaded
xjx
Contains shortcut’s to frequently used functions.
Functions
$
Shortcut to xajax.tools.$.
getFormValues
Shortcut to xajax.tools.getFormValues.
call
Shortcut to xajax.call.

xajax core javascript library

Please see copyright.inc.php for a detailed description, copyright and license information.

xajax. config

This class contains all the default configuration settings.  These are application level settings; however, they can be overridden by including a xajax.config definition prior to including the xajax_core.js file, or by specifying the appropriate configuration options on a per call basis.

Summary
Functions
setDefault
This function will set a default configuration option if it is not already set.
Variables
waitCursor
statusMessages
baseDocument
The base document that will be used throughout the code for locating elements by ID.
requestURI
The URI that requests will be sent to.
defaultMode
The request mode.
defaultHttpVersion
The Hyper Text Transport Protocol version designated in the header of the request.
defaultContentType
The content type designated in the header of the request.
defaultResponseDelayTime
The delay time, in milliseconds, associated with the <xajax.callback.global.onRequestDelay> event.
defaultExpirationTime
The amount of time to wait, in milliseconds, before a request is considered expired.
defaultMethod
The method used to send requests to the server.
defaultRetry
The number of times a request should be retried if it expires.
defaultReturnValue
The value returned by xajax.call when in asynchronous mode, or when a syncrhonous call does not specify the return value.
maxObjectDepth
The maximum depth of recursion allowed when serializing objects to be sent to the server in a request.
maxObjectSize
The maximum number of members allowed when serializing objects to be sent to the server in a request.

Functions

setDefault

xajax.config.setDefault = function(option,
defaultValue)

This function will set a default configuration option if it is not already set.

option(string): The name of the option that will be set.
defaultValue(unknown): The value to use if a value was not already set.

Variables

waitCursor

xajax.config.setDefault('waitCursor',
false)
truexajax should display a wait cursor when making a request
falsexajax should not show a wait cursor during a request

statusMessages

xajax.config.setDefault('statusMessages',
false)
truexajax should update the status bar during a request
falsexajax should not display the status of the request

baseDocument

xajax.config.setDefault('baseDocument',
document)

The base document that will be used throughout the code for locating elements by ID.

requestURI

xajax.config.setDefault('requestURI',
xajax.config.baseDocument.URL)

The URI that requests will be sent to.

defaultMode

xajax.config.setDefault('defaultMode',
'asynchronous')

The request mode.

’asynchronous’The request will immediately return, the response will be processed when (and if) it is received.
’synchronous’The request will block, waiting for the response.  This option allows the server to return a value directly to the caller.

defaultHttpVersion

xajax.config.setDefault('defaultHttpVersion',
'HTTP/1.1')

The Hyper Text Transport Protocol version designated in the header of the request.

defaultContentType

xajax.config.setDefault('defaultContentType',
'application/x-www-form-urlencoded')

The content type designated in the header of the request.

defaultResponseDelayTime

xajax.config.setDefault('defaultResponseDelayTime',
1000)

The delay time, in milliseconds, associated with the <xajax.callback.global.onRequestDelay> event.

defaultExpirationTime

xajax.config.setDefault('defaultExpirationTime',
10000)

The amount of time to wait, in milliseconds, before a request is considered expired.  This is used to trigger the <xajax.callback.global.onExpiration event.

defaultMethod

xajax.config.setDefault('defaultMethod',
'POST')

The method used to send requests to the server.

’POST’Generate a form POST request
’GET’Generate a GET request; parameters are appended to the xajax.config.requestURI to form a URL.

defaultRetry

xajax.config.setDefault('defaultRetry',
5)

The number of times a request should be retried if it expires.

defaultReturnValue

xajax.config.setDefault('defaultReturnValue',
false)

The value returned by xajax.call when in asynchronous mode, or when a syncrhonous call does not specify the return value.

maxObjectDepth

xajax.config.setDefault('maxObjectDepth',
20)

The maximum depth of recursion allowed when serializing objects to be sent to the server in a request.

maxObjectSize

xajax.config.setDefault('maxObjectSize',
2000)

The maximum number of members allowed when serializing objects to be sent to the server in a request.

xajax. config. status

Provides support for updating the browser’s status bar during the request process.  By splitting the status bar functionality into an object, the xajax developer has the opportunity to customize the status bar messages prior to sending xajax requests.

Summary
Functions
update
Constructs and returns a set of event handlers that will be called by the xajax framework to set the status bar messages.
dontUpdate
Constructs and returns a set of event handlers that will be called by the xajax framework where status bar updates would normally occur.

Functions

update

update: function()

Constructs and returns a set of event handlers that will be called by the xajax framework to set the status bar messages.

dontUpdate

dontUpdate: function()

Constructs and returns a set of event handlers that will be called by the xajax framework where status bar updates would normally occur.

xajax. config. cursor

Provides the base functionality for updating the browser’s cursor during requests.  By splitting this functionalityh into an object of it’s own, xajax developers can now customize the functionality prior to submitting requests.

Summary
Functions
update
Constructs and returns a set of event handlers that will be called by the xajax framework to effect the status of the cursor during requests.
dontUpdate
Constructs and returns a set of event handlers that will be called by the xajax framework where cursor status changes would typically be made during the handling of requests.

Functions

update

update: function()

Constructs and returns a set of event handlers that will be called by the xajax framework to effect the status of the cursor during requests.

dontUpdate

dontUpdate: function()

Constructs and returns a set of event handlers that will be called by the xajax framework where cursor status changes would typically be made during the handling of requests.

xajax. tools

This contains utility functions which are used throughout the xajax core.

Summary
Functions
$
Shorthand for finding a uniquely named element within the document.
doubleQuotes
Replace all occurances of the single quote character with a double quote character.
singleQuotes
Replace all occurances of the double quote character with a single quote character.
_escape
Determine if the specified value contains special characters and create a CDATA section so the value can be safely transmitted.
_objectToXML
Convert a javascript object or array into XML suitable for transmission to the server.
_nodeToObject
Deserialize a javascript object from an XML node.
getRequestObject
Construct an XMLHttpRequest object dependent on the capabilities of the browser.
getBrowserHTML
Insert the specified string of HTML into the document, then extract it.
willChange
Tests to see if the specified data is the same as the current value of the element’s attribute.
getFormValues
Build an associative array of form elements and their values from the specified form.
_getFormValues
Used internally by xajax.tools.getFormValues to recursively get the value of form elements.
_getFormValue
Used internally by xajax.tools._getFormValues to extract a single form value.
stripOnPrefix
Detect, and if found, remove the prefix ‘on’ from the specified string.
addOnPrefix
Detect, and add if not found, the prefix ‘on’ from the specified string.

Functions

$

xajax.tools.$ = function(sId)

Shorthand for finding a uniquely named element within the document.

sId(string): The unique name of the element (specified by the ID attribute), not to be confused with the name attribute on form elements.

Returns

objectThe element found or null.

Note

This function uses the xajax.config.baseDocument which allows xajax to operate on the main window document as well as documents from contained iframes and child windows.

See also

xajax.$ and xjx.$

doubleQuotes

xajax.tools.doubleQuotes = function(haystack)

Replace all occurances of the single quote character with a double quote character.

haystackThe source string to be scanned.

Returns

stringA new string with the modifications applied.

singleQuotes

xajax.tools.singleQuotes = function(haystack)

Replace all occurances of the double quote character with a single quote character.

haystackThe source string to be scanned.

Returns

stringA new string with the modification applied.

_escape

xajax.tools._escape = function(data)

Determine if the specified value contains special characters and create a CDATA section so the value can be safely transmitted.

data(string or other): The source string value to be evaluated or an object of unknown type.

Returns

stringThe string value, escaped if necessary or the object provided if it is not a string.

Note

When the specified object is NOT a string, the value is returned as is.

_objectToXML

xajax.tools._objectToXML = function(obj,
guard)

Convert a javascript object or array into XML suitable for transmission to the server.

objThe object or array to convert.
guardAn object used to track the level of recursion when encoding javascript objects.  When an object contains a reference to it’s parent and the parent contains a reference to the child, an infinite recursion will cause some browsers to crash.

Returns

stringthe xml representation of the object or array.

See also

xajax.config.maxObjectDepth and xajax.config.maxObjectSize

_nodeToObject

xajax.tools._nodeToObject = function(node)

Deserialize a javascript object from an XML node.

nodeA node, likely from the xml returned by the server.

Returns

objectThe object extracted from the xml node.

getRequestObject

Construct an XMLHttpRequest object dependent on the capabilities of the browser.

Returns

objectJavascript XHR object.

getBrowserHTML

xajax.tools.getBrowserHTML = function(sValue)

Insert the specified string of HTML into the document, then extract it.  This gives the browser the ability to validate the code and to apply any transformations it deems appropriate.

sValue(string): A block of html code or text to be inserted into the browser’s document.

Returns

The (potentially modified) html code or text.

willChange

xajax.tools.willChange = function(element,
attribute,
newData)

Tests to see if the specified data is the same as the current value of the element’s attribute.

element(string or object): The element or it’s unique name (specified by the ID attribute)
attribute(string): The name of the attribute.
newData(string): The value to be compared with the current value of the specified element.

Returns

trueThe specified value differs from the current attribute value.
falseThe specified value is the same as the current value.

getFormValues

xajax.tools.getFormValues = function(parent)

Build an associative array of form elements and their values from the specified form.

element(string): The unique name (id) of the form to be processed.
disabled(boolean, optional): Include form elements which are currently disabled.
prefix(string, optional): A prefix used for selecting form elements.

Returns

An associative array of form element id and value.

_getFormValues

xajax.tools._getFormValues = function(aFormValues,
children,
submitDisabledElements,
prefix)

Used internally by xajax.tools.getFormValues to recursively get the value of form elements.  This function will extract all form element values regardless of the depth of the element within the form.

_getFormValue

xajax.tools._getFormValue = function(aFormValues,
child,
submitDisabledElements,
prefix)

Used internally by xajax.tools._getFormValues to extract a single form value.  This will detect the type of element (radio, checkbox, multi-select) and add it’s value(s) to the form values array.

stripOnPrefix

xajax.tools.stripOnPrefix = function(sEventName)

Detect, and if found, remove the prefix ‘on’ from the specified string.  This is used while working with event handlers.

sEventName(string): The string to be modified.

Returns

stringThe modified string.

addOnPrefix

xajax.tools.addOnPrefix = function(sEventName)

Detect, and add if not found, the prefix ‘on’ from the specified string.  This is used while working with event handlers.

sEventName(string): The string to be modified.

Returns

stringThe modified string.

xajax. tools. queue

This contains the code and variables for building, populating and processing First In Last Out (FILO) buffers.

Summary
Functions
create
Construct and return a new queue object.
retry
Maintains a retry counter for the given object.
rewind
Rewind the buffer head pointer, effectively reinserting the last retrieved object into the buffer.
setWakeup
Set or reset a timeout that is used to restart processing of the queue.
process
While entries exist in the queue, pull and entry out and process it’s command.
push
Push a new object into the tail of the buffer maintained by the specified queue object.
pushFront
Push a new object into the head of the buffer maintained by the specified queue object.
pop
Attempt to pop an object off the head of the queue.

Functions

create

xajax.tools.queue.create = function(size)

Construct and return a new queue object.

size(integer): The number of entries the queue will be able to hold.

retry

xajax.tools.queue.retry = function(obj,
count)

Maintains a retry counter for the given object.

obj(object): The object to track the retry count for.
count(integer): The number of times the operation should be attempted before a failure is indicated.

Returns

trueThe object has not exhausted all the retries.
falseThe object has exhausted the retry count specified.

rewind

xajax.tools.queue.rewind = function(theQ)

Rewind the buffer head pointer, effectively reinserting the last retrieved object into the buffer.

theQ(object): The queue to be rewound.

setWakeup

xajax.tools.queue.setWakeup = function(theQ,
when)

Set or reset a timeout that is used to restart processing of the queue.  This allows the queue to asynchronously wait for an event to occur (giving the browser time to process pending events, like loading files)

theQ(object): The queue to process upon timeout.
when(integer): The number of milliseconds to wait before starting/ restarting the processing of the queue.

process

xajax.tools.queue.process = function(theQ)

While entries exist in the queue, pull and entry out and process it’s command.  When a command returns false, the processing is halted.

theQ(object): The queue object to process.  This should have been crated by calling xajax.tools.queue.create.

Returns

trueThe queue was fully processed and is now empty.
falseThe queue processing was halted before the queue was fully processed.

Notes

  • Use xajax.tools.queue.setWakeup or call this function to cause the queue processing to continue.
  • This will clear the associated timeout, this function is not designed to be reentrant.
  • When an exception is caught, do nothing; if the debug module is installed, it will catch the exception and handle it.

push

xajax.tools.queue.push = function(theQ,
obj)

Push a new object into the tail of the buffer maintained by the specified queue object.

theQ(object): The queue in which you would like the object stored.
obj(object): The object you would like stored in the queue.

pushFront

xajax.tools.queue.pushFront = function(theQ,
obj)

Push a new object into the head of the buffer maintained by the specified queue object.  This effectively pushes an object to the front of the queue... it will be processed first.

theQ(object): The queue in which you would like the object stored.
obj(object): The object you would like stored in the queue.

pop

xajax.tools.queue.pop = function(theQ)

Attempt to pop an object off the head of the queue.

theQ(object): The queue object you would like to modify.

Returns

objectThe object that was at the head of the queue or null if the queue was empty.

xajax. responseProcessor

Summary
Functions
xml
Parse the response XML into a series of commands.

Functions

xml

xajax.responseProcessor.xml = function(oRequest)

Parse the response XML into a series of commands.  The commands are constructed by calling xajax.parseAttributes and xajax.parseChildren.

oRequest(object): The request context object.

xajax.js

Contains the functions for javascript file and function manipulation.

Summary
Functions
includeOnce
Add a reference to the specified script file if one does not already exist in the HEAD of the current document.
includeScript
Adds a SCRIPT tag referencing the specified file.
removeScript
Locates a SCRIPT tag in the HEAD of the document which references the specified file and removes it.
sleep
Causes the processing of items in the queue to be delayed for the specified amount of time.
confirmCommands
Prompt the user with the specified text, if the user responds by clicking cancel, then skip the specified number of commands in the response command queue.
execute
Execute the specified string of javascript code, using the current script context.
waitFor
Test for the specified condition, using the current script context; if the result is false, sleep for 1/10th of a second and try again.
call
Call a javascript function with a series of parameters using the current script context.
setFunction
Constructs the specified function using the specified javascript as the body of the function.