/**
 * Title: Document Extensions
 * Date Created: 2005/12/27
 * Description: Extensions to the document object.
 * Dependencies: events.js
 * Amendment History:
 * Copyright (c) 2004
 * Company: Azeus Systems Philippines Inc.
 * @author Daniw
 */

/**
 * Cross-browser way of retrieving an element by ID.
 * @param anId - the element's ID
 * @return the element, if it exists; otherwise undefined
 */
document.get = function(anId) {
  var result = undefined;

  if (document.getElementById) {
    result = document.getElementById(anId);

    // workaround for stupid IE bug that causes getElementById to retrieve the
    // element with same name instead of id
    if (result && result.id != anId && document.all) {
      var elements = document.all[anId];
      if (elements && elements.length) {
        for (var i = 0; i < elements.length; i++) {
          if (elements[i].id == anId)
            result = elements[i];
        }
      } else {
        result = elements;
      }
    }
  } else if (document.layers) {
    result = document.layers[anId]; // for NS4
  } else if (document.all) {
    result = document.all[anId]; //IE4
  }

  return result;
}

/**
 * Sets an element's event handler using the traditional event handling interface. It is more recommended to use
 * addEvent() and removeEvent() over this method since you may accidentally overwrite an existing event.
 */
document.setEvent = function(aName, anEventType, aFunctionReference) {
  document.setProperty(aName, "on" + anEventType, aFunctionReference);
}

/**
 * Sets an element's property, only if the element exists.
 * Example usage: document.setProperty("PERSON_NAME", "partner", partnerElement);
 *
 * @param anId - the element's ID
 * @param aPropertyName - the name of the element's property to be set, e.g. element.partner
 * @param aPropertyValue - the value of the property; this can be a function reference or any kind of data
 */
document.setProperty = function(anId, aPropertyName, aPropertyValue) {
  var element = document.get(anId);
  if (element && aPropertyName && aPropertyValue) {
    element[aPropertyName] = aPropertyValue;
  }
}

/**
 * Gets an element's property, or null if the element or the property does not exist.
 * @param anId - the element's ID
 * @param aPropertyName - the name of the element's property to be set, e.g. element.partner
 * @return the value of the property, if found; otherwise, returns undefined
 */ 
document.getProperty = function(anId, aPropertyName) {
  var element = document.get(anId);
  if (element && aPropertyName) {
    return element[aPropertyName];
  } else {
    return undefined;
  }
}

/**
 * Attaches an event to an element in the document, only if the element exists.
 * Example usage: document.addEvent("PERSON_NAME", "blur", trim);
 *
 * @param aName - the element's ID
 * @param anEventType - the event type to be used, excluding the "on"; for example, "click", or "mouseover"
 * @param aFunctionReference - the reference to the function, not the function's result
 */
document.addEvent = function(aName, anEventType, aFunctionReference) {
  var element = document.get(aName);
  events.addEvent(element, anEventType, aFunctionReference);
}

/**
 * Removes an event from an element in the document, only if the element exists.
 * Example usage: document.removeEvent("PERSON_NAME", "change", trim);
 *
 * @param aName - the element's ID
 * @param anEventType - the event type to be used, excluding the "on"; for example, "click", or "mouseover"
 * @param aFunctionReference - the reference to the function, not the function's result
 */
document.removeEvent = function(aName, anEventType, aFunctionReference) {  
  var element = document.get(aName);
  events.removeEvent(element, anEventType, aFunctionReference);
}

/**
 * Shorthands for document.get(aId).
 */
get = document.get;
$ = document.get;