SimileAjax/DOM

= SimileAjax.DOM =

Cross-browser syntactic sugar for dealing with the DOM.

Code: http://api.simile-widgets.org/ajax/2.2.1/scripts/dom.js

Migration Notes
This is jQuery's claim to fame.

Back to SimileAjax.

SimileAjax.DOM._cachedParent

 * Type: Element
 * Default: null
 * Description: Avoids creating new throwaway elements in the course of running createElementFromString

SimileAjax.DOM.registerEventWithObject

 * Arguments:
 * elmt: Element, The DOM element to add an event to
 * eventName: string, The event to listen for, without the 'on' prefix (e.g., 'onClick' becomes 'click')
 * obj: object, a hash with methods associated to attributes
 * handlerName: string, the name of the attribute in obj containing the method to call
 * Returns: Nothing
 * Description: Specialized form of attaching an event handler to an element, likely given a Listener.

SimileAjax.DOM.registerEvent

 * Arguments:
 * elmt: Element, The DOM element to register the event to
 * eventName: string, The name of the event without the 'on' prefix (e.g., 'onClick' becomes 'click')
 * handler: function, The function to call when the event occurs
 * Returns: Nothing
 * Description: Cross-browser method to add an event handler to an element

SimileAjax.DOM.getPageCoordinates

 * Arguments:
 * elmt: Element, a DOM element
 * Returns: object, a hash with numeric attributes left and top
 * Description: Return where in the absolute grid pixels an element sits on the page

SimileAjax.DOM.getSize

 * Arguments:
 * elmt: Element, a DOM element
 * Returns: object, a hash with numeric attributes w and h
 * Description: Return the style computed width and height of an object (this would seem to be buggy on inspection as browser's computed width and height may not match up - IE's box model is wrong, etc.)

SimileAjax.DOM.getStyle

 * Arguments:
 * elmt: Element, a DOM element
 * styleProp: string, a CSS property name
 * Returns: string
 * Description: The value of the computed CSS property on the element (note that even numeric attributes are strings, numbers with units).

SimileAjax.DOM.getRelativeEventCoordinates

 * Arguments:
 * evt: Event, a browser event
 * elmt: Element, a DOM element
 * Returns: object, a hash with numeric attributes x and y
 * Description: Compute the offset from the element's top left corner of where the event occurred

SimileAjax.DOM.getEventPageCoordinates

 * Arguments:
 * evt: Event, a browser event
 * Returns: object, a hash with numeric attributes x and y
 * Description: Returns the absolute grid coordinates of where an event occurred

SimileAjax.DOM.hittest

 * Arguments:
 * x: int, the X-axis position on the page
 * y: int, the Y-axis position on the page
 * except: array, a list of Elements to ignore
 * Returns: Element
 * Description: Returns the deepest element at the coordinates provided, not counting the ones in the except list

SimileAjax.DOM.cancelEvent

 * Arguments:
 * evt: Event, a browser event
 * Returns: Nothing
 * Description: Stop the event from bubbling and prevent its default if possible

SimileAjax.DOM.appendClassName

 * Arguments:
 * elmt: Element, a DOM element
 * className: string, a DOM class name
 * Returns: Nothing
 * Description: Add another class to an element's existing DOM class attribute

SimileAjax.DOM.createInputElement

 * Arguments:
 * type: string, a valid HTML input element type
 * Returns: Element, the new DOM element
 * Description: Create an  element

SimileAjax.DOM.createDOMFromTemplate

 * Arguments:
 * template: object, a hash conforming to a implicitly specified way to describe a DOM tree using Javascript data structure conventions
 * Returns: Element, the described DOM tree
 * Description: Specifics are elided for the time being. This is used frequently, examples of the object format should be readily available in Exhibit code.

SimileAjax.DOM.createElementFromString

 * Arguments:
 * s: string, the string representation of an HTML fragment
 * Returns: Element, the DOM element constructed from the input
 * Description: Turn a string fragment of HTML into a DOM element; uses _cachedParent

SimileAjax.DOM.createDOMFromString

 * Arguments:
 * root: string or Element, the root element
 * s: string, the string representation of an HTML fragment
 * fieldElmts: object, a mapping of IDs to Elements
 * Returns: object, with an attribute elmt of type Element
 * Description: Creates a DOM element from a string and a hash of Elements that are used to replace any IDs in the string with corresponding hash key.

SimileAjax.DOM._hittest
Implements hittest.

SimileAjax.DOM._createDOMFromTemplate
Implements createDOMFromTemplate.

SimileAjax.DOM._processDOMConstructedFromString
Performs the processing described in createDOMFromString.

SimileAjax.DOM._processDOMChildrenConstructedFromString
Assist in performing the processing described in createDOMFromString.

Back to SimileAjax.