dom.js

Members

(static, constant) $

Finds a single DOM element matching selector within the optional context of another DOM element (defaulting to document).

(static, constant) $$

Finds a all DOM elements matching selector within the optional context of another DOM element (defaulting to document).

Methods

(static) addClass(element, …classesToAdd) → {Element}

Add a class name to an element.

Parameters:
NameTypeAttributesDescription
elementElement

Element to add class name to.

classesToAddstring<repeatable>

One or more class name to add.

Returns:

The DOM element with the added class name.

Type: 
Element

(static) appendContent(el, content) → {Element}

Normalizes and appends content to an element.

Parameters:
NameTypeDescription
elElement

Element to append normalized content to.

contentContentDescriptor

A content descriptor value.

Returns:

The element with appended normalized content.

Type: 
Element

(static) blockTextSelection()

Attempt to block the ability to select text.

(static) computedStyle(el, prop)

A safe getComputedStyle.

This is needed because in Firefox, if the player is loaded in an iframe with display:none, then getComputedStyle returns null, so, we do a null-check to make sure that the player doesn't break in these cases.

Parameters:
NameTypeDescription
elElement

The element you want the computed style of

propstring

The property name you want

(static) copyStyleSheetsToWindow(win)

Copy document style sheets to another window.

Parameters:
NameTypeDescription
winWindow

The window element you want to copy the document style sheets to.

(static) createEl(tagNameopt, propertiesopt, attributesopt, contentopt) → {Element}

Creates an element and applies properties, attributes, and inserts content.

Parameters:
NameTypeAttributesDefaultDescription
tagNamestring<optional>
'div'

Name of tag to be created.

propertiesObject<optional>
{}

Element properties to be applied.

attributesObject<optional>
{}

Element attributes to be applied.

contentContentDescriptor<optional>

A content descriptor object.

Returns:

The element that was created.

Type: 
Element

(static) emptyEl(el) → {Element}

Empties the contents of an element.

Parameters:
NameTypeDescription
elElement

The element to empty children from

Returns:

The element with no children

Type: 
Element

(static) findPosition(el) → {module:dom~Position}

Get the position of an element in the DOM.

Uses getBoundingClientRect technique from John Resig.

Parameters:
NameTypeDescription
elElement

Element from which to get offset.

Returns:

The position of the element that was passed in.

Type: 
module:dom~Position

(static) getAttribute(el, attribute) → {string}

Get the value of an element's attribute.

Parameters:
NameTypeDescription
elElement

A DOM element.

attributestring

Attribute to get the value of.

Returns:

The value of the attribute.

Type: 
string

(static) getAttributes(tag) → {Object}

Get an element's attribute values, as defined on the HTML tag.

Attributes are not the same as properties. They're defined on the tag or with setAttribute.

Parameters:
NameTypeDescription
tagElement

Element from which to get tag attributes.

Returns:

All attributes of the element. Boolean attributes will be true or false, others will be strings.

Type: 
Object

(static) getBoundingClientRect(el) → {Object|undefined}

Identical to the native getBoundingClientRect function, but ensures that the method is supported at all (it is in all browsers we claim to support) and that the element is in the DOM before continuing.

This wrapper function also shims properties which are not provided by some older browsers (namely, IE8).

Additionally, some browsers do not support adding properties to a ClientRect/DOMRect object; so, we shallow-copy it with the standard properties (except x and y which are not widely supported). This helps avoid implementations where keys are non-enumerable.

Parameters:
NameTypeDescription
elElement

Element whose ClientRect we want to calculate.

Returns:

Always returns a plain object - or undefined if it cannot.

Type: 
Object | undefined

(static) getPointerPosition(el, event) → {module:dom~Coordinates}

Get the pointer position within an element.

The base on the coordinates are the bottom left of the element.

Parameters:
NameTypeDescription
elElement

Element on which to get the pointer position on.

eventEvent

Event object.

Returns:

A coordinates object corresponding to the mouse position.

Type: 
module:dom~Coordinates

(static) hasClass(element, classToCheck) → {boolean}

Check if an element has a class name.

Parameters:
NameTypeDescription
elementElement

Element to check

classToCheckstring

Class name to check for

Throws:

Throws an error if classToCheck has white space.

Type
Error
Returns:

Will be true if the element has a class, false otherwise.

Type: 
boolean

(static) insertContent(el, content) → {Element}

Normalizes and inserts content into an element; this is identical to appendContent(), except it empties the element first.

Parameters:
NameTypeDescription
elElement

Element to insert normalized content into.

contentContentDescriptor

A content descriptor value.

Returns:

The element with inserted normalized content.

Type: 
Element

(static) isEl(value) → {boolean}

Determines, via duck typing, whether or not a value is a DOM element.

