dom.js

### Members

#### static, constant $
`utils/dom.js`, `line 746`

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

#### static, constant $$
`utils/dom.js`, `line 765`

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

### Methods

#### static addClass(element, classToAdd) → {Element}
`utils/dom.js`, `line 239`

  Add a CSS class name to an element

  ##### Parameters:

  Name | Type | Description
  --- | --- | ---
  `element` | Element | Element to add class name to.
  `classToAdd` | string | Class name to add.

  ##### Returns:

  Element -

  The dom element with the added class name.

#### static appendContent(el, content) → {Element}
`utils/dom.js`, `line 707`

  Normalizes and appends content to an element.

  ##### Parameters:

  Name | Type | Description
  --- | --- | ---
  `el` | Element | Element to append normalized content to.
  `content` | String | Element | TextNode | Array | function | See the `content` argument of dom:normalizeContent

  ##### Returns:

  Element -

  The element with appended normalized content.

#### static blockTextSelection()
`utils/dom.js`, `line 451`

  Attempt to block the ability to select text while dragging controls

#### static createEl(tagNameopt, propertiesopt, attributesopt, contentopt) → {Element}
`utils/dom.js`, `line 130`

  Creates an element and applies properties.

  ##### Parameters:

  Name | Type | Attributes | Default | Description
  --- | --- | --- | --- | ---
  `tagName` | string | <optional> | 'div' | Name of tag to be created.
  `properties` | Object | <optional> | {} | Element properties to be applied.
  `attributes` | Object | <optional> | {} | Element attributes to be applied.
  `content` | String | Element | TextNode | Array | function | <optional> |  | Contents for the element (see: dom:normalizeContent)

  ##### Returns:

  Element -

  The element that was created.

#### static emptyEl(el) → {Element}
`utils/dom.js`, `line 638`

  Empties the contents of an element.

  ##### Parameters:

  Name | Type | Description
  --- | --- | ---
  `el` | Element | The element to empty children from

  ##### Returns:

  Element -

  The element with no children

#### static findPosition(el) → {module:dom~Position}
`utils/dom.js`, `line 534`

  Offset Left. getBoundingClientRect technique from John Resig

  ##### Parameters:

  Name | Type | Description
  --- | --- | ---
  `el` | Element | Element from which to get offset

  ##### Returns:

  module:dom~Position -

  The position of the element that was passed in.

  See:
    - http://ejohn.org/blog/getboundingclientrect-is-awesome/

#### static getAttribute(el, attribute) → {string}
`utils/dom.js`, `line 415`

  Get the value of an element's attribute

  ##### Parameters:

  Name | Type | Description
  --- | --- | ---
  `el` | Element | A DOM element
  `attribute` | string | Attribute to get the value of

  ##### Returns:

  string -

  value of the attribute

