1. Home
  2. Modules
  3. DOMTools
Description

Helpful utilities for dealing with DOM operations.

This module also extends HTMLElement to add a set of utility functions, the same as the ones available in the module itself, but with the element parameter bound to this.

Details

modules/domtools.js, line 1

Classes

new Selector( classname )

new ClassName( name )

new DOMObserver()

Members

<static> observer

Description

Default DOMObserver for global usage.

Details

modules/domtools.js, line 39

DOMObserver

<static> screenWidth

Description

Document/window width

Details

modules/domtools.js, line 44

<static> screenHeight

Description

Document/window height

Details

modules/domtools.js, line 47

Methods

<static> addStyle( id, css )

Description

Adds a style to the document.

Parameters
Name Type Description
id string

identifier to use as the element id
css string

css to add to the document
Details

modules/domtools.js, line 72

<static> removeStyle( id )

Description

Removes a style from the document.

Parameters
Name Type Description
id string

original identifier used
Details

modules/domtools.js, line 80

<static> addScript( id, url ) → {Promise}

Description

Adds/requires a remote script to be loaded

Parameters
Name Type Description
id string

identifier to use for this script
url string

url from which to load the script
Returns

promise that resolves when the script is loaded

Details

modules/domtools.js, line 91

<static> removeScript( id )

Description

Removes a remote script from the document.

Parameters
Name Type Description
id string

original identifier used
Details

modules/domtools.js, line 106

<static> Q( selector ) → {DocumentFragment|NodeList|HTMLElement}

Description

This is my shit version of not having to use $ from jQuery. Meaning that you can pass a selector and it will automatically run module:DOMTools.query. It also means that you can pass a string of html and it will perform and return parseHTML.

Parameters
Name Type Description
selector string

Selector to query or HTML to parse
Returns
  • Either the result of parseHTML or query
Details

modules/domtools.js, line 120

<static> query( selector [, baseElement ] ) → {Element|null}

Description

Essentially a shorthand for document.querySelector. If the baseElement is not provided document is used by default.

Parameters
Name Type Attributes Description
selector string

Selector to query
baseElement Element <optional>

Element to base the query from
Returns
  • The found element or null if not found
Details

modules/domtools.js, line 134

<static> queryAll( selector [, baseElement ] ) → {Array.<Element>}

Description

Essentially a shorthand for document.querySelectorAll. If the baseElement is not provided document is used by default.

Parameters
Name Type Attributes Description
selector string

Selector to query
baseElement Element <optional>

Element to base the query from
Returns
  • Array of all found elements
Details

modules/domtools.js, line 146

<static> parseHTML( html [, fragment ] ) → {DocumentFragment|NodeList|HTMLElement}

Description

