@oframe/dom

Install

npm i @oframe/dom

yarn add @oframe/dom

import { DOM } from './DOM.mjs';

Documentation

@oframe/dom is a singleton factory class used to add js animation functionality to HTMLElements.

DOM.setup()

DOM.setup() will attach several properties and methods to the HTMLElement passed in to facilitate animation.

Syntax

node = DOM.setup(node)

Params

node

A HTMLElement object.

Return value

The same HTMLElement object passed in as the node parameter, with added properties and methods.

The added methods include:

node.css(styles)

node.animate(duration, values)

Both methods are aliases to:

DOM.css(node, styles)

DOM.animate(node, duration, values)

See documentation of the above methods later in this page for more info.

The added properties include:

opacity, perspective, x, y, z, scale, scaleX, scaleY, rotate, rotateX, rotateY, rotateZ, skewX, skewY

These include transform properties, and opacity. These are the only recommended properties for javascript animation as they are the only editable properties that do not cause a re-paint - merely a composite.

Animations on color, background-color, etc are recommended to use CSS-Transitions, and even-so should be used infrequently.

Note: added properties will not inherit from css values. The performance hit to check computed styles isn't worth it.

DOM.create()

DOM.create() is an alternative to document.createElement() with the addition that the created HTMLElement object is passed through DOM.setup() to receive the added properties and methods.

Syntax

node = DOM.create(tagName, [className])

Params

tagName optional

A String that specifies the type of element to be created. Used internally with document.createElement(). If not specified, tagName defaults to 'div'.

className optional

A String of the intended ClassName to add to the created HTMLElement.

Return value

An HTMLElement object with added properties and methods.

DOM.query()

DOM.query() is an alternative to document.querySelectorAll(), with the addition that the returned NodeList is passed through DOM.setup() to receive the added properties and methods.

Syntax

node = DOM.query(selector, [root])

Params

selectors

A DOMString containing one or more selectors to match against. Used internally with Document.querySelectorAll().

root optional

An HTMLElement object within which to perform the search query. If not specified, root defaults to document.

Return value

A NodeList of HTMLElement objects with added properties and methods. If query was unsuccessful, the return value will be an empty NodeList.

DOM.css()

DOM.css() updates the styling of an HTMLElement. It also checks if any of the animatable properties were included, storing them on the object itself for animation tracking.

Syntax

node = DOM.css(node, styles)

Params

node

An extended HTMLElement object.

styles

An Object containing the desired styling. If the value of a property is not a String, nor one of opacity, zIndex, fontWeight, or strokeDashoffset, then the 'px' suffix will automatically be added. Style property names in javascript use camel case, eg backgroundColor, rather than background-color.

Return value

The same HTMLElement object passed in as the node parameter.

DOM.transform()

DOM.transform() updates the styles of the animatable properties. It combines the individual transform properties of an extended HTMLElement, and combines it to a single transform style value.

Syntax

node = DOM.transform(node)

Params

node

An HTMLElement object that has had the additional properties added from DOM.setup().

Return value

The same HTMLElement object passed in as the node parameter.

DOM.animate()

DOM.animate() is an alias for the @oframe/animate library, see inside for more documentation.

Syntax

animation = DOM.animate(node, duration, values)

Params

node

An HTMLElement object that has had the additional properties added from DOM.setup().

duration

A Number designating the duration of the animation in milliseconds.

values

An Object containing the final values of animated properties, along with other optional properties used by the @oframe/animate library.

Return value

An Animate object returned from the @oframe/animate library.