Namespace $sf.lib.dom

$sf.lib.dom Defines helper functions / objects for common browser web-page / DOM interactions

Method Summary

Method Attributes	Method Name and Description
<static>	$sf.lib.dom.append(parNode, child) Append and HTMLElement to another HTMLElement
<static>	$sf.lib.dom.attach(el, name, cb) Attach an event handler to an HTMLElement.
<static>	$sf.lib.dom.attr(el, attrName, attrVal) Retrieve/Set/Delete an element's attribute.
<static>	$sf.lib.dom.bounds(el, details, check_3D) Calculate the surrounding boundaries of an HTMLElement, and whether or not the HTMLElement is "in-view" of the user
<static>	$sf.lib.dom.contains(element, needle) Returns whether or not an HTMLElement is contained within another HTMLElement
<static>	$sf.lib.dom.css(el, val) Set/Get the CSS text of an HTML element
<static>	$sf.lib.dom.currentStyle(el, attr) Returns the current value of a style attribute, or the current style object in its entirety depending on whether an attribute parameter is specified
<static>	$sf.lib.dom.detach(el, namethe, cb) Detach an event handler to an HTMLElement
<static>	$sf.lib.dom.doc(el) Retrieve a document for a given HTML Element
<static>	$sf.lib.dom.docRect(el) Returns an object that represents a rectangle with the geometric information of an HTMLDocument (includes scroll width / height)
<static>	$sf.lib.dom.elt(id, par) Retrieve an element by its ID.
<static>	$sf.lib.dom.evtCncl(evt) Cancel the the default action of a particular DOM event
<static>	$sf.lib.dom.evtTgt(evt) Return the target/srcElement of an event from an HTML element
<static>	$sf.lib.dom.make(tagName, parent) Make a new element
<static>	$sf.lib.dom.overlaps(el, limit) Find any HTMLElements that are covering a given HTMLElement.
<static>	$sf.lib.dom.par(el) Retrive the parent element of an HTML element
<static>	$sf.lib.dom.purge(node) A wrapper method for removing elements from a document rather than calling parentNode.removeChild raw.
<static>	$sf.lib.dom.ready() Returns whether or not the DOM is ready to be manipulated
<static>	$sf.lib.dom.tagName(el) A wrapper around retrieving the tagName of an HTML element (normalizes values to lower case strings).
<static>	$sf.lib.dom.tags(name, parNode) A wrapper around retrieving a list of tags by name.
<static>	$sf.lib.dom.view(el) Retrieve the host window object for a given HTML Element/document.
<static>	$sf.lib.dom.wait(cb) Fire off a particular function when it is detected that the DOM is ready Useful when you don't know for sure if the DOM of the browser is ready or not, so this will detect and fire your function for you.
<static>	$sf.lib.dom.winRect(el) Returns an object that represents a rectangle with the geometric information of an HTMLWindow (does not include scroll width / height)

Method Detail

<static> $sf.lib.dom.append(parNode, child)

Append and HTMLElement to another HTMLElement

Parameters:

{HTMLElement} parNode

the HTML element to manipulate

{HTMLElement} child

(Required) the new HTML element to add to the parent return {HTMLElement|Boolean} the new reference to the child element that was appended, or FALSE if failure
<static> $sf.lib.dom.attach(el, name, cb)

Attach an event handler to an HTMLElement. Note normalize event names to lower case / w3c standards. See example.
```
var el = $sf.lib.dom.elt("my_element");
function handle_click(evt)
{
     alert('i was clicked');
}

$sf.lib.dom.attach(el,"click",handle_click);
```
Parameters:

{HTMLElement} el

the HTML element to attach an event handler too

{String} name

the name of the event to listen too

{Function} cb

the function used to handle the particular event
<static> {String} $sf.lib.dom.attr(el, attrName, attrVal)

Retrieve/Set/Delete an element's attribute. Note that this handle's slight differences in the way HTML attributes are handled across browsers as well as being shorthand

Parameters:

{HTMLElement} el

the HTML element to manipulate

{String} attrName

the attribute to set/get

{String} attrVal Optional

, if specified will set the value of the attribute for this element. Passing null will remove the attribute completely

Returns:

{String} the value of the attribute normalized to a string (may be empty)
<static> {Object} $sf.lib.dom.bounds(el, details, check_3D)

Calculate the surrounding boundaries of an HTMLElement, and whether or not the HTMLElement is "in-view" of the user
Defined in: <C:\DEV\Projects\Yahoo\IAB-SafeFrames\trunk\src\js\pub\pub.js>.

Parameters:

{HTMLElement} el

The element for which to calculate information

{Object} details Optional

An object reference used as an output parameter in which further details about the boundaries of the element are specified

{Boolean} check_3D Optional

Check the element within 3 dimensional space such that any elements covering said element are also take into consideration

Returns:

{Object} info An object containing information about the element boundaries
<static> {Boolean} $sf.lib.dom.contains(element, needle)

Returns whether or not an HTMLElement is contained within another HTMLElement
Defined in: <C:\DEV\Projects\Yahoo\IAB-SafeFrames\trunk\src\js\pub\pub.js>.

Parameters:

{HTMLElement} element

The HTMLElement reference to search within

{HTMLElement} needle

The HTMLElement for which you want to check if its contained by the 1st parameter

Returns:

{Boolean}
<static> {String} $sf.lib.dom.css(el, val)

Set/Get the CSS text of an HTML element

Parameters:

{HTMLElement} el

the HTML element to manipulate

{String} val Optional

the CSS string to set if specified (e.g. "background-color:transparent;position:absolute;top:0px;left:0px").

Returns:

