wtc-utility-helpers

## Functions <dl> <dt><a href="#floatRandomBetween">floatRandomBetween(min, max)</a> ⇒ <code>number</code></dt> <dd>Generate a random float number max and min. <pre class="prettyprint source lang-javascript"><code>floatRandomBetween(-10, 20); // 12.513 </code></pre></dd> <dt><a href="#randomBetween">randomBetween(min, max)</a> ⇒ <code>number</code></dt> <dd>Generate a random integer number max and min. <pre class="prettyprint source lang-javascript"><code>randomBetween(-10, 20); // 12 </code></pre></dd> <dt><a href="#lerp">lerp(x, y, amount)</a> ⇒ <code>number</code></dt> <dd>Linearly interpolate between two values by a unit interval <pre class="prettyprint source lang-javascript"><code>lerp(100, 200, .5); // 150 </code></pre></dd> <dt><a href="#clampfunction">clampfunction(min, max, value)</a> ⇒ <code>number</code></dt> <dd>Clamps a value between an upper and lower bound. <pre class="prettyprint source lang-javascript"><code>clamp(0, 1, 2); // 1 </code></pre></dd> <dt><a href="#shuffleArray">shuffleArray(array, [modifyOriginal])</a> ⇒ <code>array</code></dt> <dd>Shuffle an array.</dd> <dt><a href="#fireCustomEvent">fireCustomEvent(name, data, [bubbles], [cancelable])</a></dt> <dd>Fire a custom event. <pre class="prettyprint source lang-javascript"><code>fireCustomEvent(name, data); </code></pre></dd> <dt><a href="#getElementPosition">getElementPosition(element, [toWorld])</a> ⇒ <code>Object</code></dt> <dd>Get the position of the element relative to document or optionally to the nearest offset parent. <pre class="prettyprint source lang-javascript"><code>getElementPosition(element); // returns something like { top: 100, left: 500 } </code></pre></dd> <dt><a href="#isChildOf">isChildOf(element, parentElement, [toWorld])</a> ⇒ <code>Boolean</code></dt> <dd>Determines whether the element is a child 0 ancestor of the other. If the toWorld flag is true (default), this will test recursively up the node hierarchy. This method can be used to determine whether a node is detached by something like: <pre class="prettyprint source"><code>attached = isChildOf(element, document.body); </code></pre></dd> <dt><a href="#getSiblings">getSiblings(e)</a> ⇒</dt> <dd>Get siblings from element <pre class="prettyprint source lang-javascript"><code>getSiblings(e); </code></pre></dd> <dt><a href="#getAncestors">getAncestors(e, [toBody], [ancestors])</a></dt> <dd>Retrieves all of the ancestors of an element, optionally to the document body (true by default). The list that is returned is the list of ancestors in order from the oldest to youngest.</dd> <dt><a href="#getSelectorForElement">getSelectorForElement(el)</a> ⇒ <code>String</code></dt> <dd>Returns the CSS selector for a provided element</dd> <dt><a href="#fixWidows">fixWidows()</a></dt> <dd>Fix widows replaces the last space in a sentence with a non-breaking space This function is a little dangerous at the moment so we should revisit it at some point in the future</dd> <dt><a href="#serializeArray">serializeArray(form)</a> ⇒ <code>Array</code></dt> <dd>Returns the form data as an array of name/value pairs.</dd> <dt><a href="#asyncImageLoadfunction">asyncImageLoadfunction(props)</a> ⇒ <code>Promise</code></dt> <dd>Asynchronous image loader. Returns a promise for an image allowing it to be used directly via <code>.then()</code> or as a part of an async workload via <code>await</code>. The then returns the provided image for use in the promise fulfullment. Usage: <pre class="prettyprint source language-javascript"><code>try { const img = asyncImageLoad({ src: '/assets/images/cool_image.png', alt: 'Cool Cats', crossOrigin: "anonymous" }) // do something cool with img } catch(err) { // Something happened and img didn't load } </code></pre> Without async/await: <pre class="prettyprint source lang-js"><code>const img = asyncImageLoad({ src: '/assets/images/cool_image.png', alt: 'Cool Cats', crossOrigin: "anonymous" }).then((img) => { // do something cool with img return img }).catch((err) => { // Something happened and img didn't load }) { </code></pre></dd> <dt><a href="#floatRandomBetween">floatRandomBetween(min, max)</a> ⇒ <code>number</code></dt> <dd>Generate a random float number max and min. <pre class="prettyprint source lang-javascript"><code>floatRandomBetween(-10, 20); // 12.513 </code></pre></dd> <dt><a href="#randomBetween">randomBetween(min, max)</a> ⇒ <code>number</code></dt> <dd>Generate a random integer number max and min. <pre class="prettyprint source lang-javascript"><code>randomBetween(-10, 20); // 12 </code></pre></dd> <dt><a href="#lerp">lerp(x, y, amount)</a> ⇒ <code>number</code></dt> <dd>Linearly interpolate between two values by a unit interval <pre class="prettyprint source lang-javascript"><code>lerp(100, 200, .5); // 150 </code></pre></dd> <dt><a href="#clampfunction">clampfunction(min, max, value)</a> ⇒ <code>number</code></dt> <dd>Clamps a value between an upper and lower bound. <pre class="prettyprint source lang-javascript"><code>clamp(0, 1, 2); // 1 </code></pre></dd> <dt><a href="#shuffleArray">shuffleArray(array, [modifyOriginal])</a> ⇒ <code>array</code></dt> <dd>Shuffle an array.</dd> <dt><a href="#fireCustomEvent">fireCustomEvent(name, data, [bubbles], [cancelable])</a></dt> <dd>Fire a custom event. <pre class="prettyprint source lang-javascript"><code>fireCustomEvent(name, data); </code></pre></dd> <dt><a href="#getElementPosition">getElementPosition(element, [toWorld])</a> ⇒ <code>Object</code></dt> <dd>Get the position of the element relative to document or optionally to the nearest offset parent. <pre class="prettyprint source lang-javascript"><code>getElementPosition(element); // returns something like { top: 100, left: 500 } </code></pre></dd> <dt><a href="#isChildOf">isChildOf(element, parentElement, [toWorld])</a> ⇒ <code>Boolean</code></dt> <dd>Determines whether the element is a child 0 ancestor of the other. If the toWorld flag is true (default), this will test recursively up the node hierarchy. This method can be used to determine whether a node is detached by something like: <pre class="prettyprint source"><code>attached = isChildOf(element, document.body); </code></pre></dd> <dt><a href="#getSiblings">getSiblings(e)</a> ⇒</dt> <dd>Get siblings from element <pre class="prettyprint source lang-javascript"><code>getSiblings(e); </code></pre></dd> <dt><a href="#getAncestors">getAncestors(e, [toBody], [ancestors])</a></dt> <dd>Retrieves all of the ancestors of an element, optionally to the document body (true by default). The list that is returned is the list of ancestors in order from the oldest to youngest.</dd> <dt><a href="#getSelectorForElement">getSelectorForElement(el)</a> ⇒ <code>String</code></dt> <dd>Returns the CSS selector for a provided element</dd> <dt><a href="#fixWidows">fixWidows()</a></dt> <dd>Fix widows replaces the last space in a sentence with a non-breaking space This function is a little dangerous at the moment so we should revisit it at some point in the future</dd> <dt><a href="#serializeArray">serializeArray(form)</a> ⇒ <code>Array</code></dt> <dd>Returns the form data as an array of name/value pairs.</dd> <dt><a href="#asyncImageLoadfunction">asyncImageLoadfunction(props)</a> ⇒ <code>Promise</code></dt> <dd>Asynchronous image loader. Returns a promise for an image allowing it to be used directly via <code>.then()</code> or as a part of an async workload via <code>await</code>. The then returns the provided image for use in the promise fulfullment. Usage: <pre class="prettyprint source language-javascript"><code>try { const img = asyncImageLoad({ src: '/assets/images/cool_image.png', alt: 'Cool Cats', crossOrigin: "anonymous" }) // do something cool with img } catch(err) { // Something happened and img didn't load } </code></pre> Without async/await: <pre class="prettyprint source lang-js"><code>const img = asyncImageLoad({ src: '/assets/images/cool_image.png', alt: 'Cool Cats', crossOrigin: "anonymous" }).then((img) => { // do something cool with img return img }).catch((err) => { // Something happened and img didn't load }) { </code></pre></dd> </dl> <a name="floatRandomBetween"></a> ## floatRandomBetween(min, max) ⇒ <code>number</code> Generate a random float number max and min. <pre class="prettyprint source lang-javascript"><code>floatRandomBetween(-10, 20); // 12.513 </code></pre> **Kind**: global function **Returns**: <code>number</code> - Random number. | Param | Type | Description | | --- | --- | --- | | min | <code>number</code> | Minimum value. | | max | <code>number</code> | Maximum value. | <a name="randomBetween"></a> ## randomBetween(min, max) ⇒ <code>number</code> Generate a random integer number max and min. <pre class="prettyprint source lang-javascript"><code>randomBetween(-10, 20); // 12 </code></pre> **Kind**: global function **Returns**: <code>number</code> - Random number. | Param | Type | Description | | --- | --- | --- | | min | <code>number</code> | Minimum value. | | max | <code>number</code> | Maximum value. | <a name="lerp"></a> ## lerp(x, y, amount) ⇒ <code>number</code> Linearly interpolate between two values by a unit interval <pre class="prettyprint source lang-javascript"><code>lerp(100, 200, .5); // 150 </code></pre> **Kind**: global function **Returns**: <code>number</code> - The interpolated value | Param | Type | Description | | --- | --- | --- | | x | <code>number</code> | The lower value | | y | <code>number</code> | The upper value | | amount | <code>number</code> | the amount to interpolate. The expected value is a unit interval (a float between 0 and 1), but this will work with higher and lower values as well. | <a name="clampfunction"></a> ## clampfunction(min, max, value) ⇒ <code>number</code> Clamps a value between an upper and lower bound. <pre class="prettyprint source lang-javascript"><code>clamp(0, 1, 2); // 1 </code></pre> **Kind**: global function **Returns**: <code>number</code> - A number in the range [min, max] | Param | Type | Description | | --- | --- | --- | | min | <code>number</code> | The lower bound | | max | <code>number</code> | The upper bound | | value | <code>number</code> | The value to clamp. | <a name="shuffleArray"></a> ## shuffleArray(array, [modifyOriginal]) ⇒ <code>array</code> Shuffle an array. **Kind**: global function **Returns**: <code>array</code> - Shuffled array. | Param | Type | Description | | --- | --- | --- | | array | <code>Array</code> | Arrray to be shuffled. | | [modifyOriginal] | <code>Boolean</code> | A boolean indicating whether the original array should be modified or whether a copy should be created. (default True) | <a name="fireCustomEvent"></a> ## fireCustomEvent(name, data, [bubbles], [cancelable]) Fire a custom event. <pre class="prettyprint source lang-javascript"><code>fireCustomEvent(name, data); </code></pre> **Kind**: global function | Param | Type | Description | | --- | --- | --- | | name | <code>string</code> | Name of the event. | | data | <code>object</code> | Object to be passed to the event. | | [bubbles] | <code>Boolean</code> | Indicates whether the event bubbles (default True) | | [cancelable] | <code>Boolean</code> | Indicates whether the event is cancellable default True) | <a name="getElementPosition"></a> ## getElementPosition(element, [toWorld]) ⇒ <code>Object</code> Get the position of the element relative to document or optionally to the nearest offset parent. <pre class="prettyprint source lang-javascript"><code>getElementPosition(element); // returns something like { top: 100, left: 500 } </code></pre> **Kind**: global function **Returns**: <code>Object</code> - the element coordinates. | Param | Type | Description | | --- | --- | --- | | element | <code>DOMNode</code> | Element. | | [toWorld] | <code>Boolean</code> | indicates whether the calculation of the element offset should be to the page or to the offset parent. (default True) | <a name="isChildOf"></a> ## isChildOf(element, parentElement, [toWorld]) ⇒ <code>Boolean</code> Determines whether the element is a child 0 ancestor of the other. If the toWorld flag is true (default), this will test recursively up the node hierarchy. This method can be used to determine whether a node is detached by something like: <pre class="prettyprint source"><code>attached = isChildOf(element, document.body); </code></pre> **Kind**: global function **Returns**: <code>Boolean</code> - true is the parentElement is parent (or ancestor) to Element | Param | Type | Description | | --- | --- | --- | | element | <code>DomNode</code> | The element to test with | | parentElement | <code>DomNode</code> | The parent element to test against | | [toWorld] | <code>Boolean</code> | Whether to test this up the DOM hierarchy | <a name="getSiblings"></a> ## getSiblings(e) ⇒ Get siblings from element <pre class="prettyprint source lang-javascript"><code>getSiblings(e); </code></pre> **Kind**: global function **Returns**: Returns a list with the element's siblings. | Param | Type | Description | | --- | --- | --- | | e | <code>DOMElement</code> | Element | <a name="getAncestors"></a> ## getAncestors(e, [toBody], [ancestors]) Retrieves all of the ancestors of an element, optionally to the document body (true by default). The list that is returned is the list of ancestors in order from the oldest to youngest. **Kind**: global function | Param | Type | Description | | --- | --- | --- | | e | <code>DOMElement</code> | The element to retrieve the ancestors for | | [toBody] | <code>boolean</code> | whether to only test to the body (default True) | | [ancestors] | <code>array</code> | the list of already existing elements to pass. This is nromally only used internally | <a name="getSelectorForElement"></a> ## getSelectorForElement(el) ⇒ <code>String</code> Returns the CSS selector for a provided element **Kind**: global function **Returns**: <code>String</code> - The CSS selector the describes exactly where to find the element | Param | Type | Description | | --- | --- | --- | | el | <code>DOMElement</code> | The DOM node to find a selector for | <a name="fixWidows"></a> ## fixWidows() Fix widows replaces the last space in a sentence with a non-breaking space This function is a little dangerous at the moment so we should revisit it at some point in the future **Kind**: global function <a name="serializeArray"></a> ## serializeArray(form) ⇒ <code>Array</code> Returns the form data as an array of name/value pairs. **Kind**: global function **Returns**: <code>Array</code> - Serialized data | Param | Type | Description | | --- | --- | --- | | form | <code>DOMElement</code> | The <form> DOM node | <a name="asyncImageLoadfunction"></a> ## asyncImageLoadfunction(props) ⇒ <code>Promise</code> Asynchronous image loader. Returns a promise for an image allowing it to be used directly via <code>.then()</code> or as a part of an async workload via <code>await</code>. The then returns the provided image for use in the promise fulfullment. Usage: <pre class="prettyprint source lang-js"><code>try { const img = asyncImageLoad({ src: '/assets/images/cool_image.png', alt: 'Cool Cats', crossOrigin: "anonymous" }) // do something cool with img } catch(err) { // Something happened and img didn't load } </code></pre> Without async/await: <pre class="prettyprint source lang-js"><code>const img = asyncImageLoad({ src: '/assets/images/cool_image.png', alt: 'Cool Cats', crossOrigin: "anonymous" }).then((img) => { // do something cool with img return img }).catch((err) => { // Something happened and img didn't load }) { </code></pre> **Kind**: global function **Returns**: <code>Promise</code> - A promise | Param | Type | Description | | --- | --- | --- | | props | <code>Object</code> | Image properties | | props.src | <code>String</code> | The image SRC | <a name="floatRandomBetween"></a> ## floatRandomBetween(min, max) ⇒ <code>number</code> Generate a random float number max and min. <pre class="prettyprint source lang-javascript"><code>floatRandomBetween(-10, 20); // 12.513 </code></pre> **Kind**: global function **Returns**: <code>number</code> - Random number. | Param | Type | Description | | --- | --- | --- | | min | <code>number</code> | Minimum value. | | max | <code>number</code> | Maximum value. | <a name="randomBetween"></a> ## randomBetween(min, max) ⇒ <code>number</code> Generate a random integer number max and min. <pre class="prettyprint source lang-javascript"><code>randomBetween(-10, 20); // 12 </code></pre> **Kind**: global function **Returns**: <code>number</code> - Random number. | Param | Type | Description | | --- | --- | --- | | min | <code>number</code> | Minimum value. | | max | <code>number</code> | Maximum value. | <a name="lerp"></a> ## lerp(x, y, amount) ⇒ <code>number</code> Linearly interpolate between two values by a unit interval <pre class="prettyprint source lang-javascript"><code>lerp(100, 200, .5); // 150 </code></pre> **Kind**: global function **Returns**: <code>number</code> - The interpolated value | Param | Type | Description | | --- | --- | --- | | x | <code>number</code> | The lower value | | y | <code>number</code> | The upper value | | amount | <code>number</code> | the amount to interpolate. The expected value is a unit interval (a float between 0 and 1), but this will work with higher and lower values as well. | <a name="clampfunction"></a> ## clampfunction(min, max, value) ⇒ <code>number</code> Clamps a value between an upper and lower bound. <pre class="prettyprint source lang-javascript"><code>clamp(0, 1, 2); // 1 </code></pre> **Kind**: global function **Returns**: <code>number</code> - A number in the range [min, max] | Param | Type | Description | | --- | --- | --- | | min | <code>number</code> | The lower bound | | max | <code>number</code> | The upper bound | | value | <code>number</code> | The value to clamp. | <a name="shuffleArray"></a> ## shuffleArray(array, [modifyOriginal]) ⇒ <code>array</code> Shuffle an array. **Kind**: global function **Returns**: <code>array</code> - Shuffled array. | Param | Type | Description | | --- | --- | --- | | array | <code>Array</code> | Arrray to be shuffled. | | [modifyOriginal] | <code>Boolean</code> | A boolean indicating whether the original array should be modified or whether a copy should be created. (default True) | <a name="fireCustomEvent"></a> ## fireCustomEvent(name, data, [bubbles], [cancelable]) Fire a custom event. <pre class="prettyprint source lang-javascript"><code>fireCustomEvent(name, data); </code></pre> **Kind**: global function | Param | Type | Description | | --- | --- | --- | | name | <code>string</code> | Name of the event. | | data | <code>object</code> | Object to be passed to the event. | | [bubbles] | <code>Boolean</code> | Indicates whether the event bubbles (default True) | | [cancelable] | <code>Boolean</code> | Indicates whether the event is cancellable default True) | <a name="getElementPosition"></a> ## getElementPosition(element, [toWorld]) ⇒ <code>Object</code> Get the position of the element relative to document or optionally to the nearest offset parent. <pre class="prettyprint source lang-javascript"><code>getElementPosition(element); // returns something like { top: 100, left: 500 } </code></pre> **Kind**: global function **Returns**: <code>Object</code> - the element coordinates. | Param | Type | Description | | --- | --- | --- | | element | <code>DOMNode</code> | Element. | | [toWorld] | <code>Boolean</code> | indicates whether the calculation of the element offset should be to the page or to the offset parent. (default True) | <a name="isChildOf"></a> ## isChildOf(element, parentElement, [toWorld]) ⇒ <code>Boolean</code> Determines whether the element is a child 0 ancestor of the other. If the toWorld flag is true (default), this will test recursively up the node hierarchy. This method can be used to determine whether a node is detached by something like: <pre class="prettyprint source"><code>attached = isChildOf(element, document.body); </code></pre> **Kind**: global function **Returns**: <code>Boolean</code> - true is the parentElement is parent (or ancestor) to Element | Param | Type | Description | | --- | --- | --- | | element | <code>DomNode</code> | The element to test with | | parentElement | <code>DomNode</code> | The parent element to test against | | [toWorld] | <code>Boolean</code> | Whether to test this up the DOM hierarchy | <a name="getSiblings"></a> ## getSiblings(e) ⇒ Get siblings from element <pre class="prettyprint source lang-javascript"><code>getSiblings(e); </code></pre> **Kind**: global function **Returns**: Returns a list with the element's siblings. | Param | Type | Description | | --- | --- | --- | | e | <code>DOMElement</code> | Element | <a name="getAncestors"></a> ## getAncestors(e, [toBody], [ancestors]) Retrieves all of the ancestors of an element, optionally to the document body (true by default). The list that is returned is the list of ancestors in order from the oldest to youngest. **Kind**: global function | Param | Type | Description | | --- | --- | --- | | e | <code>DOMElement</code> | The element to retrieve the ancestors for | | [toBody] | <code>boolean</code> | whether to only test to the body (default True) | | [ancestors] | <code>array</code> | the list of already existing elements to pass. This is nromally only used internally | <a name="getSelectorForElement"></a> ## getSelectorForElement(el) ⇒ <code>String</code> Returns the CSS selector for a provided element **Kind**: global function **Returns**: <code>String</code> - The CSS selector the describes exactly where to find the element | Param | Type | Description | | --- | --- | --- | | el | <code>DOMElement</code> | The DOM node to find a selector for | <a name="fixWidows"></a> ## fixWidows() Fix widows replaces the last space in a sentence with a non-breaking space This function is a little dangerous at the moment so we should revisit it at some point in the future **Kind**: global function <a name="serializeArray"></a> ## serializeArray(form) ⇒ <code>Array</code> Returns the form data as an array of name/value pairs. **Kind**: global function **Returns**: <code>Array</code> - Serialized data | Param | Type | Description | | --- | --- | --- | | form | <code>DOMElement</code> | The <form> DOM node | <a name="asyncImageLoadfunction"></a> ## asyncImageLoadfunction(props) ⇒ <code>Promise</code> Asynchronous image loader. Returns a promise for an image allowing it to be used directly via <code>.then()</code> or as a part of an async workload via <code>await</code>. The then returns the provided image for use in the promise fulfullment. Usage: <pre class="prettyprint source lang-js"><code>try { const img = asyncImageLoad({ src: '/assets/images/cool_image.png', alt: 'Cool Cats', crossOrigin: "anonymous" }) // do something cool with img } catch(err) { // Something happened and img didn't load } </code></pre> Without async/await: <pre class="prettyprint source lang-js"><code>const img = asyncImageLoad({ src: '/assets/images/cool_image.png', alt: 'Cool Cats', crossOrigin: "anonymous" }).then((img) => { // do something cool with img return img }).catch((err) => { // Something happened and img didn't load }) { </code></pre> **Kind**: global function **Returns**: <code>Promise</code> - A promise | Param | Type | Description | | --- | --- | --- | | props | <code>Object</code> | Image properties | | props.src | <code>String</code> | The image SRC |