/**
 * Displays a form validation error message using a standardized.
 * format.
 *
 * @param	errorMessage	Optional.  An array of messages to be
 *							formatted and displayed.
 *
 * @return					Returns true after the message is
 *							displayed
 *
 * @author	Rob Wilkerson
 * @date	3/9/2005
 */
function se_showError ( errors )
{
	var i;
	var errorMessage = ( errors.length == 1 ) ? "Please correct the following error:\n\n" : "Please correct the following errors:\n\n";

	if ( errors.length > 0 ) {
		for ( i = 0; i < errors.length; i++ ) {
			/**
			 * format each error message to remove trailing punctuation
			 * and HTML tags in the message content.
			 */
			errorMessage += "> " + errors[i].replace ( /\.*\s*$/, "" ).replace ( /<[^>]*>/ig, "" ) + "\n";
		}

		alert ( errorMessage );
	}
	return true;
}

/**
 * Toggles the server-side error display element.
 *
 * @param	cErrors			Required.  The number of errors that
 *							were discovered.
 *
 * @author	Rob Wilkerson
 * @date	3/9/2005
 */
function se_toggleErrorDisplay ( cErrors )
{
	try {
		if ( cErrors > 0 ) {
			document.getElementById ( "error" ).style.display = "block";
		}
		else {
			document.getElementById ( "error" ).style.display = "none";
		}
	}
	catch ( e ) {
		/**
		 * For some reason the expected element (<tr id="error"> or
		 * <div id="error">) does
		 * not seem to exist.  Not much we can do about this so we'll
		 * just fail silently.
		 */
		 // alert ( e.description );
	}
}

/**
 * Sets the cursor in the first field of a given type on a form
 *
 * @param	form		Required.  The form object that will accept the focus
 * @param	fieldType	Optional.  The input type (e.g. text, button, etc.)
 */
function setFieldFocusByType ( form )
{
	try {
		var inputs = form.getElementsByTagName ( "input" );

		if ( arguments.length > 1 ) {

			/* BEGIN : set focus to a particular type of field */
			for ( i = 0; i < inputs.length; i++ ) {
				inp = inputs[i];

				if ( inp.type && ( inp.type.toLowerCase() == arguments[1].toLowerCase() ) ) {
					break;
				}
			}
			/* END : set focus to a particular type of field */

		}
		else {

			/* BEGIN : set focus to the first form field regardless of type */
			inp = inputs[0];
			/* END : set focus to the first form field regardless of type */

		}

		inp.focus();
	}
	catch (e)
	{
		// no worries, we just won't set any focus
	}
}

/**
 * Finds the first form on a page and set the focus to the first
 * field in that form that will accept focus.  If that field has
 * a value the value will be selected.
 *
 * @return		void
 *
 * @notes
 *
 * @author		Rob Wilkerson
 * @date		4/26/2005
 */
function setInitialFocus()
{
	try {
		var form = document.forms[0];

		for ( var i = 0; i < form.length; i++ ) {
			try {
				with ( form.elements[i] ) {
					/**
					 * We don't want to set the focus (or select) a readonly element, but select
					 * elements don't have that property so we have to check for them separately.
					 */
					if ( ( type.search ( /(text|password|checkbox|radio|file)/ ) >= 0 && !readOnly ) || type.search ( /select-/i ) >= 0 /**  && type.search ( /(button|submit|reset)/ ) < 0 */ ) {
						focus();

						try {
							if ( value.length && value.length > 0 ) {
								select();
							}
						}
						catch ( e ) {
							/**
							 * Some input types don't offer the select() method so
							 * we'll just fail silently and set the focus.
							 */
						}
						break;
					}
				}
			}
			catch ( e ) {
				/**
				 * This field probably just can't accept the focus.  Maybe
				 * it's disabled or hidden.  No worries.  We'll move on to
				 * the next field.
				 */

				 /** alert ( e.description ); */
			}
		}
	}
	catch ( e ) {
		/**
		 * No problem.  This is a usability function that is VERY general
		 * so that it can be used globally.  If we're here then there may
		 * not be a form on this page or it may not have any elements that
		 * can accept the focus.
		 */
	}
}
/**
 * Forces a character limit on a form field (including
 * textareas).
 *
 * @param	field		The field element
 * @param	limit		The maximum character limit
 *
 * @return				whether the next character will
 *						be added to the content
 * @usage
 *		onkeypress="return se_forceCharLimit ( this, 200 );
 *
 * @author	Rob Wilkerson
 * @date	3/22/2005
 */
function se_forceCharLimit ( field, limit )
{
	if ( field.value.length > limit ) {
		field.value = field.value.substring(0, limit);
		return false;
	}
	return true;
}

/**
 * Appends an option to a selectbox
 *
 * @param	field			the selectbox field object
 * @param	optionText		text to be displayed for the option
 * @param	optionValue		value to be passed for the option
 */
function addSelectOption ( field, optionText, optionValue )
{
	with ( field ) {
		options.length++;
		options[options.length - 1].text	= optionText;
		options[options.length - 1].value	= optionValue;

		if ( arguments.length > 3 && arguments[3] ) {
			options[options.length - 1].setAttribute('selected','selected');
		}

		return options[options.length - 1];
	}
}

/**
 * Sorts the options in a select or list box by text then by value.
 *
 * @param	field		The field whose options will be sorted
 */
function sortOptions ( field )
{
	var tmp			= new Array();
	var hash		= new Object();

	for ( var i = 0; i < field.options.length; i++ ) {
		tmp[i]			= field.options[i].text.toUpperCase() + '-' + i;
		hash[tmp[i]]	= field.options[i];
	}
	tmp.sort();

	for ( var i = 0; i < tmp.length; i++ ) {
		if ( i == field.options.length ) {
			field.options.length++;
		}
		field.replaceChild(hash[tmp[i]], field.options[i]);
	}
}

/**
 * Enables or disables one or more buttons on a form
 *
 * @param	disable		Boolean.  Whether the buttons passed should
 *						be disabled.  A false value will enable the
 *						buttons.
 * @param	buttons		Optional.  The function will iterate over any
 *						remaining arguments and try to set the disabled
 *						property
 */
function disableButtons ( disable )
{
	if ( arguments.length > 1 ) {
		for ( i = 1; i < arguments.length; i++ ) {
			try {
				arguments[i].disabled = disable;
			}
			catch ( e ) {
				/** ignore any errors */
				// alert ( "Error disabling buttons: " + e.description );
			}
		}
	}
}