#### static getAttributes(tag) → {Object}
`utils/dom.js`, `line 372`

  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 (which shouldn't be used with HTML) This will return true or false for boolean attributes.

  ##### Parameters:

  Name | Type | Description
  --- | --- | ---
  `tag` | Element | Element from which to get tag attributes.

  ##### Returns:

  Object -

  All attributes of the element.

#### static getBoundingClientRect(el) → {Object|undefined}
`utils/dom.js`, `line 486`

  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:

  Name | Type | Description
  --- | --- | ---
  `el` | Element | Element whose `ClientRect` we want to calculate.

  ##### Returns:

  Object | undefined -

  Always returns a plain

#### static getPointerPosition(el, event) → {Dom~Coordinates}
`utils/dom.js`, `line 593`

  Get pointer position in element Returns an object with x and y coordinates. The base on the coordinates are the bottom left of the element.

  ##### Parameters:

  Name | Type | Description
  --- | --- | ---
  `el` | Element | Element on which to get the pointer position on
  `event` | EventTarget~Event | Event object

  ##### Returns:

  Dom~Coordinates -

  A Coordinates object corresponding to the mouse position.

#### static hasClass(element, classToCheck) → {boolean}
`utils/dom.js`, `line 219`

  Check if an element has a CSS class

  ##### Parameters:

  Name | Type | Description
  --- | --- | ---
  `element` | Element | Element to check
  `classToCheck` | string | Class name to check for

  ##### Throws:

  Throws an error if `classToCheck` has white space.

  Type
    Error

  ##### Returns:

  boolean -
  - True if the element had the class

          - False otherwise.

#### static insertContent(el, content) → {Element}
`utils/dom.js`, `line 726`

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

  ##### Parameters:

  Name | Type | Description
  --- | --- | ---
  `el` | Element | Element to insert normalized content into.
  `content` | String | Element | TextNode | Array | function | See the `content` argument of dom:normalizeContent

  ##### Returns:

  Element -

  The element with inserted normalized content.

#### static isEl(value) → {boolean}
`utils/dom.js`, `line 84`

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

  ##### Parameters:

  Name | Type | Description
  --- | --- | ---
  `value` | Mixed | The thing to check

  ##### Returns:

  boolean -
  - True if it is a DOM element

          - False otherwise

#### static isReal() → {Boolean}
`utils/dom.js`, `line 63`

  Whether the current DOM interface appears to be real.

  ##### Returns:

  Boolean

#### static isTextNode(value) → {boolean}
`utils/dom.js`, `line 625`

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

  ##### Parameters:

  Name | Type | Description
  --- | --- | ---
  `value` | Mixed | Check if this value is a text node.

  ##### Returns:

  boolean -
  - True if it is a text node

          - False otherwise

#### static normalizeContent(content) → {Array}
`utils/dom.js`, `line 666`

  Normalizes content for eventual insertion into the DOM.

  This allows a wide range of content definition methods, but protects from falling into the trap of simply writing to `innerHTML`, which is an XSS concern.

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

  ##### Parameters:

  Name | Type | Description
  --- | --- | ---
  - `content` | String | Element | TextNode | Array | function | String: Normalized into a text node.
         - Element/TextNode: Passed through.
         - Array: A one-dimensional array of strings, elements, nodes, or functions
           (which return single strings, elements, or nodes).
         - Function: If the sole argument, is expected to produce a string, element,
           node, or array as defined above.

  ##### Returns:

  Array -

  All of the content that was passed in normalized.

#### static prependTo(child, parent)
`utils/dom.js`, `line 195`

  Insert an element as the first child node of another

  ##### Parameters:

  Name | Type | Description
  --- | --- | ---
  `child` | Element | Element to insert
  `parent` | Element | Element to insert child into

#### static removeAttribute(el, attribute)
`utils/dom.js`, `line 444`

  Remove an element's attribute

  ##### Parameters:

  Name | Type | Description
  --- | --- | ---
  `el` | Element | A DOM element
  `attribute` | string | Attribute to remove

#### static removeClass(element, classToRemove) → {Element}
`utils/dom.js`, `line 264`

  Remove a CSS class name from an element

  ##### Parameters:

  Name | Type | Description
  --- | --- | ---
  `element` | Element | Element to remove a class name from.
  `classToRemove` | string | Class name to remove

  ##### Returns:

  Element -

  The dom element with class name removed.

#### static setAttribute(el, attribute, value)
`utils/dom.js`, `line 431`

  Set the value of an element's attribute

  ##### Parameters:

  Name | Type | Description
  --- | --- | ---
  `el` | Element | A DOM element
  `attribute` | string | Attribute to set
  `value` | string | Value to set the attribute to

#### static setAttributes(el, attributesopt)
`utils/dom.js`, `line 348`

  Apply attributes to an HTML element.

  ##### Parameters:

  Name | Type | Attributes | Description
  --- | --- | --- | ---
  `el` | Element |  | Element to add attributes to.
  `attributes` | Object | <optional> | Attributes to be applied.

#### static textContent(el, text) → {Element}
`utils/dom.js`, `line 177`

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

  ##### Parameters:

  Name | Type | Description
  --- | --- | ---
  `el` | Element | The element to add text content into
  `text` | string | The text content to add.

  ##### Returns:

  Element -

  The element with added text content.

#### static toggleClass(element, classToToggle, predicateopt) → {Element}
`utils/dom.js`, `line 309`

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

  ##### Parameters:

  Name | Type | Attributes | Description
  --- | --- | --- | ---
  `element` | Element |  | The element to toggle a class name on.
  `classToToggle` | string |  | The class that should be toggled
  `predicate` | boolean | PredicateCallback | <optional> | See the return value for Dom~PredicateCallback

  ##### Returns:

  Element -

  The element with a class that has been toggled.

#### static unblockTextSelection()
`utils/dom.js`, `line 461`

  Turn off text selection blocking

#### inner classRegExp(className) → {RegExp}
`utils/dom.js`, `line 54`

  Produce a regular expression for matching a className within an elements className.

  ##### Parameters:

  Name | Type | Description
  --- | --- | ---
  `className` | string | The className to generate the RegExp for.

  ##### Returns:

  RegExp -

  The RegExp that will check for a specific `className` in an elements className.

#### inner createQuerier(method) → {function}
`utils/dom.js`, `line 97`

  Creates functions to query the DOM using a given method.

  ##### Parameters:

  Name | Type | Description
  --- | --- | ---
  `method` | string | The method to create the query with.

  ##### Returns:

  function -

  The query method

#### inner isNonBlankString(str) → {boolean}
`utils/dom.js`, `line 23`

  Detect if a value is a string with any non-whitespace characters.

  ##### Parameters:

  Name | Type | Description
  --- | --- | ---
  `str` | string | The string to check

  ##### Returns:

  boolean -
  - True if the string is non-blank

          - False otherwise

#### inner throwIfWhitespace(str)
`utils/dom.js`, `line 38`

  Throws an error if the passed string has whitespace. This is used by class methods to be relatively consistent with the classList API.

  ##### Parameters:

  Name | Type | Description
  --- | --- | ---
  `str` | string | The string to check for whitespace.

  ##### Throws:

  Throws an error if there is whitespace in the string.

  Type
    Error

### Type Definitions

#### Position
`utils/dom.js`, `line 509`

  The postion of a DOM element on the page.

  ##### Properties:

  Name | Type | Description
  --- | --- | ---
  `left` | number | Pixels to the left
  `top` | number | Pixels on top