// ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
//
// api_Forms.js
//
// These are CLIENTSIDE JavaScript functions that help us validate forms and other common form
// functions.
//
// sections : 
//   SECTION I   = Validation Functions
//   SECTION II  = Selection List Functions
//   SECTION III = Miscellaneous Functions
//
// created  : 02.14.00
// updated  : 02.14.00
//
// notes    : 2/14/00 JMB - Today i started the commenting standard...
//
//
// ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++






//
//
// SECTION I 
//
//
// //////////////////////////////////////////////////////////////////////////////////////////////
//
// Validation Functions
//
// These functions validate forms or form fields...
//
//
//
// //////////////////////////////////////////////////////////////////////////////////////////////


// FUNCTION *************************************************************************************
//
// ValidateAllTextFields
//
// This function validates all fields that require values, except Hidden fields and
// whatever names of fields specified in the comma-delimited string passed as exceptFields
// The function, if all fields are validated, can possibly pass on to doOtherFunction which
// is the functin name of another function to call after you validate the form...
//
// * NOTE : to be able to use this function with passing exceptFields, the user must be using
//          a browser that can handle JavaScript 1.2..... ex: NS4+ and IE4+
//
// input  : form [object], alertMessage [string], exceptFields [comma delimited string],
//          doOtherFunction [function name]
//
// output : true/false [boolean]
//
// **********************************************************************************************
function ValidateAllTextFields(form, alertMessage, exceptFields, doOtherFunction)
{
 // --> initialize variables...
 //
 exceptFieldArray = new Array();
 notValid         = false;
 if(exceptFields != "" && esceptFields)
 {
  exceptFieldArray = exceptFields.split(',');
 }

 // --> go through each form element and array element..
 //
 for(elementPosition = 0; elementPosition < form.length; elementPosition++){
  for(arrayPosition = 0; arrayPosition < exceptFieldArray.length; arrayPosition++)
  {
    if(form.elements[elementPosition].name.indexOf(exceptFieldArray[arrayPosition]) != -1)
    {
     notValid = true;
     break;
    }
    else{ notValid=false; }
  }    
  
  if(form.elements[elementPosition].type != 'hidden' && 
     form.elements[elementPosition].value == "" && !notValid)
  {
    alert(alertMessage);
    form.elements[elementPosition].focus();
    return false;
  }
 }

 if(doOtherFunction)
 {
  return doOtherFunction(form);
 }
 else{ return true; }

}





//
//
// SECTION II
//
//
// //////////////////////////////////////////////////////////////////////////////////////////////
//
// Selection List Functions
//
// These functions manipulate selection list(s)...
//
//
//
// //////////////////////////////////////////////////////////////////////////////////////////////


// FUNCTION *************************************************************************************
//
// MoveItems
//
// This function moves an item from one (muli)selection list to another list...
//
// input  : fromList [selection list object], toList [selection list object]
//
// output : none
//
// **********************************************************************************************
function MoveItems(fromList, toList)
{
 for(fromPosition = 0; fromPosition < fromList.options.length; fromPosition++)
 {
  if(fromList.options[fromPosition].selected == 1)
  {
   AddItem(fromList.options[fromPosition].text,fromList.options[fromPosition].value,toList);
  }
 } 

 RemoveListItems(fromList);
}



// FUNCTION *************************************************************************************
//
// CopyItems
//
// This function copies an item from one (muli)selection list to another list...
//
// input  : fromList [selection list object], toList [selection list object]
//
// output : none
//
// **********************************************************************************************
function CopyItems(fromList, toList)
{
 for(fromPosition = 0; fromPosition < fromList.options.length; fromPosition++)
 {
  if(fromList.options[fromPosition].selected == 1)
  {
   AddItem(fromList.options[fromPosition].text,fromList.options[fromPosition].value,toList);
   fromList.options[fromPosition].selected = 0;
  }
 } 
}



