//2010-04-30
//Written by Ran Zafrir
//
//
//
//This file, unlike "general.js" consists of functions that are application specific,
//but within the context of the application, they can be considered "generic".
//
//For example - a function that is dependent only on JQuery should go in this file ( and not in "general.js" ! )
/**
*
* Written by Ran Zafrir.
*
* Simplifies the use of AJAX
*
*
*
*
* @requires JQuery
*
* @author Ran Zafrir
*
*/
var AjaxHelpers =
{
/**
*
* Written by Ran Zafrir.
*
* This function sends data to the server via AJAX.
* What's unique about this function is that it takes care of any possible scenario including when network problems prevent the client from connecting to the server.
*
*
* This function receives a JSON-object that can contain any of these options:
*
*
* List of Options:
*
*
*
*
* - data
* - url
* - type
* - serverFunction
* - onValid
* - onExplicitlyInvalid
* - onImplicitlyInvalid
* - onError
* - onEmpty
* - onNonEmpty
* - onComplete
* - onNonErrorNonEmpty
* - retry
* - retryDelay
* - decodeFunction
* - validateResponse
* - validResponseIndicator
* - invalidResponseIndicator
*
*
Options Description:
*
*
*
*
* - data -
* Required.
* Data to be sent to the server.
*
*
*
* - url -
* Required.
* The URL of the request.
*
*
*
* - type -
* Optional.
* Request type ( "get" or "post" ).
* "post" by default.
*
*
*
* - serverFunction -
* Optional.
* This is useful if you concentrate all of your AJAX handling in 1 file.
* That way you can use this parameter to specify the server-function ( within that file ) to handle the request.
*
*
*
* - onValid -
* function(data, textStatus)
* Optional.
* A function to run upon a valid response from the server.
*
*
*
* - onExplicitlyInvalid -
* function(data, textStatus)
* Optional.
* A function to run if the server returns an explicitly invalid response.
*
*
*
* - onImplicitlyInvalid -
* function(data, textStatus)
* Optional.
* A function to run if the server returns an implicitly invalid response.
*
*
*
* - onError -
* function(XMLHttpRequest, textStatus, errorThrown)
* Optional.
* A function to be called if the request fails. The function is passed three arguments: The XMLHttpRequest object, a string describing the type of error that occurred and an optional exception object, if one occurred. Possible values for the second argument (besides null) are "timeout", "error", "notmodified" and "parsererror".
*
*
*
* - onEmpty -
* function(data, textStatus)
* Optional.
* A function to run if an empty response is received ( could be the result of failing to reach the server ).
* By default, this will be a function that waits 2 seconds and tries sending the request again.
*
*
*
* - onNonEmpty -
* function(data, textStatus)
* Optional.
* A function to run if a non-empty response is received
*
*
*
* - onComplete -
* function(XMLHttpRequest, textStatus)
* Optional.
* A function to be called when the request finishes (after success and error callbacks are executed). The function gets passed two arguments: The XMLHttpRequest object and a string describing the status of the request.
*
*
*
* - onNonErrorNonEmpty -
* function
* Optional.
* A function to be called when the response is not empty and not a server-error
*
*
*
* - retry -
* Boolean
* Optional.
* A boolean specifying whether to keep retrying when an empty response is received.
* TRUE by default.
*
*
*
* - retryDelay -
* Integer
* Optional.
* Specifies the number of milliseconds to wait between retry attempts.
* 2000 by default.
*
*
*
* - decodeFunction -
* function
* Optional.
* A function to pass the returned data through.
* For example - Base64.decode can go here.
*
*
*
* - validateResponse -
* boolean
* Optional.
* A boolean indicating whether the server's response should be passed through AjaxHelpers.validateResponse().
* onExplicitlyInvalid and onImplicitlyInvalid will be ignored if this is set to FALSE.
* TRUE by default.
*
*
*
* - validResponseIndicator -
* string
* Optional.
* A string the server should add to the beginning of the response in order to indicate "success".
* "1" by default.
*
*
*
* - invalidResponseIndicator -
* string
* Optional.
* A string the server should add to the beginning of the response in order to indicate "failure".
* "0" by default.
*
*
*
*
Written by Ran Zafrir.
*
* This function is very useful to distinguish between different scenarios such as:
*
*
*
*
* - Valid server response
* - Explicitly invalid server response
* - Implicitly invalid server response
* - No response ( Possible network problem )
*
*
This function receives a JSON-object that can contain any of these options:
*
* List of Options:
*
*
*
*
* - data
* - textStatus
* - onValid
* - onExplicitlyInvalid
* - onImplicitlyInvalid
* - onEmpty
* - onNonEmpty
* - decodeFunction
* - validResponseIndicator
* - invalidResponseIndicator
*
*
Options Description:
*
*
*
*
* - data -
* Required.
* Data received from the server.
*
*
*
* - textStatus -
* Required.
* String.
* textStatus as received by JQuery's functions.
*
*
*
* - onValid -
* function(data, textStatus)
* Optional.
* A function to run upon a valid response from the server.
*
*
*
* - onExplicitlyInvalid -
* function(data, textStatus)
* Optional.
* A function to run if the server returns an explicitly invalid response.
*
*
*
* - onImplicitlyInvalid -
* function(data, textStatus)
* Optional.
* A function to run if the server returns an implicitly invalid response.
*
*
*
* - onEmpty -
* function(data, textStatus)
* Optional.
* A function to run if an empty response is received ( could be the result of failing to reach the server ).
* By default, this will be a function that waits 2 seconds and tries sending the request again.
*
*
*
* - onNonEmpty -
* function(data, textStatus)
* Optional.
* A function to run if a non-empty response is received
*
*
*
* - decodeFunction -
* function
* Optional.
* A function to pass the returned data through.
* For example - Base64.decode() can go here.
*
*
*
* - validResponseIndicator -
* string
* Optional.
* A string the server should add to the beginning of the response in order to indicate "success".
* "1" by default.
*
*
*
* - invalidResponseIndicator -
* string
* Optional.
* A string the server should add to the beginning of the response in order to indicate "failure".
* "0" by default.
*
*
*
*
Written by Ran Zafrir.
*
* Like sendRequest, only that this function sends the contents of a "select" object.
* This function will first disable the "select" object so it can't be modified until the request is processed.
* Once a response is received from the server, the "select" will be returned to it's inital state ( enabled / disabled )
*
*
* This function receives a JSON-object that can contain any of these options:
*
*
* List of Options:
*
*
*
*
* - data
* - url
* - type
* - serverFunction
* - onValid
* - onExplicitlyInvalid
* - onImplicitlyInvalid
* - onError
* - onEmpty
* - onNonEmpty
* - onComplete
* - onNonErrorNonEmpty
* - retry
* - retryDelay
* - decodeFunction
* - validateResponse
* - validResponseIndicator
* - invalidResponseIndicator
*
*
Options Description:
*
*
*
*
* - data -
* Required.
* Data to be sent to the server.
*
*
*
* - url -
* Required.
* The URL of the request.
*
*
*
* - type -
* Optional.
* Request type ( "get" or "post" ).
* "post" by default.
*
*
*
* - serverFunction -
* Optional.
* This is useful if you concentrate all of your AJAX handling in 1 file.
* That way you can use this parameter to specify the server-function ( within that file ) to handle the request.
*
*
*
* - onValid -
* function(data, textStatus)
* Optional.
* A function to run upon a valid response from the server.
*
*
*
* - onExplicitlyInvalid -
* function(data, textStatus)
* Optional.
* A function to run if the server returns an explicitly invalid response.
*
*
*
* - onImplicitlyInvalid -
* function(data, textStatus)
* Optional.
* A function to run if the server returns an implicitly invalid response.
*
*
*
* - onError -
* function(XMLHttpRequest, textStatus, errorThrown)
* Optional.
* A function to be called if the request fails. The function is passed three arguments: The XMLHttpRequest object, a string describing the type of error that occurred and an optional exception object, if one occurred. Possible values for the second argument (besides null) are "timeout", "error", "notmodified" and "parsererror".
*
*
*
* - onEmpty -
* function(data, textStatus)
* Optional.
* A function to run if an empty response is received ( could be the result of failing to reach the server ).
* By default, this will be a function that waits 2 seconds and tries sending the request again.
*
*
*
* - onNonEmpty -
* function(data, textStatus)
* Optional.
* A function to run if a non-empty response is received
*
*
*
* - onComplete -
* function(XMLHttpRequest, textStatus)
* Optional.
* A function to be called when the request finishes (after success and error callbacks are executed). The function gets passed two arguments: The XMLHttpRequest object and a string describing the status of the request.
*
*
*
* - onNonErrorNonEmpty -
* function
* Optional.
* A function to be called when the response is not empty and not a server-error
*
*
*
* - retry -
* Boolean
* Optional.
* A boolean specifying whether to keep retrying when an empty response is received.
* TRUE by default.
*
*
*
* - retryDelay -
* Integer
* Optional.
* Specifies the number of milliseconds to wait between retry attempts.
* 2000 by default.
*
*
*
* - decodeFunction -
* function
* Optional.
* A function to pass the returned data through.
* For example - Base64.decode can go here.
*
*
*
* - validateResponse -
* boolean
* Optional.
* A boolean indicating whether the server's response should be passed through AjaxHelpers.validateResponse().
* onExplicitlyInvalid and onImplicitlyInvalid will be ignored if this is set to FALSE.
* TRUE by default.
*
*
*
* - validResponseIndicator -
* string
* Optional.
* A string the server should add to the beginning of the response in order to indicate "success".
* "1" by default.
*
*
*
* - invalidResponseIndicator -
* string
* Optional.
* A string the server should add to the beginning of the response in order to indicate "failure".
* "0" by default.
*
*
*
*
Written by Ran Zafrir.
*
* This function is being used internally.
* Validates a specified input-field and adds/removes a specified CSS-class ( typically "error" ) to/from that field.
*
*
* This function receives a JSON-object that can contain any of these options:
*
*
* List of Options:
*
*
*
*
* - input
* - validationFunction
* - errorClass
* - passToCallbacks
* - beforeSetError
* - beforeRemoveError
* - onError
* - onValid
*
*
Options Description:
*
*
*
*
* - input -
* Required.
* The input-field ( or a JQuery Selector pointing to an input-field ) to validate.
*
*
*
* - validationFunction -
* Required.
* A JavaScript function that accepts 1 string paramter and returns a boolean.
*
*
*
* - errorClass -
* Required.
* A CSS-class to use for showing that the specified input-field has errors.
*
*
*
* - passToCallbacks -
* Optional.
* A parameter to be passed to callbacks.
*
*
*
* - beforeSetError -
* function(input, validationFunction)
* Optional.
* A function to be called before setting the error-class
*
*
*
* - beforeRemoveError -
* function(input, validationFunction)
* Optional.
* A function to be called before removing the error-class.
*
*
*
* - onError -
* function(input, validationFunction)
* Optional.
* A function to be called if the specified input is invalid.
*
*
*
* - onValid -
* function(input, validationFunction)
* Optional.
* A function to be called if the specified input is valid.
*
*
*
*
Written by Ran Zafrir.
*
* Validates a specified input-field and adds/removes a specified CSS-class ( typically "error" ) to/from that field.
*
*
* This function receives a JSON-object that can contain any of these options:
*
*
* List of Options:
*
*
*
*
* - input
* - validationFunction
* - errorClass
* - passToCallbacks
* - beforeSetError
* - beforeRemoveError
* - onError
* - onValid
*
*
Options Description:
*
*
*
*
* - input -
* Required.
* The input-field ( or a JQuery Selector pointing to an input-field ) to validate.
*
*
*
* - validationFunction -
* Required.
* A JavaScript function that accepts 1 string paramter and returns a boolean.
*
*
*
* - errorClass -
* Optional.
* A CSS-class to use for showing that the specified input-field has errors.
* "error" by default.
*
*
*
* - passToCallbacks -
* Optional.
* A parameter to be passed to callbacks.
* validationFunction by default.
*
*
*
* - beforeSetError -
* function(input, validationFunction)
* Optional.
* A function to be called before setting the error-class
*
*
*
* - beforeRemoveError -
* function(input, validationFunction)
* Optional.
* A function to be called before removing the error-class.
*
*
*
* - onError -
* function(input, validationFunction)
* Optional.
* A function to be called if the specified input is invalid.
*
*
*
* - onValid -
* function(input, validationFunction)
* Optional.
* A function to be called if the specified input is valid.
*
*
*
*
Written by Ran Zafrir.
*
* Starts validating the specified input-field in real-time.
*
*
* This function receives a JSON-object that can contain any of these options:
*
*
* List of Options:
*
*
*
*
* - input
* - validationFunction
* - errorClass
* - passToCallbacks
* - beforeSetError
* - beforeRemoveError
* - onError
* - onValid
* - validateOnBlur
* - validateOnChange
* - validateOnKeyup
*
*
Options Description:
*
*
*
*
* - input -
* Required.
* The input-field ( or a JQuery Selector pointing to an input-field ) to validate.
*
*
*
* - validationFunction -
* Required.
* A JavaScript function that accepts 1 string paramter and returns a boolean.
*
*
*
* - errorClass -
* Optional.
* A CSS-class to use for showing that the specified input-field has errors.
* "error" by default.
*
*
*
* - passToCallbacks -
* Optional.
* A parameter to be passed to callbacks.
* validationFunction by default.
*
*
*
* - beforeSetError -
* function(input, validationFunction)
* Optional.
* A function to be called before setting the error-class
*
*
*
* - beforeRemoveError -
* function(input, validationFunction)
* Optional.
* A function to be called before removing the error-class.
*
*
*
* - onError -
* function(input, validationFunction)
* Optional.
* A function to be called if the specified input is invalid.
*
*
*
* - onValid -
* function(input, validationFunction)
* Optional.
* A function to be called if the specified input is valid.
*
*
*
* - validateOnBlur -
* Optional.
* True by default.
*
*
*
* - validateOnChange -
* Optional.
* True by default.
*
*
*
* - validateOnKeyup -
* Optional.
* True by default.
*
*
*
*
Written by Ran Zafrir.
*
* This can be used to validate an entire form via AJAX.
*
*
* This function receives a JSON-object that can contain any of these options:
*
*
* List of Options:
*
*
*
*
* - elements
* - errors
* - errorClass
* - beforeSetError
* - beforeRemoveError
* - onError
* - onValid
*
*
Options Description:
*
*
*
*
* - elements -
* Required.
* A JSON-array with this format:
*
* {
* serverIdentifier1: input1,
* serverIdentifier2: input2,
* serverIdentifier3: input3,
* .
* .
* .
* serverIdentifierN: inputN
* }
*
*
* "serverIdentifier" is a name ( string ) used by the server to identify the specified input-field.
* "input" is an input-field or a JQuery Selector pointing to an input-field.
*
*
* - errors -
* Required.
* A JSON-object with this format:
*
* {
* serverIdentifier1: error1,
* serverIdentifier2: error2,
* serverIdentifier3: error3
* .
* .
* .
* serverIdentifierN: errorN
* }
*
*
* "serverIdentifier" is a name ( string ) used by the server to identify the specified input-field.
* "error" is the text to display for the specified input-field.
*
*
* - errorClass -
* Optional.
* A CSS-class to use for showing that the specified input-field has errors.
* "error" by default.
*
*
*
* - beforeSetError -
* function(input, error)
* Optional.
* A function to be called before setting the error-class
*
*
*
* - beforeRemoveError -
* function(input, error)
* Optional.
* A function to be called before removing the error-class.
*
*
*
* - onError -
* function(input, error)
* Optional.
* A function to be called if the specified input is invalid.
*
*
*
* - onValid -
* function(input, error)
* Optional.
* A function to be called if the specified input is valid.
*
*
*
*
Written by Ran Zafrir.
*
* This is used for opening JQuery-dialogs ( possibly with several buttons like: "OK", "Cancel", etc'. ) on the fly with very little coding and ** WITHOUT ** creating any HTML !
*
*
*
*
* @requires JQuery
* @requires JQuery-UI
*
* @author Ran Zafrir
*
*/
var DialogFactory =
{
//Private Properties:
_dialogs: [],
_reservedDialogs: [],
/**
*
* Written by Ran Zafrir.
*
* Initializes a new dialog.
* This function was meant for internal use, but you can also use it externally.
* ( though I can't figure why you'll want to do that )
*
*
*
*
* @return A JSON object containing information about the created dialog.
* @type JSON Object
* @requires JQuery
* @requires JQuery-UI
*
* @author Ran Zafrir
*
*/
initNewDialog : function(reserve)
{
//NOTICE: This function is dependant on JQuery
if (typeof reserve == 'undefined') reserve = false;
//Create a div and then have JQuery make it into a dialog
var dialogDiv = document.createElement('div');
dialogDiv.style.display = 'none';
var messageObj = document.createElement('div');
dialogDiv.appendChild(messageObj);
document.body.appendChild(dialogDiv);
$(dialogDiv).dialog({
autoOpen: false,
closeOnEscape: true,
dialogClass: 'jqueryui',
modal: false,
stack: true,
resizable: false,//JQuery's default is TRUE
title: ''
//buttons:
//{
// 'OK': function()
// {
// $(this).dialog('close');
// }
//},
//beforeClose: function(event, ui)
//{
//},
//close: function(event, ui)
//{
//}
});
var dialog =
{
dialogDiv: dialogDiv,
messageObj: messageObj,
dialogDivClass: null
};
if (reserve)
{
this._reservedDialogs.push(dialog);
}
else
{
this._dialogs.push(dialog);
}
return dialog;
},
/**
*
* Written by Ran Zafrir.
*
*
* Creates a new DIV and initializes it into a JQuery-dialog ( or re-uses a JQuery-dialog already initialized by DialogFactory ).
*
*
* This function receives a JSON-object that can contain any of these options:
*
* List of Options:
*
*
*
*
Non-JQuery Options:
*
* - message
* - dialog
* - reserve
* - forceNew
* - dialogInnerClass
*
*
*
JQuery Options:
*
* - title
* - modal
* - buttons
* - beforeclose
* - close
* - width
* - height
* - dialogClass
* - disabled
* - closeOnEscape
* - stack
* - resizable
*
*
Options Description:
*
*
*
*
*
*
* @return A JSON object containing information about the dialog used.
* @type JSON Object
* @requires JQuery
* @requires JQuery-UI
*
* @author Ran Zafrir
*
*/
openDialog : function(settings)
{
//NOTICE: This function is dependant on JQuery
if (
typeof settings != 'object'
||
settings == null
)
{
throw 'Input must be a JavaScript object !';
}
if (
typeof settings.message == 'undefined'
&&
typeof settings.dialog == 'undefined'
)
{
throw 'Must set new-dialog\'s content or specify an existing dialog !';
}
var dialog = null;
if (
typeof settings.dialog == 'undefined'
||
settings.dialog == null
)
{
if (
typeof settings.forceNew == 'undefined'
||
!settings.forceNew
)
{
//Check if you can re-use an existing ( non-reserved ) dialog
for (var i = this._dialogs.length - 1; i >= 0; i--)
{
if ( !$(this._dialogs[i].dialogDiv).dialog('isOpen') )
//If found an existing dialog that's not currently open
{
//Use the existing dialog !
dialog = this._dialogs[i];
break;
}
}
if (dialog == null)
//If no available dialogs found --> Make a new one
{
dialog =
this.initNewDialog(
typeof settings.reserve != 'undefined'
&&
settings.reserve
);//Initialize a new dialog
}
}
else
{
dialog =
this.initNewDialog(
typeof settings.reserve != 'undefined'
&&
settings.reserve
);//Initialize a new dialog
}
}
else
{
dialog = settings.dialog;
}
if (typeof settings.message != 'undefined')
{
dialog.messageObj.innerHTML = settings.message;
}
var dialogOptions = {};
if (typeof settings.title != 'undefined')
{
dialogOptions.title = settings.title;
}
if (typeof settings.modal != 'undefined')
{
dialogOptions.modal = settings.modal;
}
if (
typeof settings.buttons == 'undefined'
||
settings.buttons == null
)
{
if (
typeof settings.dialog == 'undefined'
||
settings.dialog == null
)
{
//This is the default when not forced to use a specific dialog
dialogOptions.buttons =
{
'OK': function()
{
$(this).dialog('close');
}
};
}
}
else
{
dialogOptions.buttons = settings.buttons;
}
if (typeof settings.beforeclose == 'function')
{
dialogOptions.beforeclose = settings.beforeclose;
}
if (typeof settings.close == 'function')
{
dialogOptions.close = settings.close;
}
if (typeof settings.width != 'undefined')
{
dialogOptions.width = settings.width;
}
if (typeof settings.height != 'undefined')
{
dialogOptions.height = settings.height;
}
if (typeof settings.dialogClass == 'string')
{
dialogOptions.dialogClass = settings.dialogClass;
}
if (typeof settings.disabled != 'undefined')
{
dialogOptions.disabled = settings.disabled;
}
if (typeof settings.closeOnEscape != 'undefined')
{
dialogOptions.closeOnEscape = settings.closeOnEscape;
}
if (typeof settings.stack != 'undefined')
{
dialogOptions.stack = settings.stack;
}
if (typeof settings.resizable != 'undefined')
{
dialogOptions.resizable = settings.resizable;
}
$(dialog.dialogDiv).dialog(
'option',
dialogOptions
);
if (typeof settings.dialogInnerClass == 'string')
{
if (dialog.dialogDivClass != null)
{
$(dialog.dialogDiv).removeClass(dialog.dialogDivClass);
}
dialog.dialogDivClass = settings.dialogInnerClass;
$(dialog.dialogDiv).addClass(settings.dialogInnerClass);
}
else
{
if (dialog.dialogDivClass != null)
{
$(dialog.dialogDiv).removeClass(dialog.dialogDivClass);
dialog.dialogDivClass = null;
}
}
$(dialog.dialogDiv).dialog('open');
return dialog;
},
/**
*
* Written by Ran Zafrir.
*
* "Marks" the specified dialog as "Reserved" so that it won't be re-used when openDialog() is called.
*
*
*
*
* @return A JSON object containing information about the dialog used, or FALSE if the specified dialog was already reserved or wasn't found.
* @type JSON Object
*
* @author Ran Zafrir
*
*/
reserveDialog: function(dialog)
{
for (var i = this._dialogs.length - 1; i >= 0; i--)
{
if ( this._dialogs[i] == dialog )
{
this._dialogs.splice(i, 1)
this._reservedDialogs.push(dialog);
return dialog;
}
}
return false;
},
/**
*
* Written by Ran Zafrir.
*
* "Marks" the specified dialog as "Unreserved" making it available for re-use when calling openDialog().
*
*
*
*
* @return A JSON object containing information about the dialog used, or FALSE if the specified dialog was not reserved or not found
* @type JSON Object
*
* @author Ran Zafrir
*
*/
unreserveDialog: function(dialog)
{
for (var i = this._reservedDialogs.length - 1; i >= 0; i--)
{
if ( this._reservedDialogs[i] == dialog )
{
this._reservedDialogs.splice(i, 1)
this._dialogs.push(dialog);
return dialog;
}
}
return false;
},
/**
*
* Written by Ran Zafrir.
*
* Destroys all unreserved-dialogs and clears their DIVs.
*
*
*
*
* @return Void
* @requires JQuery
* @requires JQuery-UI
*
* @author Ran Zafrir
*
*/
clearUnreservedDialogs: function()
{
for (var i = this._dialogs.length - 1; i >= 0; i--)
{
$(this._dialogs[i].dialogDiv).dialog('destroy');
document.body.removeChild(this._dialogs[i].dialogDiv);
}
this._dialogs = [];
}
};