Echo Web Framework

The Core.Web library provides an API of cross-platform DOM manipulation tools. These are provided due to the fact that Internet Explorer, even in version 7, elects to use proprietary APIs in lieu of supporting W3C standards. The idea behind the Core.Web.DOM module is to limit the developer's exposure to these issues by providing functions that will perform tasks using either the W3C or proprietary API automatically.

Cross-Platform Event Handling

Internet Explorer does not support the DOM Level 2 event model. This browser requires that the developer register event listeners on DOM Element objects using attachEvent() and detachEvent() methods rather than the W3C specification's addEventListener() and removeEventListener() methods.

Core.Web.DOM provides its own addEventListener() and removeEventListener() methods for cross-platform event listener registration. These methods take following parameters:

• eventSource: the source of the event, i.e., the DOM Element.
• eventType: the event type, as a String, e.g., "click" for click events. Note that the "on" prefix is not used.
• eventListener: the listener to invoke, a Function. If you would like to invoke a method of an object, Core.method() may be used.
• useCapture: a boolean flag indicating whether the listener should be notified during the capturing or bubbling phase of event processing. On Internet Explorer this property is ignored, as capturing event listeners are not supported. It is thus recommended that you refrain from setting this value to true. Core.Web's EventProcessor object can be used to provide support for event capturing on all browsers.

When an event occurs, the specified eventListener will be invoked by the browser. In the case of browsers that support the W3C event model, the event will be provided as a parameter. In the case of IE, it is only available by accessing the global window.event property. It is thus recommended that your event listeners use something similar to the following to obtain the event before processing it:

function eventHandler(e) {
    // Cross-platform method to obtain event object:
    e = e ? e : window.event;
    // Process event:
    :
    :
}

Event Utility Methods

Core.Web.DOM provides a number of cross-platform utility methods for working with events. This functionality is again provided to compensate for Internet Explorer not following the DOM events specification.

The following utility methods are provided:

• getEventTarget(): Determines the target of the event. On DOM2 browsers, this method returns the target property of an event. On Internet Explorer, it returns the srcElement property.
• getEventRelatedTarget: Returns the relateed target of an event. On DOM2 browsers, this method returns the relatedTarget property. On Internet Explorer, it returns the toElement property.
• preventEventDefault(): Prevents the default action of an event from occurring. The default action will vary based on an event. For example, an ENTER keypress event in a textfield might have a 'default' action of submitting its containing HTML form. Passing such an event to preventEventDefault() will prevent such a default action from occurring. This method will invoke preventEventDefault() on the event on DOM2 compliant browsers, and set the returnValue of the event to false on Internet Explorer
• stopEventPropagation(): Stops the event from propagating to listeners on higher level elements. This method will invoke stopPropagation() on the event on DOM2 browsers and set the cancelBubble property to true on Internet Explorer.

Document Creation

Core.Web.DOM provides a createDocument() method to create a new DOM instance. This method will either invoke document.implementation.createDocument() (on DOM2 browsers) or create a new Microsoft.XMLDOM ActiveX object (on Internet Explorer). This method is typically used to create a new DOM that will be sent to a server using an XMLHTTPRequest.

createDocument() takes two paramters, the first is the namespace URI for the root element, and the second is the qualified name of the root element. The root element will exist in the returned document.

Focus

The DOM object provides a focusElement() method which accurately focuses a DOM element, avoiding various browser quirks.

General Utility Methods

The DOM API provides several utility methods for DOM manipulation, including:

• isAncestorOf(): determines if one DOM node is an ancestor of another.
• removeAllChildren(): removes all child nodes from a specific node.
• removeNode(): removes one node from another, employing tactics to avoid quirks in certain browsers that occur when removing large hierarchies from the DOM.