Parameters:
NameTypeDescription
value*

The value to check.

Returns:

Will be true if the value is a DOM element, false otherwise.

Type: 
boolean

(static) isInFrame() → {boolean}

Determines if the current DOM is embedded in an iframe.

Returns:

Will be true if the DOM is embedded in an iframe, false otherwise.

Type: 
boolean

(static) isReal() → {boolean}

Whether the current DOM interface appears to be real (i.e. not simulated).

Returns:

Will be true if the DOM appears to be real, false otherwise.

Type: 
boolean

(static) isSingleLeftClick(event) → {boolean}

Check if an event was a single left click.

Parameters:
NameTypeDescription
eventMouseEvent

Event object.

Returns:

Will be true if a single left click, false otherwise.

Type: 
boolean

(static) isTextNode(value) → {boolean}

Determines, via duck typing, whether or not a value is a text node.

Parameters:
NameTypeDescription
value*

Check if this value is a text node.

Returns:

Will be true if the value is a text node, false otherwise.

Type: 
boolean

(static) normalizeContent(content) → {Array}

Normalizes content for eventual insertion into the DOM.

This allows a wide range of content definition methods, but helps protect from falling into the trap of simply writing to innerHTML, which could be an XSS concern.

The content for an element can be passed in multiple types and combinations, whose behavior is as follows:

Parameters:
NameTypeDescription
contentContentDescriptor

A content descriptor value.

Returns:

All of the content that was passed in, normalized to an array of elements or text nodes.

Type: 
Array

(static) prependTo(child, parent)

Insert an element as the first child node of another

Parameters:
NameTypeDescription
childElement

Element to insert

parentElement

Element to insert child into

(static) removeAttribute(el, attribute)

Remove an element's attribute.

Parameters:
NameTypeDescription
elElement

A DOM element.

attributestring

Attribute to remove.

(static) removeClass(element, …classesToRemove) → {Element}

Remove a class name from an element.

Parameters:
NameTypeAttributesDescription
elementElement

Element to remove a class name from.

classesToRemovestring<repeatable>

One or more class name to remove.

Returns:

The DOM element with class name removed.

Type: 
Element

(static) setAttribute(el, attribute, value)

Set the value of an element's attribute.

Parameters:
NameTypeDescription
elElement

A DOM element.

attributestring

Attribute to set.

valuestring

Value to set the attribute to.

(static) setAttributes(el, attributesopt)

Apply attributes to an HTML element.

Parameters:
NameTypeAttributesDescription
elElement

Element to add attributes to.

attributesObject<optional>

Attributes to be applied.

(static) textContent(el, text) → {Element}

Injects text into an element, replacing any existing contents entirely.

Parameters:
NameTypeDescription
elHTMLElement

The element to add text content into

textstring

The text content to add.

Returns:

The element with added text content.

Type: 
Element

(static) toggleClass(element, classToToggle, predicateopt) → {Element}

Adds or removes a class name to/from an element depending on an optional condition or the presence/absence of the class name.

Parameters:
NameTypeAttributesDescription
elementElement

The element to toggle a class name on.

classToTogglestring

The class that should be toggled.

predicateboolean | module:dom~PredicateCallback<optional>

See the return value for module:dom~PredicateCallback

Returns:

The element with a class that has been toggled.

Type: 
Element

(static) unblockTextSelection()

Turn off text selection blocking.

Type Definitions

ContentDescriptor()

This is a mixed value that describes content to be injected into the DOM via some method. It can be of the following types:

TypeDescription
stringThe value will be normalized into a text node.
ElementThe value will be accepted as-is.
TextA TextNode. The value will be accepted as-is.
ArrayA one-dimensional array of strings, elements, text nodes, or functions. These functions should return a string, element, or text node (any other return value, like an array, will be ignored).
FunctionA function, which is expected to return a string, element, text node, or array - any of the other possible values described above. This means that a content descriptor could be a function that returns an array of functions, but those second-level functions must return strings, elements, or text nodes.

Coordinates

Represents x and y coordinates for a DOM element or mouse pointer.

Type:
  • Object
Properties
NameTypeDescription
xnumber

x coordinate in pixels

ynumber

y coordinate in pixels

Position

Represents the position of a DOM element on the page.

Type:
  • Object
Properties
NameTypeDescription
leftnumber

Pixels to the left.

topnumber

Pixels from the top.

PredicateCallback(element, classToToggle) → {boolean|undefined}

The callback definition for toggleClass.

Parameters:
NameTypeDescription
elementElement

The DOM element of the Component.

classToTogglestring

The className that wants to be toggled

Returns:

If true is returned, the classToToggle will be added to the element. If false, the classToToggle will be removed from the element. If undefined, the callback will be ignored.

Type: 
boolean | undefined