@joinbox/ui-tools
v1.4.0
Published
Provides repeatedly used tools for frontend and UI JS development
Downloads
102
Readme
Tools
Provides some simple and regularily used frontend helpers for JavaScript.
readAttribute
Description
Reads, transforms and validates an attribute from an HTML element.
Usage
import { readAttribute } from '@joinbox/ui-tools';
const element = document.querySelector('div.className');
readAttribute(element, 'attributeName', { transform: (value) => parseInt(value, 10) });
Arguments
Syntax: readAttribute(element, attribute, additionalArguments)
;
element
(HTMLElement
, required): Element to read attribute fromattribute
(string
, required): Name of the attribute to readadditionalArguments
(object
, optional): Object with propertiestransform
(function
, optional), takesvalue
as its only parameter and should return the transformed value. Defaults to(value) => value
. In order to check if a boolean attribute is present, use(value) => value !== null
.validate
(function
, optional), takesvalue
as its only parameter (that is the attribute's value after thetransform
function has been applied) and should returntrue
if the value is valid, elsefalse
. Defaults to(value) => value
.expectation
(string
, optional): expected value for the (transformed) value; will be printed in the error message ifvalidate
returnsfalse
.
Returns
*
: Transformed and validated value
Errors
Error
if validate
function returns false
debounce
Description
Creates a debounced function. Primarily needed for performant scroll (and window resize) operations.
Usage
import { debounce } from '@joinbox/ui-tools';
const callbackFunction = () => { console.log('update'); };
const debouncedFunction = debounce(callbackFunction, 200);
// Will only print a console.log *after* the window has *not* been resized for 200ms
window.addEventListener('resize', debouncedFunction);
Arguments
Syntax: debounce(callback, timeout)
callback
(function
, required): The function that will be executed after the debounce function has not been called fortimeout
ms.timeout
(number
, required, in ms). The inactivity timeout in ms after which the `callback`` function will be executed.
Returns
undefined
once
Description
Only executes a given function once for a given element; the execution state (executed or not) is
stored on an HTML element and only depends on the provided name
, not the function
. Needed
especially to implement Drupal behaviors.
Usage
import { once } from '@joinbox/ui-tools';
const executeOnlyOnce = () => { console.log('executing'); };
const element = document.querySelector('.executing-element');
once(element, 'example-executer', executeOnlyOnce);
// Will *not* execute executeOnlyOnce because it has been executed for this element before
once(element, 'example-executer', executeOnlyOnce);
// Will *not* execute because the name has been used before
once(element, 'example-executer', () => { console.log('nope') });
// Will execute as executeOnlyOnce has not been executed for this element before
once(document.querySelector('body'), 'example-executer', executeOnlyOnce);
Arguments
Syntax: once(element, name, function)
element
(HTMLElement
, required): The HTML element for which thefunction
should be executed oncename
(string
, required): Name under which the execution state function (executed or not) will be stored on the providedelement
function
(function
, required): Function that shall only be executed once
Returns
undefined
measureElement
Description
Gets dimensions of an element (by calling getBoundingClientRect()
) on load, window resize
and (optionally) intersection. Returns them as an object that updates its values whenever any of
the events described happens.
Usage
import { measureElement } from '@joinbox/ui-tools';
const element = document.querySelector('div.className');
const dimensions = measureElement({ element, updateOnIntersection: true });
Arguments
Syntax: measureElement({ element, updateOnIntersection })
;
element
(HTMLElement
, required): Element to measureupdateOnIntersection
(boolean
, optional): Iftrue
, dimensions will update whenever the element becomes visible. Defaults tofalse
.
Returns
object
: Object with same properties as DOMRect
with values that reflect the element's current dimensions.
Errors
No specific errors