DOM Functions Reference

Related documents

• MVCS index

Table of contents

• Introduction
• DOM Functions
  • addCssClass()
  • Parameters
  • chooseCssClass()
  • Parameters
  • eltGetAncestorByTag()
  • Parameters
  • eltOuterHeight()
  • Parameters
  • eltOuterWidth()
  • Parameters
  • eltScrollTo()
  • Parameters
  • eltTransition()
  • Parameters
  • evtGetPointerX()
  • Parameters
  • evtGetPointerY()
  • Parameters
  • getElt()
  • Parameters
  • hasCssClass()
  • Parameters
  • hasElt()
  • Parameters
  • importStyleSheet()
  • Parameters
  • isDomNode()
  • Parameters
  • replaceCssClass()
  • Parameters

Introduction

The DOM functions manipulate DOM elements. All DOM functions are properties of the global/window object and may be used without importing.

DOM Functions

addCssClass()

Import

Global

Syntax

addCssClass(arg1, ...classNames)

Adds CSS classes to an element, object, or string. The arguments in classNames are strings of class names separated by spaces.

If arg1 is a string, it is considered to be class names separated by spaces, and the class names in the classNames arguments are added to arg1 if they don't exist. The resulting string of class names is returned.

If arg1 is an object or DOM element, then the class names in the classNames arguments are added to the class names in arg1.className if they don't exist. If arg1.className does not exist, then arg1.className is set to the class names in the classNames arguments with any duplicates removed.

Parameters

• arg1
  An object, DOM element, or string. If a string, it should contain zero or more CSS class names separated by spaces. If an object, then the className property should contain zero or more CSS class names separated by spaces, if present.
• classNames
  The classNames arguments are strings containing zero or more CSS class names separated by spaces.

Return value

If arg1 is a string, then a string is returned containing all the CSS classes specified in the arguments without duplicates. If arg1 is a DOM element or object, then undefined is returned.

chooseCssClass()

Import

Global

Syntax

chooseCssClass(arg1, choice, ...choices)

Adds a single choice of CSS class name to the string, object, or DOM element specified by arg1. All the remaining choices are removed. The choice argument is an index into the choices arguments. This is useful when a CSS class string must have one of several different class names but not more than one.

Parameters

• arg1
  An object, DOM element, or string. If a string, it should contain zero or more CSS class names separated by spaces. If an object, then the className property should contain zero or more CSS class names separated by spaces, if present.
• choice
  An index into the choices arguments. A non-finite value (e.g. a Boolean) is coerced to 1 if truthy, otherwise 0. If the index is out of range, no class is chosen and all the choices classes are removed.
• choices
  The choices arguments are strings containing zero or more CSS class names separated by spaces.

Return value

If arg1 is a string, then a string is returned containing all the CSS classes with the chosen class names, with the others removed. If arg1 is a DOM element or object, then undefined is returned.

eltGetAncestorByTag()

Import

Global

Syntax

eltGetAncestorByTag(elt, tag)

Return the enclosing element with the given tag. For example, eltGetAncestorByTag(elt, 'tr') returns the enclosing table row. The search stops at the <body> element. If no ancestor has the tag, an assert() failure is generated (logged and alerted) before null is returned.

Parameters

• elt
  A DOM element or a DOM element ID string.
• tag
  The tag string of the requested enclosing element.

Return value

A DOM element, if the tag is found, or null otherwise.

eltOuterHeight()

Import

Global

Syntax

eltOuterHeight(elt)

Returns the height of the element's bounding box in pixels (px units).

Parameters

• elt
  A DOM element or a DOM element ID string.

Return value

A number.

eltOuterWidth()

Import

Global

Syntax

eltOuterWidth(elt)

Returns the width of the element's bounding box in pixels (px units).

Parameters

• elt
  A DOM element or a DOM element ID string.

Return value

A number.

eltScrollTo()

Import

Global

Syntax

eltScrollTo(elt, top, duration)

Smoothly scrolls elt so that its scrollTop becomes top, using cosine easing so the motion starts and ends gently. When the document is hidden, where requestAnimationFrame() never fires, the animation is driven by a timer instead so the Promise still resolves.

Parameters

• elt
  A DOM element or a DOM element ID string.
