Menu

Utils

Core utility functions used throughout Formstone.

Methods

Methods are publicly available as static methods on the Utils class.

Name Description
.addClass() Adds class(es) to target(s)
.camelCase() Converts a string to camelCase
.element() Creates a new element
.extend() Deep or shallow merge of objects
.falsey() Checks if a value is "falsey"
.getAttr() Returns an attribute value from an element
.hasAttr() Checks if an element has an attribute
.hasClass() Checks if an element has a class
.isFn() Checks if a value is a function
.isObj() Checks if a value is an object
.isU() Checks if a value is undefined
.iterable() Normalizes an item into an array for iteration
.iterate() Iterates over items
.off() Removes event listener(s)
.on() Adds event listener(s)
.once() Adds a one-time event listener
.ready() Executes callback when DOM is ready
.removeAttr() Removes attribute(s)
.removeClass() Removes class(es) from target(s)
.restoreAttr() Restores an attribute's value
.select() Selects elements via query selector
.setAttr() Sets attribute(s)
.siblings() Returns siblings of an element
.trigger() Triggers a custom event
.type() Returns the native typeof of an item
.updateAttr() Preserves and updates an attribute

Core

.ready()

Executes a callback when the DOM is ready, or immediately if already loaded.

Parameters

Name Type Description
cb function Callback function to execute

Examples

Utils.ready(() => {
  console.log('DOM is ready');
});

Checks

.type()

Returns the JavaScript type of an item.

Parameters

Name Type Description
item any The item to check

Returns

Type Description
string The type of the item ('string', 'number', 'boolean', 'object', 'function', 'undefined', 'symbol', 'bigint')

.falsey()

Checks if a value is falsey (undefined, false, or null).

Parameters

Name Type Description
v any The value to check

Returns

Type Description
boolean True if the value is undefined, false, or null

.isFn()

Checks if a value is a function.

Parameters

Name Type Description
v any Value to check

Returns

Type Description
boolean True if a function

.isObj()

Checks if a value is an object.

Parameters

Name Type Description
v any Value to check

Returns

Type Description
boolean True if an object

.isU()

Checks if a value is undefined.

Parameters

Name Type Description
v any Value to check

Returns

Type Description
boolean True if undefined

Objects

.extend()

Extends objects by merging properties from one or more source objects.

Parameters

Name Type Description
deep boolean (optional) If first argument is boolean, enables deep merge
...args object Objects to merge

Returns

Type Description
object The extended object

Examples

// Shallow merge
Utils.extend({a: 1}, {b: 2}); // {a: 1, b: 2}

// Deep merge
Utils.extend(true, {a: {x: 1}}, {a: {y: 2}}); // {a: {x: 1, y: 2}}

Selection

.select()

Selects all elements matching a CSS selector.

Parameters

Name Type Description
selector string CSS selector string
context element|Document (optional) Context element or document to search within (defaults to document)

Returns

Type Description
NodeList NodeList of matching elements

Examples

let buttons = Utils.select('.btn');
let inputs = Utils.select('input', form);

.element()

Creates a new DOM element.

Parameters

Name Type Description
tag string The HTML tag name to create

Returns

Type Description
element The created element

Examples

let div = Utils.element('div');

.siblings()

Gets all sibling elements of a node.

Parameters

Name Type Description
node element The element to get siblings for

Returns

Type Description
array Array of sibling elements

Iteration

.iterate()

Iterates over a target and executes a callback for each item.

Parameters

Name Type Description
target element|NodeList|array|any The target to iterate over
cb function Callback function to execute for each item

.iterable()

Converts a value to an iterable array.

Parameters

Name Type Description
target any The target to convert (Element, NodeList, Array, or any value)

Returns

Type Description
array Array of non-falsey items

Events

.on()

Adds event listener(s) to element(s).

Parameters

Name Type Description
target element|NodeList|array The target element(s)
event string The event name
cb function The event handler callback
options object|boolean (optional) Event listener options

Examples

Utils.on(button, 'click', handleClick);
Utils.on(Utils.select('.item'), 'mouseenter', handleHover);

.once()

Adds a one-time event listener to element(s).

Parameters

Name Type Description
target element|NodeList|array The target element(s)
event string The event name
cb function The event handler callback
options object|boolean (optional) Event listener options

.off()

Removes event listener(s) from element(s).

Parameters

Name Type Description
target element|NodeList|array The target element(s)
event string The event name
cb function The event handler callback to remove

.trigger()

Dispatches a custom event on element(s).

Parameters

Name Type Description
target element|NodeList|array The target element(s)
event string The event name
detail any (optional) Optional detail data to pass with the event

Examples

Utils.trigger(element, 'customEvent', {data: 'value'});

Classes

.addClass()

Adds class(es) to element(s).

Parameters

Name Type Description
target element|NodeList|array The target element(s)
...classes string Class names to add

Examples

Utils.addClass(element, 'active');
Utils.addClass(Utils.select('.item'), 'highlight', 'selected');

.removeClass()

Removes class(es) from element(s).

Parameters

Name Type Description
target element|NodeList|array The target element(s)
...classes string Class names to remove

Examples

Utils.removeClass(element, 'active');
Utils.removeClass(Utils.select('.item'), 'highlight', 'selected');

.hasClass()

Checks if an element has a class.

Parameters

Name Type Description
target element The target element
c string The class name to check

Returns

Type Description
boolean True if the element has the class

Attributes

.setAttr()

Sets attribute(s) on element(s).

Parameters

Name Type Description
target element|NodeList|array The target element(s)
attr string|object Attribute name or object of attribute key-value pairs
value string (optional) Attribute value (when attr is a string). If falsey, removes the attribute

Examples

Utils.setAttr(element, 'data-id', '123');
Utils.setAttr(element, {id: 'myId', 'data-type': 'primary'});

.getAttr()

Gets an attribute value from an element.

Parameters

Name Type Description
target element The target element
attr string The attribute name

Returns

Type Description
string|null The attribute value or null if not present

.hasAttr()

Checks if an element has an attribute.

Parameters

Name Type Description
target element The target element
attr string The attribute name

Returns

Type Description
boolean True if the element has the attribute

.removeAttr()

Removes attribute(s) from element(s).

Parameters

Name Type Description
target element|NodeList|array The target element(s)
attr string|array Attribute name(s) to remove

Examples

Utils.removeAttr(element, 'disabled');
Utils.removeAttr(element, ['disabled', 'hidden']);

.updateAttr()

Updates an attribute value and stores the original in a data attribute.

Parameters

Name Type Description
els element|NodeList|array The target element(s)
attr string The attribute name to update
value string The new attribute value
handle string A handle used to namespace the backup data attribute

.restoreAttr()

Restores an attribute to its original value from a data attribute.

Parameters

Name Type Description
els element|NodeList|array The target element(s)
attr string The attribute name to restore
handle string The handle used when the attribute was updated

Strings

.camelCase()

Converts a hyphenated or space-separated string to camelCase.

Parameters

Name Type Description
string string The string to convert

Returns

Type Description
string The camelCased string

Examples

Utils.camelCase('my-data-attr'); // 'myDataAttr'
Utils.camelCase('background color'); // 'backgroundColor'