// CREATE AND FIRE A NEW REQUEST OBJECT. RETURNS A SUCCESS FLAG.
function FireXHR(requestMethod, url, responseHandler, requestBody)
{
    if (window.XMLHttpRequest)
        var xhr = new XMLHttpRequest();
    else if (window.ActiveXObject)
        var xhr = new ActiveXObject("Microsoft.XMLHTTP");
    else
    {
        alert("Your browser is not supported by this application.");
        return false;
    }
    xhr.open(requestMethod, url, true);
    xhr.setRequestHeader("Content-type", "application/json")
    xhr.onreadystatechange = function ()
    {
        if (xhr.readyState == 4)
        {
            if (xhr.status == 200)
            {
                try
                {
                    // MADE THE FAILURE MESSAGE LOOK LIKE THE EXCEPTION MESSAGE.
                    var responseObj = $.parseJSON(xhr.responseText);
                    if (responseObj != null)
                        responseHandler(responseObj);
                    else
                        alert("Empty JSON - empty, null, or undefined string.");
                }
                catch(err)
                {
                    // parseJSON() THROWS A FULLY-FORMED EXCEPTION STRING THAT INCLUDES THE RESPONSE BODY.
                    alert(err);
                }
            }
            else
                alert("Received HTTP error " + xhr.status + ".");
        }
    };
    xhr.send(requestBody);
    return true;
}

// ADD A NEW ROW TO THE TABLE.
function AddTableRowTop(templateRowID, newRowID)
{
    $(templateRowID).clone(true).attr('id', newRowID).show().insertAfter(templateRowID);
}
function AddTableRowBottom(templateRowID, newRowID)
{
    var clonedRow = $(templateRowID).clone(true).attr('id', newRowID).show();
    $(templateRowID).parent().append(clonedRow);
}

// POPULATE TABLE ROW FROM NAMED ARRAY.
function PopulateTableRowFromNamedArray(rowID, objArray)
{
    $(rowID + ' td').each(function()
    {
        // FOR REGULAR TABLE CELLS, IN CASE FIELD VALUE CONTAINS \n, REPLACE WITH <br/> AND SET VIA .html
        var thisClass = $(this).attr('class');
        if (objArray[thisClass] != undefined)
            $(this).html(  objArray[thisClass].replace(new RegExp("\\n", "g"), '<br/>')  );
    });
    $(rowID + ' a').each(function()
    {
        var thisClass = $(this).attr('class');
        if (objArray[thisClass] != undefined)
            $(this).text(objArray[thisClass]);
    });
    $(rowID + ' :submit').each(function()
    {
        var thisClass = $(this).attr('class');
        if (objArray[thisClass] != undefined)
            $(this).attr('value', objArray[thisClass]);
    });
    $(rowID + ' input:checkbox').each(function()
    {
        var thisClass = $(this).attr('class');
        if (objArray[thisClass] != undefined)
            $(this).attr('checked', ('0' != objArray[thisClass]));
    });
}

// POPULATE FORM DIV FROM NAMED ARRAY
function PopulateFormFromNamedArray(divID, objArray)
{
    $(divID + ' input:radio').each(function()
    {
        // TO AVOID MULTIPLE RADIO BUTTONS SELECTED.
        $(this).attr('checked', false);
    });
    for (field in objArray)
    {
        var fieldVal = '';
        try
        {
            // THE DB MAY NOT BE PROPERLY UTF-8, SO TRY DECODING JUST IN CASE.
            fieldVal = decodeURIComponent( escape(   objArray[field]  )  );
        }
        catch (err)
        {
            alert("Skipping UTF-8 conversion.");
            fieldVal = objArray[field];
        }
        $(divID + ' input:text.' + field).val(fieldVal);
        $(divID + ' textarea.' + field).val(fieldVal);
        $(divID + ' input:checkbox.' + field).attr('checked', ('0' != fieldVal));
        $(divID + ' input:radio.' + field + '[value="' + fieldVal + '"]').attr('checked', true);
    }
}

// CLEAR FORM DIV.
function ClearForm(divID)
{
    $(divID + ' input:text').val("");
    $(divID + ' textarea').val("");
    $(divID + ' option:selected').each(function()
    {
        $(this).removeAttr("selected");
    });
    $(divID + ' input:checkbox').each(function()
    {
        $(this).attr('checked', false);
    });
    $(divID + ' input:radio').each(function()
    {
        $(this).attr('checked', false);
    });
}

// CREATE JSON OBJECT FROM FORM FIELDS
function CreateJSONFromForm(divID)
{
    var requestObj = { };
    $(divID + ' input:text').each(function()
    {
        if ($(this).attr('class') != "")
            requestObj[ $(this).attr('class') ] = $(this).val();
    });
    $(divID + ' option:selected').each(function()
    {
        if ($(this).attr('class') != "")
            requestObj[ $(this).attr('class') ] = $(this).val();
    });
    $(divID + ' textarea').each(function()
    {
        if ($(this).attr('class') != "")
            requestObj[ $(this).attr('class') ] = $(this).val();
    });
    $(divID + ' input:checkbox').each(function()
    {
        if ($(this).attr('class') != "")
        {
            if ($(this).is(':checked'))
                requestObj[ $(this).attr('class') ] = '1';
            else
                requestObj[ $(this).attr('class') ] = '0';
        }
    });
    $(divID + ' input:radio').each(function()
    {
        if ($(this).attr('class') != "")
        {
            if ($(this).is(':checked'))
                requestObj[ $(this).attr('class') ] = $(this).val();
        }
    });
    return requestObj;
}

// DELETE OBJECT FROM NAMED ARRAY
function DeleteFromNamedArray(objArray, fieldName, fieldValue)
{
    for (var objIdx = 0; objIdx < objArray.length; objIdx++)
    {
        if (fieldValue == objArray[objIdx][fieldName])
        {
            objArray.splice(objIdx, 1);
            break;
        }
    }
}

// ADD OBJECT TO SORTED NAMED ARRAY
function AddToNamedArray(objArray, fieldName, fieldValue, newItem)
{
    var objectIdx = -1;
    for (var objIdx = 0; objIdx < objArray.length; objIdx++)
    {
        if (fieldValue.toLowerCase() < objArray[objIdx][fieldName].toLowerCase())
        {
            objectIdx = objIdx;
            objArray.splice(objIdx, 0, newItem);
            break;
        }
    }
    if (objectIdx == -1)
        objArray.push(newItem);
}