{String} the value of the attribute normalized to a string (may be empty)
<static> {HTMLStyleObject, String} $sf.lib.dom.currentStyle(el, attr)

Returns the current value of a style attribute, or the current style object in its entirety depending on whether an attribute parameter is specified
Defined in: <C:\DEV\Projects\Yahoo\IAB-SafeFrames\trunk\src\js\pub\pub.js>.

Parameters:

{HTMLElement} el

The HTMLElement for which to retrieve style information

{String} attr Optional

The style attribute (in JavaScript notation, e.g. 'backgroundColor' rather than 'background-color') to fetch.

Returns:

{HTMLStyleObject} An HTMLStyleObject containing all current style attribute values

{String} The value of an style attribute (only if attr parameter is specified).
<static> $sf.lib.dom.detach(el, namethe, cb)

Detach an event handler to an HTMLElement

Parameters:

{HTMLElement} el

the HTML element to attach an event handler too

{String} namethe

name of the event to listen too

{Function} cb

the function used to handle the particular event
<static> {Document|null} $sf.lib.dom.doc(el)

Retrieve a document for a given HTML Element

Parameters:

{HTMLElement} el

the HTML element for which you wish to find it's parent document

Returns:

{Document|null} null if nothing found
<static> {Object} $sf.lib.dom.docRect(el)

Returns an object that represents a rectangle with the geometric information of an HTMLDocument (includes scroll width / height)
Defined in: <C:\DEV\Projects\Yahoo\IAB-SafeFrames\trunk\src\js\pub\pub.js>.

Parameters:

{HTMLElement} el Optional

An HTMLElement to use as the reference for an HTMLDocument

Returns:

{Object}
<static> {HTMLElement|null} $sf.lib.dom.elt(id, par)

Retrieve an element by its ID. . basically a short hand wrapper around document.getElementById.

Parameters:

{String} id

(Required) the id of the HTML element to find

{HTMLElement|HTMLWindow|HTMLDocument} par Optional

The parent element,document,window to look for the given element

Returns:

{HTMLElement|null} null if nothing found
<static> $sf.lib.dom.evtCncl(evt)

Cancel the the default action of a particular DOM event

Parameters:

{HTMLEvent} evt

The raw HTML event
<static> $sf.lib.dom.evtTgt(evt)

Return the target/srcElement of an event from an HTML element

Parameters:

{HTMLEvent} evt

The raw HTML event
<static> {HTMLElement} $sf.lib.dom.make(tagName, parent)

Make a new element

Parameters:

{String} tagName

{Document|HTMLElement|Window} parent Optional

element, document, or window to make the tag in, optional.

Returns:

{HTMLElement}
<static> {Array} $sf.lib.dom.overlaps(el, limit)

Find any HTMLElements that are covering a given HTMLElement.
Defined in: <C:\DEV\Projects\Yahoo\IAB-SafeFrames\trunk\src\js\pub\pub.js>.

Parameters:

{HTMLElement} el

The HTMLElement for which to find any other elements that may be covering it.

{Number} limit Optional

The maximum number of covering elements to return

Returns:

{Array} An array of elements that are covering the given element
<static> $sf.lib.dom.par(el)

Retrive the parent element of an HTML element

Parameters:

{HTMLElement} el

the HTML element to check return {HTMLElement} the new reference to the parent element or null
<static> {Boolean} $sf.lib.dom.purge(node)

A wrapper method for removing elements from a document rather than calling parentNode.removeChild raw. Has special processing to ensure that contents of IFRAME tags gets released from memory as well

Parameters:

{HTMLElement} node

The HTML element to be removed from the dom

Returns:

{Boolean} Whether or not the element was successfully removed
<static> {Boolean} $sf.lib.dom.ready()

Returns whether or not the DOM is ready to be manipulated

Returns:

{Boolean}
<static> {String} $sf.lib.dom.tagName(el)

A wrapper around retrieving the tagName of an HTML element (normalizes values to lower case strings).

Parameters:

{HTMLElement} el

The HTML element for which to get the tag name.

Returns:

{String} The tag name in all lower case of an HTML element, if it cannot be successfully retrieved, alwasys returns an empty string (which will evaluate to FALSE).
<static> {HTMLElementCollection} $sf.lib.dom.tags(name, parNode)

A wrapper around retrieving a list of tags by name.

Parameters:

{String} name

The name of the tags that you wish to look for, note that you can pass in "*" to find all.

{HTMLElement|Document} parNode Optional

the parent node that you wish to look in

Returns:

{HTMLElementCollection} List of tags found. Note that is NOT a real JavaScript Array
<static> {Document|null} $sf.lib.dom.view(el)

Retrieve the host window object for a given HTML Element/document. Note that this is NOT the same as $sf.lib.dom.iframes.view, which returns the window reference INSIDE the IFRAME element.

Parameters:

{HTMLElement|HTMLDocument} el

the HTML element/document for which you wish to find it's parent window

Returns:

{Document|null} null if nothing found
<static> $sf.lib.dom.wait(cb)

Fire off a particular function when it is detected that the DOM is ready Useful when you don't know for sure if the DOM of the browser is ready or not, so this will detect and fire your function for you.

Parameters:

{Function} cb

A function reference to be called when the DOM is ready
<static> {Object} $sf.lib.dom.winRect(el)

Returns an object that represents a rectangle with the geometric information of an HTMLWindow (does not include scroll width / height)
Defined in: <C:\DEV\Projects\Yahoo\IAB-SafeFrames\trunk\src\js\pub\pub.js>.

Parameters:

{HTMLElement} el Optional

An HTMLElement to use as the references for an HTMLWindow

Returns:

{Object}

Classes

Method Summary

Method Detail