Home | Class Index

SDK Version: 3.11.4-302512

Documentation generated on 24 July 2015

Class
caplin.dom

Utility

This class provides static, browser agnostic, utility methods for DOM interactions such as adding / removing event listeners, adjusting CSS classes, finding element positions etc.

Constructor Summary

Attributes Name and Description
caplin.dom.Utility()

Method Summary

Attributes Name and Description
<static> void addAndRemoveClassNames(Element element, String classesToAdd, String classesToRemove)

Adds and/or removes the specified class names from the specified element.
<static> void addClassName(Element element, String className)

Adds the specified class name to the list of CSS classes on the given element, if the class does not already exist.
<static> Number addEventListener(Object targetElem, String eventName, Function eventListener, boolean directAttachedEvent, bUseCapture)

Registers the specified event function to a particular event using the provided DOM element.
<static> void addScrollListener(Function scrollListener)

Registers a global listener for mouse scroll events.
<static> Function createMethodEventListener(Object obj, String method, Array staticArguments)

Creates an event listener (a function pointer) that allows a method to be called on an object when that event is fired.
<static> void discard()

Discards one or more elements (all arguments passed will be discarded) by removing children, and removing it from any parentNode.
<static> DOMElement getAncestorElementWithClass(Element element, String className)

Returns the first element that contains the given class as part of its className string.
<static> String getComputedStyle(DOMElement element, String styleName)

Computes current style of a DOM Element, converting it to pixels where appropriate.
<static> Object getElementOffsetValues(Object element)

Returns the bounding rectangle of the specified element.
<static> Object getElementPosition(DOMElement element)

Returns the absolute position of the element relative to the window in pixels.
<static> Array getElementsByClassName(DOMElement domElement, String tagName, String className)

Returns an array of DOM elements that match the specified tag name and class name.
<static> DOMElement getLastChildWithClassName(DOMElement parentElement, String className)

Returns the last child element that contains the specified CSS class.
<static> Array getMousePosition(Event event)

Returns the mouse position for the specified event.
<static> Number getNodeIndex(Element element)

Returns the node index of the element as it exists in the parent.
<static> String getScrollBarWidth()

Returns the computed current width of scrollBar.
<static> Object getScrollOffset(Element element)

Returns the scrolled offset of the element (if any) in an object containing a left and top properties.
<static> Boolean hasClassName(Element element, String className)

Returns true if the specified class name exists on the element.
<static> void insertAfter(Element element, Element referenceElement)

Inserts the specified node immediately after the reference element.
<static> Boolean isElementAncestorOfElement(Element possibleAncestor, Element possibleChildElement)

Checks to see if the specified ancestor element contains the specified child element.
<static> Boolean isMouseLeaveOrEnter(Event event, Element element)

Determines whether the event is the equivalent of the microsoft mouseleave or mouseenter events.
<static> Boolean preventEventDefault(Event event)

Allows the user to prevent the default event, with the use return Utility.preventEventDefault(event);.
<static> void removeChild(Element childElement)

Removes the specified child from its parent.
<static> void removeClassName(Element element, String className)

Removes the CSS class name from the specified element.
<static> void removeEventListener(Element targetElem, String eventName, Function eventListener)

Removes the specified event listener function from the element.
<static> void removeEventListenerById(Number uniqueListenerId)

Removes the DOM event listener that has previously been added via the caplin.dom.Utility#addEventListener method.
<static> void replaceClassName(Element element, String currentClass, String newClass)

Replaces the specified CSS class name on the DOM element with another class.
<static> void setInnerHtml(Element element, String html)

Sets the innerHTML of the specified element in an efficient way.
<static> void stopEventPropagation(Event event)

Stops the propagation of an event.

Constructor Detail

► caplin.dom.Utility()

Method Detail

► <static> void addAndRemoveClassNames(Element element, String classesToAdd, String classesToRemove)

Adds and/or removes the specified class names from the specified element. This operation is performed in a single DOM action, making this more efficient than adding/removing the classes individually. If a class exists in both the add and remove lists, the class will be added to the element.

Parameters
Element element The HTML DOM element to make the class changes to.
String classesToAdd The list of class names that will be added to the list of existing classes.
String classesToRemove The list of class names that will be removed from the list of existing classes.