• top
  The target scrollTop value in pixels.
• duration
  The duration of the scroll in milliseconds.

Return value

A Promise that resolves when the scroll is complete.

eltTransition()

Import

Global

Syntax

eltTransition(elt, startFn)

Asynchronously set up a transition on a DOM element.

startFn is a function that is called asynchronously when the current thread completes. This allows eltTransition() to be called before the element is fully painted with it's current style. At that point, the startFn can set up a transition or a new CSS class with a transition. The startFn is passed the DOM element as its single argument.

eltTransition() returns a Promise that resolves when the transition is complete.

Parameters

• elt
  A DOM element or a DOM element ID string.
• startFn
  A function having the signature startFn(elt) where elt is the DOM element referenced by the eltTransition() elt argument. startFn() should set up the element with the new transition either by changing style or CSS class name.

Return value

A Promise that resolves when the transition is complete.

evtGetPointerX()

Import

Global

Syntax

evtGetPointerX(evt)

Returns the client X offset in pixels from the evt event object. On touch devices it returns the first touch point's X offset.

Parameters

• evt
  An Event object.

Return value

A number.

evtGetPointerY()

Import

Global

Syntax

evtGetPointerY(evt)

Returns the client Y offset in pixels from the evt event object. On touch devices it returns the first touch point's Y offset.

Parameters

• evt
  An Event object.

Return value

A number.

getElt()

Import

Global

Syntax

getElt(id)

Returns the DOM element whose ID string is id. getElt() generates an assertion failure if the ID is not found.

Parameters

• id
  An DOM element ID string.

Return value

A DOM element.

hasCssClass()

Import

Global

Syntax

hasCssClass(arg1, className)

Return true if the DOM element, object, or string contains the string className.

If arg1 is a string, it is considered to be class names separated by spaces, and hasCssClass() returns true if the string includes className. It returns false if className is not present.

If arg1 is an object or DOM element, then hasCssClass() returns true if arg1.className includes className. It returns false if className is not present or arg1.className does not exist.

Parameters

• arg1
  An object, DOM element, or string. If a string, it should contain zero or more CSS class names separated by spaces. If an object, then the className property should contain zero or more CSS class names separated by spaces, if present.
• className
  A string contains a single CSS class name.

Return value

A Boolean

hasElt()

Import

Global

Syntax

hasElt(id)

Returns true if the DOM element whose ID string is id exists.

Parameters

• id
  An DOM element ID string.

Return value

A Boolean.

importStyleSheet()

Import

Global

Syntax

importStyleSheet(file)

A build-time placeholder. The function does nothing at run time; the build process finds the call and imports the CSS stylesheet.

Parameters

• file
  The path of the CSS file to import.

Return value

undefined.

isDomNode()

Import

Global

Syntax

isDomNode(arg)

Returns true if arg is a DOM element.

Parameters

• arg
  Any type.

Return value

A Boolean.

replaceCssClass()

Import

Global

Syntax

replaceCssClass(arg1, oldClass)
replaceCssClass(arg1, oldClass, newClass)

Deletes the CSS classes in oldClass and adds the CSS classes in newClass to the element, object, or string specified by arg1. If newClass is not provided, then the oldClass classes are deleted.

If arg1 is a string, it is considered to be class names separated by spaces, and the class names in oldClass are deleted, and the class names in the newClass are added if they don't exist. The resulting string of class names is returned.

If arg1 is an object or DOM element, then the class names in oldClass are deleted from arg1.className, and the class names in the newClass are added to arg1.className, if they don't exist. If arg1.className does not exist, then arg1.className is set to the class names in the newClass argument with any duplicates removed.

Parameters

• arg1
  An object, DOM element, or string. If a string, it should contain zero or more CSS class names separated by spaces. If an object, then the className property should contain zero or more CSS class names separated by spaces, if present.
• oldClass
  A string containing zero or more CSS class names separated by spaces that are to be deleted.
• newClass (opional)
  A string containing zero or more CSS class names separated by spaces that are to be added.

Return value

If arg1 is a string, then a string is returned containing the result of deleting and adding the specified classes to the original string without duplicates. If arg1 is a DOM element or object, then undefined is returned.