Parses a string of HTML and returns the results. If the second parameter is true, the parsed HTML will be returned as a document fragment {@see https://developer.mozilla.org/en-US/docs/Web/API/DocumentFragment}. This is extremely useful if you have a list of elements at the top level, they can then be appended all at once to another node.

If the second parameter is false, then the return value will be the list of parsed nodes and there were multiple top level nodes, otherwise the single node is returned.

Parameters
Name Type Attributes Default Description
html string

HTML to be parsed
fragment boolean <optional>
 false

Whether or not the return should be the raw DocumentFragment
Returns
  • The result of HTML parsing
Details

modules/domtools.js, line 162

<static> createElement()

Description

Alternate name for module:DOMTools.parseHTML

Details

modules/domtools.js, line 171

<static> escapeHTML( html )

Description

Takes a string of html and escapes it using the brower's own escaping mechanism.

Parameters
Name Type Description
html String

html to be escaped
Details

modules/domtools.js, line 177

<static> escapeID( id )

Description

Takes a string and escapes it for use as a DOM id.

Parameters
Name Type Description
id String

string to be escaped
Details

modules/domtools.js, line 189

<static> addClass( element, ...classes ) → {Element}

Description

Adds a list of classes from the target element.

Parameters
Name Type Attributes Description
element Element

Element to edit classes of
classes string <repeatable>

Names of classes to add
Returns
  • element to allow for chaining
Details

modules/domtools.js, line 199

<static> removeClass( element, ...classes ) → {Element}

Description

Removes a list of classes from the target element.

Parameters
Name Type Attributes Description
element Element

Element to edit classes of
classes string <repeatable>

Names of classes to remove
Returns
  • element to allow for chaining
Details

modules/domtools.js, line 213

<static> toggleClass( element, classname [, indicator ] ) → {Element}

Description

When only one argument is present: Toggle class value; i.e., if class exists then remove it and return false, if not, then add it and return true. When a second argument is present: If the second argument evaluates to true, add specified class value, and if it evaluates to false, remove it.

Parameters
Name Type Attributes Description
element Element

Element to edit classes of
classname string

Name of class to toggle
indicator boolean <optional>

Optional indicator for if the class should be toggled
Returns
  • element to allow for chaining
Details

modules/domtools.js, line 230

<static> hasClass( element, classname ) → {boolean}

Description

Checks if an element has a specific class

Parameters
Name Type Description
element Element

Element to edit classes of
classname string

Name of class to check
Returns
  • true if the element has the class, false otherwise.
Details

modules/domtools.js, line 243

<static> replaceClass( element, oldName, newName ) → {Element}

Description

Replaces one class with another

Parameters
Name Type Description
element Element

Element to edit classes of
oldName string

Name of class to replace
newName string

New name for the class
Returns
  • element to allow for chaining
Details

modules/domtools.js, line 254

<static> appendTo( thisNode, thatNode ) → {Node}

Description

Appends thisNode to thatNode

Parameters
Name Type Description
thisNode Node

Node to be appended to another node
thatNode Node

Node for thisNode to be appended to
Returns
  • thisNode to allow for chaining
Details

modules/domtools.js, line 265

<static> prependTo( thisNode, thatNode ) → {Node}

Description

Prepends thisNode to thatNode

Parameters
Name Type Description
thisNode Node

Node to be prepended to another node
thatNode Node

Node for thisNode to be prepended to
Returns
  • thisNode to allow for chaining
Details

modules/domtools.js, line 278

<static> insertAfter( thisNode, targetNode ) → {Node}

Description

Insert after a specific element, similar to jQuery's thisElement.insertAfter(otherElement).

Parameters
Name Type Description
thisNode Node

The node to insert
targetNode Node

Node to insert after in the tree
Returns
  • thisNode to allow for chaining
Details

modules/domtools.js, line 291

<static> after( thisNode, newNode ) → {Node}

Description

Insert after a specific element, similar to jQuery's thisElement.after(newElement).

Parameters
Name Type Description
thisNode Node

The node to insert
newNode Node

Node to insert after in the tree
Returns
  • thisNode to allow for chaining
Details

modules/domtools.js, line 302

<static> next( element [, selector ] ) → {Element}

Description

Gets the next sibling element that matches the selector.

Parameters
Name Type Attributes Default Description
element Element

Element to get the next sibling of
selector string <optional>
 ""

Optional selector
Returns
  • The sibling element
Details

modules/domtools.js, line 313

<static> nextAll( element ) → {NodeList}

Description

Gets all subsequent siblings.

Parameters
Name Type Description
element Element

Element to get next siblings of
Returns
  • The list of siblings
Details

modules/domtools.js, line 322

<static> nextUntil( element, selector ) → {Array.<Element>}

Description

Gets the subsequent siblings until an element matches the selector.

Parameters
Name Type Description
element Element

Element to get the following siblings of
selector string

Selector to stop at
Returns
  • The list of siblings
Details

modules/domtools.js, line 332

<static> previous( element [, selector ] ) → {Element}

Description

Gets the previous sibling element that matches the selector.

Parameters
Name Type Attributes Default Description
element Element

Element to get the previous sibling of
selector string <optional>
 ""

Optional selector
Returns
  • The sibling element
Details

modules/domtools.js, line 344

<static> previousAll( element ) → {NodeList}

Description

Gets all preceeding siblings.

Parameters
Name Type Description
element Element

Element to get preceeding siblings of
Returns
  • The list of siblings
Details

modules/domtools.js, line 355

<static> previousUntil( element, selector ) → {Array.<Element>}

Description

Gets the preceeding siblings until an element matches the selector.

Parameters
Name Type Description
element Element

Element to get the preceeding siblings of
selector string

Selector to stop at
Returns
  • The list of siblings
Details

modules/domtools.js, line 367

<static> indexInParent( node ) → {number}

Description

Find which index in children a certain node is. Similar to jQuery's $.index()

Parameters
Name Type Description
node HTMLElement

The node to find its index in parent
Returns

Index of the node

Details

modules/domtools.js, line 378

<static> index()

Description

Shorthand for module:DOMTools.indexInParent

Details

modules/domtools.js, line 389

<static> parent( element [, selector ] ) → {Element|null}

Description

Gets the parent of the element if it matches the selector, otherwise returns null.

Parameters
Name Type Attributes Default Description
element Element

Element to get parent of
selector string <optional>
 ""

Selector to match parent
Returns
  • The sibling element or null
Details

modules/domtools.js, line 398

<static> findChild( element, selector ) → {Array.<Element>}

Description

Gets all children of Element that match the selector if provided.

Parameters
Name Type Description
element Element

Element to get all children of
selector string

Selector to match the children to
Returns
  • The list of children
Details

modules/domtools.js, line 408

<static> findChildren( element, selector ) → {Array.<Element>}

Description

Gets all children of Element that match the selector if provided.

Parameters
Name Type Description
element Element

Element to get all children of
selector string

Selector to match the children to
Returns
  • The list of children
Details

modules/domtools.js, line 418

<static> parents( element [, selector ] ) → {Array.<Element>}

Description

Gets all ancestors of Element that match the selector if provided.

Parameters
Name Type Attributes Default Description
element Element

Element to get all parents of
selector string <optional>
 ""

Selector to match the parents to
Returns
  • The list of parents
Details

modules/domtools.js, line 428

<static> parentsUntil( element, selector ) → {Array.<Element>}

Description

Gets the ancestors until an element matches the selector.

Parameters
Name Type Description
element Element

Element to get the ancestors of
selector string

Selector to stop at
Returns
  • The list of parents
Details

modules/domtools.js, line 441

<static> siblings( element [, selector ] ) → {Array.<Element>}

Description

Gets all siblings of the element that match the selector.

Parameters
Name Type Attributes Default Description
element Element

Element to get all siblings of
selector string <optional>
 "*"

Selector to match the siblings to
Returns
  • The list of siblings
Details

modules/domtools.js, line 453

<static> css( element, attribute [, value ] ) → {Element|string}

Description

Sets or gets css styles for a specific element. If value is provided then it sets the style and returns the element to allow for chaining, otherwise returns the style.

Parameters
Name Type Attributes Description
element Element

Element to set the CSS of
attribute string

Attribute to get or set
value string <optional>

Value to set for attribute
Returns
  • When setting a value, element is returned for chaining, otherwise the value is returned.
Details

modules/domtools.js, line 466

<static> width( element [, value ] ) → {Element|string}

Description

Sets or gets the width for a specific element. If value is provided then it sets the width and returns the element to allow for chaining, otherwise returns the width.

Parameters
Name Type Attributes Description
element Element

Element to set the CSS of
value string <optional>

Width to set
Returns
  • When setting a value, element is returned for chaining, otherwise the value is returned.
Details

modules/domtools.js, line 480

<static> height( element [, value ] ) → {Element|string}

Description

Sets or gets the height for a specific element. If value is provided then it sets the height and returns the element to allow for chaining, otherwise returns the height.

Parameters
Name Type Attributes Description
element Element

Element to set the CSS of
value string <optional>

Height to set
Returns
  • When setting a value, element is returned for chaining, otherwise the value is returned.
Details

modules/domtools.js, line 494

<static> text( element [, text ] ) → {string}

Description

Sets the inner text of an element if given a value, otherwise returns it.

Parameters
Name Type Attributes Description
element Element

Element to set the text of
text string <optional>

Content to set
Returns
  • Either the string set by this call or the current text content of the node.
Details

modules/domtools.js, line 506

<static> innerWidth( element ) → {number}

Description

Returns the innerWidth of the element.

Parameters
Name Type Description
element Element

Element to retrieve inner width of
Returns
  • The inner width of the element.
Details

modules/domtools.js, line 516

<static> innerHeight( element ) → {number}

Description

Returns the innerHeight of the element.

Parameters
Name Type Description
element Element

Element to retrieve inner height of
Returns
  • The inner height of the element.
Details

modules/domtools.js, line 525

<static> outerWidth( element ) → {number}

Description

Returns the outerWidth of the element.

Parameters
Name Type Description
element Element

Element to retrieve outer width of
Returns
  • The outer width of the element.
Details

modules/domtools.js, line 534

<static> outerHeight( element ) → {number}

Description

Returns the outerHeight of the element.

Parameters
Name Type Description
element Element

Element to retrieve outer height of
Returns
  • The outer height of the element.
Details

modules/domtools.js, line 543

<static> offset( element ) → {Offset}

Description

Gets the offset of the element in the page.

Parameters
Name Type Description
element Element

Element to get offset of
Returns
  • The offset of the element
Details

modules/domtools.js, line 552

<static> on( element, event, delegate [, callback ] ) → {module:DOMTools~CancelListener}

Description

This is similar to jQuery's on function and can hopefully be used in the same way.

Rather than attempt to explain, I'll show some example usages.

The following will add a click listener (in the myPlugin namespace) to element. DOMTools.on(element, "click.myPlugin", () => {console.log("clicked!");});

The following will add a click listener (in the myPlugin namespace) to element that only fires when the target is a .block element. DOMTools.on(element, "click.myPlugin", ".block", () => {console.log("clicked!");});

The following will add a click listener (without namespace) to element. DOMTools.on(element, "click", () => {console.log("clicked!");});

The following will add a click listener (without namespace) to element that only fires once. const cancel = DOMTools.on(element, "click", () => {console.log("fired!"); cancel();});

Parameters
Name Type Attributes Description
element Element

Element to add listener to
event string

Event to listen to with option namespace (e.g. "event.namespace")
delegate string | callable

Selector to run on element to listen to
callback callable <optional>

Function to fire on event
Returns
  • A function that will undo the listener
Details

modules/domtools.js, line 581

<static> once( element, event, delegate [, callback ] ) → {module:DOMTools~CancelListener}

Description

Functionality for this method matches module:DOMTools.on but automatically cancels itself and removes the listener upon the first firing of the desired event.

Parameters
Name Type Attributes Description
element Element

Element to add listener to
event string

Event to listen to with option namespace (e.g. "event.namespace")
delegate string | callable

Selector to run on element to listen to
callback callable <optional>

Function to fire on event
Returns
  • A function that will undo the listener
Details

modules/domtools.js, line 621

<static> off( element [, event [, delegate [, callback ] ] ] ) → {Element}

Description

This is similar to jQuery's off function and can hopefully be used in the same way.

Rather than attempt to explain, I'll show some example usages.

The following will remove a click listener called onClick (in the myPlugin namespace) from element. DOMTools.off(element, "click.myPlugin", onClick);

The following will remove a click listener called onClick (in the myPlugin namespace) from element that only fired when the target is a .block element. DOMTools.off(element, "click.myPlugin", ".block", onClick);

The following will remove a click listener (without namespace) from element. DOMTools.off(element, "click", onClick);

The following will remove all listeners in namespace myPlugin from element. DOMTools.off(element, ".myPlugin");

The following will remove all click listeners in namespace myPlugin from all elements. DOMTools.off("click.myPlugin");

The following will remove all listeners in namespace myPlugin from all elements. DOMTools.off(".myPlugin");

Parameters
Name Type Attributes Description
element Element | string

Element to remove listener from
event string <optional>

Event to listen to with option namespace (e.g. "event.namespace")
delegate string | callable <optional>

Selector to run on element to listen to
callback callable <optional>

Function to fire on event
Returns
  • The original element to allow for chaining
Details

modules/domtools.js, line 695

<static> onMountChange( node, callback, onMount )

Description

Adds a listener for when the node is added/removed from the document body. The listener is automatically removed upon firing.

Parameters
Name Type Default Description
node HTMLElement

node to wait for
callback callable

function to be performed on event
onMount boolean true

determines if it should fire on Mount or on Unmount
Details

modules/domtools.js, line 719

<static> onMount()

Description

Shorthand for module:DOMTools.onMountChange with third parameter true

Details

modules/domtools.js, line 734

<static> onUnmount()

Description

Shorthand for module:DOMTools.onMountChange with third parameter false

Details

modules/domtools.js, line 737

<static> onAdded()

Description

Alias for module:DOMTools.onMount

Details

modules/domtools.js, line 740

<static> onRemoved()

Description

Alias for module:DOMTools.onUnmount

Details

modules/domtools.js, line 743

<static> wrap( elements )

Description

Helper function which combines multiple elements into one parent element

Parameters
Name Type Description
elements Array.<HTMLElement>

array of elements to put into a single parent
Details

modules/domtools.js, line 749

<static> resolveElement( node )

Description

Resolves the node to an HTMLElement. This is mainly used by library modules.

Parameters
Name Type Description
node jQuery | Element

node to resolve
Details

modules/domtools.js, line 759

Type Definitions

CancelListener()

Description

Function that automatically removes added listener.

Details
function

modules/domtools.js, line 23