► <static> void addClassName(Element element, String className)

Adds the specified class name to the list of CSS classes on the given element, if the class does not already exist.

Parameters
Element element The HTML DOM element to add the CSS class to.
String className The class name that will be added to the list of existing classes.

► <static> Number addEventListener(Object targetElem, String eventName, Function eventListener, boolean directAttachedEvent, bUseCapture)

Registers the specified event function to a particular event using the provided DOM element.

Parameters
Object targetElem The document element the event will be registered against.
String eventName The name of the event that will be registered (e.g. 'click', but not 'onclick').
Function eventListener The function that will be called when the event fires.
boolean directAttachedEvent Whether the simpler form of event registration (e.g. elem.onclick) should be used (false by default). This is still occasionally useful in IE when you want access to the target element and that is different to window.event.srcElement.
bUseCapture
Returns
{Number} An event listener id to be used in the method (@link #removeEventListenerById) to remove the newly added event listener or NULL if the event listener could not be added for any reason.
See
#getEventHandlerFromMethod

► <static> void addScrollListener(Function scrollListener)

Registers a global listener for mouse scroll events.

This method is used rather than #addEventListener since the registration of mouse scroll events differs in IE, Opera, and standards compliant browsers. Furthermore, the event parameter passed through as the first parameter to scrollListener can be relied upon to exist, even in IE, and has been pre-normalized using the caplin.dom.event.Event#getNormalizedEvent method, since the format of the scroll detail differs so widely.

Parameters
Function scrollListener

► <static> Function createMethodEventListener(Object obj, String method, Array staticArguments)

Creates an event listener (a function pointer) that allows a method to be called on an object when that event is fired.

Normal event listeners are function pointers which make object-oriented programming difficult. The function pointer returned by this method merely calls the desired method on the specified object so that the this pointer is still available.

Each time an event occurs where this event listener has been attached, the method will be called with a single event parameter, event, which is the browser event object. Optionally, if staticArguments is provided then the arguments within this array will be appended to the method parameters for each method call.

The last object passed into the callback method method will be the DOM element which triggered the event firing, for example, the button that was clicked or hovered over.

Parameters
Object obj the object the method will be called on.
String method the name of the method to call.
Array staticArguments Optional The arguments that, if provided, will be appended as parameters to the given method.
Returns
{Function} The event function that will invoke the method on the specified class once the event is fired.

► <static> void discard()

Discards one or more elements (all arguments passed will be discarded) by removing children, and removing it from any parentNode.

► <static> DOMElement getAncestorElementWithClass(Element element, String className)

Returns the first element that contains the given class as part of its className string.

Parameters
Element element the element to start the search at.
String className the class name to look for.
Returns
{DOMElement} The ancestor element with the specified class, or null.

► <static> String getComputedStyle(DOMElement element, String styleName)

Computes current style of a DOM Element, converting it to pixels where appropriate.

Parameters
DOMElement element Element to get style for.
String styleName Css style name. IE. border-width.
Returns
{String} value with unit, to get the value only use parseInt.

► <static> Object getElementOffsetValues(Object element)

Returns the bounding rectangle of the specified element.

Parameters
Object element The element to get the bounding recangle for.
Returns
{Object} {left:x,right:y}

► <static> Object getElementPosition(DOMElement element)

Returns the absolute position of the element relative to the window in pixels. The position also takes into account any scrolling of parents.

Parameters
DOMElement element The DOM element to calculate the position of
Returns
{Object} {left:x,top:y}

► <static> Array getElementsByClassName(DOMElement domElement, String tagName, String className)

Returns an array of DOM elements that match the specified tag name and class name.

Parameters
DOMElement domElement The DOM element that should be used as the root of the search.
String tagName The tag name (can be *) of elements to search for.
String className The CSS class name of the elements to search for.
Returns
{Array} An array of DOMElement elements that match the specified criteria.

► <static> DOMElement getLastChildWithClassName(DOMElement parentElement, String className)

Returns the last child element that contains the specified CSS class.

Parameters
DOMElement parentElement The parent to use as the root.
String className The class of the wanted last child element.
Returns
{DOMElement} The last child element or null.

► <static> Array getMousePosition(Event event)

Returns the mouse position for the specified event.

Parameters
Event event The event object for which to get the mouse co-ordinates
Returns
{Array} [x,y]

► <static> Number getNodeIndex(Element element)

Returns the node index of the element as it exists in the parent.

Parameters
Element element The element to get the index for.
Throws
caplin.core.Error
If the specified element does not have a parent.
Returns
{Number} The node index

► <static> String getScrollBarWidth()

Returns the computed current width of scrollBar.

Returns
{String} value with unit, to get the value only use parseInt.

► <static> Object getScrollOffset(Element element)

Returns the scrolled offset of the element (if any) in an object containing a left and top properties.

Parameters
Element element The DOM element to calculate the scrolled offset of.
Returns
{Object} {left:x,top:y}

► <static> Boolean hasClassName(Element element, String className)

Returns true if the specified class name exists on the element.

Parameters
Element element The DOMElement to check.
String className The class name to check.
Returns
{Boolean} returns true if the specified class name exists on the element.

► <static> void insertAfter(Element element, Element referenceElement)

Inserts the specified node immediately after the reference element.

This convenience method saves the programmer from having to determine whether to call insertBefore() or appendChild(), depending on whether the reference element is the last child node.

Parameters
Element element The element to insert.
Element referenceElement The reference element to insert the element after.

► <static> Boolean isElementAncestorOfElement(Element possibleAncestor, Element possibleChildElement)

Checks to see if the specified ancestor element contains the specified child element.

Parameters
Element possibleAncestor The element that is presumed to be a parent node.
Element possibleChildElement The element to start the search at.
Returns
{Boolean} Returns true if the specified ancestor element contains the child element.

► <static> Boolean isMouseLeaveOrEnter(Event event, Element element)

Determines whether the event is the equivalent of the microsoft mouseleave or mouseenter events. This method assumes the event being passed is a mouseout or mouseenter and has undefined results if this isn't the case.

Parameters
Event event A mouseover or mouseout event object.
Element element The element we want to test against for mouseenter/mouseleave.
Returns
{Boolean} True if the event is either a mouse leave or enter event.

► <static> Boolean preventEventDefault(Event event)

Allows the user to prevent the default event, with the use return Utility.preventEventDefault(event);.

Parameters
Event event Event passed to your event handler. Note that event handlers are not wrapped so you need to do something like event = event || window.event;.
Returns
{Boolean} Always returns false

► <static> void removeChild(Element childElement)

Removes the specified child from its parent.

Parameters
Element childElement The child to remove.

► <static> void removeClassName(Element element, String className)

Removes the CSS class name from the specified element.

Parameters
Element element The HTML element that the class name should be removed from.
String className The CSS class to remove from the element.

► <static> void removeEventListener(Element targetElem, String eventName, Function eventListener)

Removes the specified event listener function from the element.

Parameters
Element targetElem The element to remove the event from.
String eventName The name of the event to remove the listener from.
Function eventListener The event listener to remove.
Deprecated
use removeEventListenerById instead
See
caplin.dom.Utility#removeEventListenerById to remove an event listener.

► <static> void removeEventListenerById(Number uniqueListenerId)

Removes the DOM event listener that has previously been added via the caplin.dom.Utility#addEventListener method.

Parameters
Number uniqueListenerId The event Listener Id that was returned by the method caplin.dom.Utility#addEventListener.

► <static> void replaceClassName(Element element, String currentClass, String newClass)

Replaces the specified CSS class name on the DOM element with another class.

Parameters
Element element The HTML DOM element to add the class to.
String currentClass The class name to replace.
String newClass The new name of the class.

► <static> void setInnerHtml(Element element, String html)

Sets the innerHTML of the specified element in an efficient way.

Parameters
Element element The element on which innerHTML needs to be set.
String html The HTML that will be set in the element.

► <static> void stopEventPropagation(Event event)

Stops the propagation of an event. This method should be used within an event listener to prevent bubbling of an event up to other event listeners.

Parameters
Event event Event passed to your event handler. Note that event handlers are not wrapped so you need to do something like event = event || window.event;.