/***************************************************************************************************************************************************************
                                                                        ILLUSIONATOR.JS

Copyright © 2006 Illusionator, Inc.

Common JavaScript code shared by all of our web pages.

***************************************************************************************************************************************************************/


// IlsGetObj(sId)
//		sId:	The "id" attribute of the object to be retrieved.
//	returns:	The named object.  If object is not found, returns null.
//
// Returns the HTML element object whose "id" attribute is "sId".  Uses a browser-independent technique to obtain the object.

function IlsGetObj(sId)
{
	var obj;

	// Return the style object for that table, using object detection to provide browser-independent access
	if (document.getElementById) {
		obj = document.getElementById(sId);
	} else if (document.all) {
		obj = document.all[sId];
	} else if (document.layers) {
	   	obj = document.layers[sId];
	} else {
		obj = null;
	}

	if (!obj) {
		// It is a bit difficult to track bugs where a null is returned by this function and then the calling program attempts to use the null value later, and it is
		// probably never the case that the calling program expects to receive "null" from this function, so report an error
		alert('ERROR in IlsGetObj: There is no HTML element with id "' + sId + '"');
	}

	return obj;
} // IlsGetObj


// IlsGetStyle(sId)
//		sId:	The "id" attribute of the object whose style object is to be retrieved.
//	returns:	The style object.  If object is not found, returns null.
//
// Returns the CSS style object for the HTML element whose "id" attribute is "sId".  Uses a browser-independent technique to obtain the object.

function IlsGetStyle(sId)
{
	var obj = IlsGetObj(sId)
	if (!obj) {
		// If no HTML element object with that id was found, IlsGetObj() already reports an error, so just return null here
		return null;
	}
	var objStyle = obj.style;
	if (!objStyle) {
		// For some reason, the HTML element with "id" exists, but it has no style property.  In theory, this probably shouldn't happen, but we test for it just in
		// case.  It is a bit difficult to track bugs where a null is returned by this function and then the calling program attempts to use the null value later,
		// and it is probably never the case that the calling program expects to receive "null" from this function, so report an error.
		alert('ERROR in IlsGetStyle: There is no style property for the HTML element whose id is "' + sId + '"');
		return null;
	}

	// Return the style object for this HTML element
	return objStyle;
} // IlsGetStyle


// IlsPreloadError()
//	returns:	Nothing.
//
// Error handler that is invoked when an error occurs when IlsPreloadImage() tries to preload an image.  If this handler is invoked, we assume that the image file does not exist, and we
// report a suitable error with alert().

function IlsPreloadError()
{
	alert('ERROR in IlsPreloadImage: "' + this.src + '" does not exist');
} // IlsPreloadError


// IlsPreloadImage(sPath)
//		sPath:	File path of the image to be preloaded, relative to the directory location of this source file
//	returns:	Image object that was created.  Is often not useful to the calling program, but is returned just in case.
//
// Preloads the image at file path "sPath" into memory.  Any later display of the image at that image path will be very fast, even if it is not referenced using the returned Image
// object.  Note that this function keeps references to all preloaded images persistently, so that they will not be garbage collected.  We do this because we have found that if an Image
// object is created only long enough to set its "src" property, and the Image is then immediately discarded, the image does not actually get preloaded.

function IlsPreloadImage(sPath)
{
	var img = new Image();

	// We store the images persistently in an array "arrImages[]" stored as a property of the function object itself, rather than in a separate global array, to keep
	// this function self-contained and easily reusable.  If this is the first time this function has been called, create the array.
	if (!IlsPreloadImage.arrImages) {
		IlsPreloadImage.arrImages = new Array();
	}

	// Set an error handler so that we can detect whether the image file is missing
	img.onerror = IlsPreloadError;

	// The act of setting the "src" property of the Image object to the file path of the image starts the process of preloading the image.  If the image does not exist, IlsPreloadError()
	// will be automatically invoked.
	img.src = sPath;

	// Append this image to the end of our persistent array, so that it will continue to preload while the rest of the program continues
	IlsPreloadImage.arrImages.push(img);
	
	// Return the created Image object
	return img;
} // IlsPreloadImage


// IlsPreloadImageDupes(sPath)
//		sPath:	File path of the image to be preloaded, relative to the directory location of this source file
//	returns:	Image object that was created.  Is often not useful to the calling program, but is returned just in case.
//
// The same as IlsPreloadImage(), except that it checks to see if "sPath" is already preloaded, and if so, does not load it again.

function IlsPreloadImageDupes(sPath)
{
	// If persistent array of preloaded image objects has not yet been created, create it
	if (!IlsPreloadImageDupes.arrPreloaded) {
		IlsPreloadImageDupes.arrPreloaded = new Array();
	}
	
	// If persistent array of preloaded image objects already has an image object for this image path, return that object
	var objImage = IlsPreloadImageDupes.arrPreloaded[sPath];
	if (objImage) {
		return objImage;
	}
	
	// Preload the image, save its object in the persistent array of image objects, and return the object
	return (IlsPreloadImageDupes.arrPreloaded[sPath] = IlsPreloadImage(sPath));
} // IlsPreloadImageDupes


// IlsNumberFormatCurrency(n)
//		n:		The number that is to be formatted.
//	returns:	String containing the formatted currency..
//
// Returns the string value of the number "n," formatted as U.S. currency:
//		If the number is negative, starts with a minus sign ("-").
//		Then comes a dollar sign ("$").
//		Then, the whole dollar amount, comma-separated as needed.  If the dollar portion is zero, a single zero digit ("0") is used.
//		Then the decimal point (".").
//		Then the two-digit cents, rounded to the nearest penny.

function IlsNumberFormatCurrency(n) {

	// Compute the sign string, which is "-" if the number is negative, or the empty string otherwise
	var sSign = ((n < 0) ? "-" : "");

	// Convert "n" to be positive, if needed, and multiply it by 100 to move the cents to the left of the decimal point.  Then round, so that we round to the nearest penny.
	n = Math.round(Math.abs(n) * 100);

	// The dollar amount portion is "n" divided by 100 (to move the cents back to the right of the decimal point), and then the cents chopped off.  Note that if the dollar amount is
	// zero, the toString() method will return a single zero digit ("0") for "sDollars", which is what we want.
	var sDollars = (Math.floor(n / 100)).toString();

	// Insert comma separators, as needed, to the dollar portion of the number
	for (i = (sDollars.length - 3); i > 0; i -= 3) {
		sDollars = sDollars.substring(0, i) + "," + sDollars.substring(i);
	}

	// The final value consists of the leading "-" (if the number is negative), followed by a dollar sign ("$"), followed by the dollar amount string, followed by a decimal point
	// ("."), followed by the two-digit cents.  The cents are currently the two digits to the LEFT of the decimal point in "n" (because "n" was still multipled by 100).  We obtain the
	// number of cents by taking "n" modulo 100.  To force the resulting cents to be two digits (for example, 3 cents should be "03" not "3"), we simply add 100 to force the number to
	// be three digits long, then take the substring consisting of the second and third characters.
	return (sSign + "$" + sDollars + "." + (((n % 100) + 100).toString()).substring(1));
} // IlsNumberFormatCurrency