// FUNCTION *************************************************************************************
//
// AddItem
//
// This function adds an item from one (multi)selection list to another...
//
// input  : itemText [string], itemValue [string/number], toList [selection list object]
//
// output : none
//
// **********************************************************************************************
function AddItem(itemText,itemValue,toList,selected)
{
 addIt = true;

 for(toPosition=0; toPosition < toList.options.length; toPosition++)
 {
  // --> here we check to see if value already in list, if it is, you don't add it...
  //
  if(toList.options[toPosition].value == itemValue)
  { 
    addIt = false; 
    break;
  }
 }

 if(addIt)
 {
   toPosition = toList.options.length;
   toList.options.length++; 
   toList.options[toPosition]       = new Option();
   toList.options[toPosition].text  = itemText;
   toList.options[toPosition].value = itemValue;
   if(selected) toList.options[toPosition].selected = true;
 }
}

function remove_item(list,idx)   // remove item number idx from list
{ 
  for(i=idx;i<list.options.length-1;i++)
  {
    list.options[i].value=list.options[i+1].value;
    list.options[i].text =list.options[i+1].text;
  }
  list.options.length--;
}



// FUNCTION *************************************************************************************
//
// RemvoeListItems
//
// This function removes an item from a selection list...
//
// input  : list [selection list object]
//
// output : none
//
// **********************************************************************************************
function RemoveListItems(list)
{
 listValue   = new Array(); 
 listText    = new Array(); 
 newPosition = -1;

 for(listPosition = 0; listPosition < list.options.length; listPosition++)
 {
  if(list.options[listPosition].selected == 0)
  {
    newPosition++;
    listValue[newPosition] = list.options[listPosition].value;
    listText[newPosition]  = list.options[listPosition].text;
  }
 }

 list.options.length = 0;
 for(listPosition = 0; listPosition <= newPosition; listPosition++)
 {
  list.options.length++; 
  list.options[listPosition]       = new Option();
  list.options[listPosition].text  = listText[listPosition];
  list.options[listPosition].value = listValue[listPosition];
 }
}



// FUNCTION *************************************************************************************
//
// RemvoeAll
//
// This function removes all items from a selection list...
//
// input  : list [selection list object]
//
// output : none
//
// **********************************************************************************************
function RemoveAll(list)
{
 list.options.length = 0;
}



// FUNCTION *************************************************************************************
//
// SelectAll
//
// This function selects all items in a selection list...
//
// input  : list [selection list object]
//
// output : none
//
// **********************************************************************************************
function SelectAll(list)
{ 
 list.multiple = true;
 for(listPosition = 0; listPosition < list.options.length; listPosition++)
 {
   list.options[listPosition].selected = 1;
 }
}



// FUNCTION *************************************************************************************
//
// SelectItem
//
// This function selects an item in a selection list...
//
// input  : list [selection list object]
//
// output : none
//
// **********************************************************************************************
function SelectItem(list,item)
{ 
 for(listPosition = 0; listPosition < list.options.length; listPosition++)
 { 
   if(list.options[listPosition].value == item)
   {
    list.options[listPosition].selected = 1;
   }
   else
   {
    list.options[listPosition].selected = 0;
   }
 }
}





//
//
// SECTION III
//
//
// //////////////////////////////////////////////////////////////////////////////////////////////
//
// Miscellaneous functions
//
// These functions do miscellaneous things...
//
//
//
// //////////////////////////////////////////////////////////////////////////////////////////////


// FUNCTION *************************************************************************************
//
// ClearAllTextFields
//
// This function clears all text, and textarea fields in a form (does NOT clear HIDDEN fields)
//
// input  : form [object]
//
// output : none
//
// **********************************************************************************************
function ClearAllTextFields(form)
{
  for(elementPosition = 0; elementPostions < form.length; elementPosition++)
  {
    if(form.elements[elementPosition].type != 'hidden' && 
       (form.elements[elementPosition].type == 'text' || 
        form.elements[elementPosition].type == 'textarea'))
    {
      form.elements[elementPosition].value="";
    }
  }
}


// EOF;