DMS Utility Library
arrayHelper
A module that provides common array helper functions.
-
arrayHelper
-
~sliceRandom(array, [outputArrayLength]) ⇒
Array
-
~flattenArrays(arrayOfArrays) ⇒
Array
-
~filterTallyByThreshold(tally, threshold, [noWarning]) ⇒
Array
-
~isItemInArray(array, item) ⇒
boolean
-
~findItemInArray(array, item) ⇒
string
-
~isArrayItemInArray(array1, array2) ⇒
boolean
-
~findArrayItemInArray(array1, array2) ⇒
string
-
~sliceRandom(array, [outputArrayLength]) ⇒
Array
arrayHelper~sliceRandom(array, [outputArrayLength]) ⇒ Returns a new array containing randomly extracted elements. The passed array is not modified. The returned array contains shallow copies of the passed array.
Kind: inner method of arrayHelper
Returns: Array
- A new array containing the randomly extracted elements.
Param | Type | Description |
---|---|---|
array | Array |
The array to extract elements from. |
[outputArrayLength] | number |
The number of elements to extract. Negative values will be subtracted from the length of the passed array |
Example
// Randomly select 2 names, then 3 names using a negative length.
const names = ['anne', 'bob', 'chip', 'deborah']
const randomCouple = unipro.sliceRandom(names, 2)
const randomTriplet = unipro.sliceRandom(names, -1)
Array
arrayHelper~flattenArrays(arrayOfArrays) ⇒ Flattens an array of arrays into a single array.
Kind: inner method of arrayHelper
Returns: Array
- A new array containing all sub-array elements.
Param | Type | Description |
---|---|---|
arrayOfArrays | Array.<Array> |
The array of arrays to flatten. |
Example
const nestedArray = [1, 2, [3, 4]]
const flatArray = unipro.flattenArrays(nestedArray)
// [1, 2, 3, 4]
Array
arrayHelper~filterTallyByThreshold(tally, threshold, [noWarning]) ⇒ Filters tally items by the threshold of the number of counts on each item. Items below the threshold will not be returned.
Kind: inner method of arrayHelper
Returns: Array
- filteredTally containing all items that are above the threshold.
Param | Type | Description |
---|---|---|
tally | Array |
an array of objects from the tally. |
threshold | number |
the number of counts on an individual item to be filtered on. |
[noWarning] | Array |
custom warning message to be thrown if no items match the threshold. |
boolean
arrayHelper~isItemInArray(array, item) ⇒ Tests whether an array includes a string, case insensitive and trims whitespace.
Kind: inner method of arrayHelper
Returns: boolean
- true if the string is found, otherwise false.
Param | Type | Description |
---|---|---|
array | Array.<string> |
An array of strings to search. |
item | string |
A string to search for. |
string
arrayHelper~findItemInArray(array, item) ⇒ Finds a string within an array, case insensitive and trims whitespace.
Kind: inner method of arrayHelper
Returns: string
- The matching string from array, otherwise undefined.
Param | Type | Description |
---|---|---|
array | Array.<string> |
An array of strings to search. |
item | string |
A string to search for. |
boolean
arrayHelper~isArrayItemInArray(array1, array2) ⇒ Tests whether an array includes a string from another array, case insensitive and trims whitespace.
Kind: inner method of arrayHelper
Returns: boolean
- true if a string is found, otherwise false.
Param | Type | Description |
---|---|---|
array1 | Array.<string> |
An array of strings to search within. |
array2 | Array.<string> |
An array of strings to search for. |
string
arrayHelper~findArrayItemInArray(array1, array2) ⇒ Finds a matching string within 2 arrays, case insensitive and trims whitespace.
Kind: inner method of arrayHelper
Returns: string
- The matching string from array 1, otherwise undefined.
Param | Type | Description |
---|---|---|
array1 | Array.<string> |
An array of strings to search within. |
array2 | Array.<string> |
An array of strings to search for. |
cookieHelper
A module that provides a cookie helper to encode and store objects and queues, on the appropriate domain.
dateHelper
A module that provides date validation functions.
deviceHelper
A module that provides common device check helpers.
-
deviceHelper
-
~isMobileDevice() ⇒
boolean
-
~isTabletDevice() ⇒
boolean
-
~isDesktopDevice() ⇒
boolean
-
~isMobileOrTabletDevice() ⇒
boolean
-
~isTabletOrDesktopDevice() ⇒
boolean
-
~isMobileDevice() ⇒
boolean
deviceHelper~isMobileDevice() ⇒ Determines whether the visitor's device type is mobile.
Kind: inner method of deviceHelper
Returns: boolean
- true if mobile, false if not.
Example
// Run some conditional code on mobile devices
if (isMobileDevice()) {
...
}
boolean
deviceHelper~isTabletDevice() ⇒ Determines whether the visitor's device type is tablet.
Kind: inner method of deviceHelper
Returns: boolean
- true if tablet, false if not.
boolean
deviceHelper~isDesktopDevice() ⇒ Determines whether the visitor's device type is desktop.
Kind: inner method of deviceHelper
Returns: boolean
- true if desktop, false if not.
boolean
deviceHelper~isMobileOrTabletDevice() ⇒ Determines whether the visitor's device type is mobile or tablet.
Kind: inner method of deviceHelper
Returns: boolean
- true if mobile or tablet, false if not.
boolean
deviceHelper~isTabletOrDesktopDevice() ⇒ Determines whether the visitor's device type is tablet or desktop.
Kind: inner method of deviceHelper
Returns: boolean
- true if tablet or desktop, false if not.
elementHelper
A module that provides UI helper functions for interacting with the DOM.
Promise
elementHelper~waitForScrollIntoView($element, [offset], [wait], [throttleOptions]) ⇒ Waits for an element to be scrolled into view.
Kind: inner method of elementHelper
Returns: Promise
- A Promise that resolves with $element.
The returned Promise has an additional cancel property that can be called to stop the scroll listener early.
Param | Type | Default | Description |
---|---|---|---|
$element | any |
The element to check. | |
[offset] | number |
0 |
The amount of the element to be considered visible. This must be an integer number of pixels. |
[wait] | number |
100 |
The frequency to check in milliseconds. |
[throttleOptions] | object |
Lodash throttle options (leading/trailing). |
Example
const $element = $('.carousel')
return unipro.waitForScrollIntoView($element)
Promise
elementHelper~waitForElementVisible($target, toggle, [isVisibleCallback]) ⇒ Waits for an element to be visible on the page.
Kind: inner method of elementHelper
Returns: Promise
- A Promise that resolves with $target.
Param | Type | Description |
---|---|---|
$target | any |
The element to check. |
toggle | any |
The element or jQuery object that can toggle visibility, e.g. a menu icon. |
[isVisibleCallback] | any |
An optional callback to override the check for visibility. |
errorHelper
A module that provides helper functions for errors and warnings.
errorHelper~onError(e)
Kind: inner method of errorHelper
Param | Type |
---|---|
e | Error |
errorHelper~onErrorStop(e)
Kind: inner method of errorHelper
Param | Type |
---|---|
e | Error |
void
errorHelper~Warning(message) ⇒ Instantiates an Error object with a custom "warn" property, for reporting expected error conditions as warnings.
Kind: inner method of errorHelper
Param | Type | Description |
---|---|---|
message | string |
The message describing the warning. |
hooksHelper
A module that provides helper functions for the Qubit activation and removal events.
hooksHelper~onRemove(callback, [namespace])
Attaches a clean function to be called on removal of the experience.
Kind: inner method of hooksHelper
Param | Type | Description |
---|---|---|
callback | callback |
the clean up function to call on removal of the experience. |
[namespace] | string |
namespace so that callbacks can be grouped for removal. |
hooksHelper~onActivation(callback, [removeCallback], [namespace])
Attaches a tracking function to be called on activation of the experience.
Kind: inner method of hooksHelper
Param | Type | Description |
---|---|---|
callback | callback |
the tracking function to call on activation of the experience. |
[removeCallback] | callback |
the clean up function to call on removal of the experience. |
[namespace] | string |
namespace so that callbacks can be grouped for removal. |
HTMLElement
hooksHelper~removeCliStyle() ⇒ Removes the style tag if the experience is running under the qubit CLI.
Kind: inner method of hooksHelper
Returns: HTMLElement
- The removed style tag.
hooksHelper~runOnRemove([namespace])
Manually runs any clean up functions added by onRemove.
Kind: inner method of hooksHelper
Param | Type | Description |
---|---|---|
[namespace] | string |
only call a subset of the callbacks identified by the namespace. |
hooksHelper~runOnActivation([namespace])
Manually runs any tracking functions added by onActivation.
Kind: inner method of hooksHelper
Param | Type | Description |
---|---|---|
[namespace] | string |
only call a subset of the callbacks identified by the namespace. |
jQueryHelper
A module that provides helper functions for jQuery traversal, manipulation and AJAX requests.
-
jQueryHelper
-
~ajax(url, [settings]) ⇒
Promise
-
~get(url, [data], [dataType]) ⇒
Promise
-
~post(url, [data], [dataType]) ⇒
Promise
-
~insertElement($element, target, insertionMethod) ⇒
any
-
~ajax(url, [settings]) ⇒
Promise
jQueryHelper~ajax(url, [settings]) ⇒ Perform an asynchronous HTTP (Ajax) request.
Kind: inner method of jQueryHelper
Returns: Promise
- A Promise that resolves with the data.
Param | Type | Description |
---|---|---|
url | string |
A string containing the URL to which the request is sent. |
[settings] | any |
A set of key/value pairs that configure the Ajax request |
Promise
jQueryHelper~get(url, [data], [dataType]) ⇒ Load data from the server using a HTTP GET request.
Kind: inner method of jQueryHelper
Returns: Promise
- A Promise that resolves with the data.
Param | Type | Description |
---|---|---|
url | string |
A string containing the URL to which the request is sent. |
[data] | any |
A plain object or string that is sent to the server with the request. |
[dataType] | string |
The type of data expected from the server. Default: Intelligent Guess (xml, json, script, text, html). |
Promise
jQueryHelper~post(url, [data], [dataType]) ⇒ Load data from the server using a HTTP POST request.
Kind: inner method of jQueryHelper
Returns: Promise
- A Promise that resolves with the data.
Param | Type | Description |
---|---|---|
url | string |
A string containing the URL to which the request is sent. |
[data] | any |
A plain object or string that is sent to the server with the request. |
[dataType] | string |
The type of data expected from the server. Default: Intelligent Guess (xml, json, script, text, html). |
any
jQueryHelper~insertElement($element, target, insertionMethod) ⇒ Insert every element in the set of matched elements before or after the target.
Kind: inner method of jQueryHelper
Returns: any
- The inserted element(s).
Throws:
- Throws an error if the insertionMethod is not valid.
Param | Type | Description |
---|---|---|
$element | any |
The element(s) to insert. |
target | any |
A selector, element, array of elements, HTML string, or jQuery object; the matched set of elements will be inserted before the element(s) specified by this parameter. |
insertionMethod | string |
insertBefore, insertAfter, prependTo or appendTo. |
moneyHelper
A module that provides helper functions for working with currencies.
string
moneyHelper~formatPrice(price, locale, currency, [trim]) ⇒ Converts a number to a currency string for the specified locale and currency.
Kind: inner method of moneyHelper
Returns: string
- The price in the specified language and currency.
Throws:
- Invalid number format, if the price is not a number.
Param | Type | Description |
---|---|---|
price | number |
The price to convert to a currency. |
locale | string |
The language that the price should be converted to. |
currency | string |
The currency that the price should be converted to. |
[trim] | boolean |
If true displays whole prices without decimal places (£1.00 => £1). |
objectHelper
A module that provides helper functions for working with objects.
Object
objectHelper~deepCopy(object) ⇒ Creates a deep copy of an object.
Kind: inner method of objectHelper
Returns: Object
- a deep copied object.
Param | Type | Description |
---|---|---|
object | Object |
the object to be copied. |
getOptions
A module that provides custom logging to assist with filtering the console log.
pollerHelper
A module that wraps the Qubit poller in a Promise and uses named properties for the poller conditions.
Object
pollerHelper~pollerPromise(pollFor, [timeoutMessage]) ⇒ Provides a Promise wrapper around the jQuery version of the Qubit poller (v1.6).
Kind: inner method of pollerHelper
Returns: Object
- A Promise that resolves with a object containing the property names and
the results from the poller conditions. The Promise has an additional cancel property to stop the poller.
Param | Type | Description |
---|---|---|
pollFor | Object |
Object containing the property names and poller conditions (selector/variable/function). |
[timeoutMessage] | string |
Message to report as a Warning if the poller conditions are not met. |
Example
// To poll for a selector, variable and function
const pollFor = { $header: 'h1', dataLayer: 'window.dataLayer', someCondition: functionThatChecksSomething }
unipro.poller(pollFor, 'Could not find heading')
.then(({ $header, dataLayer}) => doSomethingWithHeading($heading))
.catch(onError)
Example
// Simple poller with an immediate call to cancel
const logoPoller = unipro.poller({ $logo: 'img.logo'})
logoPoller.cancel()
requireHelper
A module that wraps the Qubit AMD require function for commonly used packages.
-
requireHelper
-
~requireCountdownPackage() ⇒
Promise
-
~requireSlickPackage() ⇒
Promise
-
~requireCountdownPackage() ⇒
Promise
requireHelper~requireCountdownPackage() ⇒ Gets the Countdown package for Qubit.
Kind: inner method of requireHelper
Returns: Promise
- Promise that resolves with the Countdown object.
Promise
requireHelper~requireSlickPackage() ⇒ Gets the custom Slick package for Qubit.
Kind: inner method of requireHelper
Returns: Promise
- Promise that resolves with the Slick object.
segmentHelper
A module that wraps the Qubit getMembershipsAsync function with a poller.
Promise
segmentHelper~getSegments() ⇒ Gets the Qubit segments Ids that the visitor is a member of.
Kind: inner method of segmentHelper
Returns: Promise
- Promise that resolves with an array of strings containing the segment IDs.
storageHelper
A module that provides helper functions for local and session storage, with support for queues of objects.
-
storageHelper
-
~isSessionStorageAccessible() ⇒
boolean
-
~isLocalStorageAccessible() ⇒
boolean
-
~getQueueFromSessionStorage(storageKey) ⇒
Array
-
~getQueueFromLocalStorage(storageKey) ⇒
Array
-
~queueItemToSessionStorage(storageKey, value, max, [uniqueProperty]) ⇒
Array
-
~queueItemToLocalStorage(storageKey, value, max, [uniqueProperty]) ⇒
Array
-
~removeItemFromSessionStorage(storageKey, value, [uniqueProperty]) ⇒
Array
-
~removeItemFromLocalStorage(storageKey, value, [uniqueProperty]) ⇒
Array
-
~isSessionStorageAccessible() ⇒
boolean
storageHelper~isSessionStorageAccessible() ⇒ Determines whether session storage is accessible.
Kind: inner method of storageHelper
Returns: boolean
- true if storage is accessible, false if not.
Throws:
- Does not throw any exceptions.
boolean
storageHelper~isLocalStorageAccessible() ⇒ Determines whether local storage is accessible.
Kind: inner method of storageHelper
Returns: boolean
- true if storage is accessible, false if not.
Throws:
- Does not throw any exceptions.
Array
storageHelper~getQueueFromSessionStorage(storageKey) ⇒ Gets a queue of items that have been stored in session storage.
Kind: inner method of storageHelper
Returns: Array
- an array of the queued items, if no items have been queued an empty array is returned.
Param | Type | Description |
---|---|---|
storageKey | string |
key name for the queue to be returned. |
Example
// To get the last 10 unique products viewed.
const items = getQueueFromSessionStorage(`qb_${_ticket}-${options.meta.experienceId}`)
Array
storageHelper~getQueueFromLocalStorage(storageKey) ⇒ Gets a queue of items that have been stored in local storage.
Kind: inner method of storageHelper
Returns: Array
- an array of the queued items, if no items have been queued an empty array is returned.
Param | Type | Description |
---|---|---|
storageKey | string |
key name for the queue to be returned. |
Example
// To get the last 10 unique products viewed.
const products = getQueueFromLocalStorage(`qb_${_ticket}-${options.meta.experienceId}`)
Array
storageHelper~queueItemToSessionStorage(storageKey, value, max, [uniqueProperty]) ⇒ Adds an item to the beginning of a unique queue that is stored in session storage.
Kind: inner method of storageHelper
Returns: Array
- The updated array of queued items.
Param | Type | Description |
---|---|---|
storageKey | string |
key name for the queue to be stored. |
value | any |
The object or primitive type to be added to the queue. |
max | number |
Maximum number of items to store. Older items will be deleted once this value is met. |
[uniqueProperty] | string |
The object's property name to use for uniqueness within the queue. |
Example
// To store the last 10 unique products viewed.
queueItemToSessionStorage`qb_${_ticket}-${options.meta.experienceId}`, product, 10, 'productId')
Example
// To store the last 10 unique product IDs viewed.
queueItemToSessionStorage`qb_${_ticket}-${options.meta.experienceId}`, productId, 10)
Array
storageHelper~queueItemToLocalStorage(storageKey, value, max, [uniqueProperty]) ⇒ Adds an item to the beginning of a unique queue that is stored in local storage.
Kind: inner method of storageHelper
Returns: Array
- The updated array of queued items.
Param | Type | Description |
---|---|---|
storageKey | string |
key name for the queue to be stored. |
value | any |
The object or primitive type to be added to the queue. |
max | number |
Maximum number of items to store. Older items will be deleted once this value is met. |
[uniqueProperty] | string |
The object's property name to use for uniqueness within the queue. |
Example
// To store the last 10 unique products viewed.
queueItemToLocalStorage`qb_${_ticket}-${options.meta.experienceId}`, product, 10, 'productId')
Example
// To store the last 10 unique product IDs viewed.
queueItemToLocalStorage`qb_${_ticket}-${options.meta.experienceId}`, productId, 10)
Array
storageHelper~removeItemFromSessionStorage(storageKey, value, [uniqueProperty]) ⇒ Removes an item with a unique queue that is stored in session storage.
Kind: inner method of storageHelper
Returns: Array
- The updated array of queued items.
Param | Type | Description |
---|---|---|
storageKey | string |
key name for the queue that has been stored. |
value | any |
The object or primitive type to be removed from the queue. |
[uniqueProperty] | string |
The object's property name to use for uniqueness within the queue. |
Example
// To remove a unique product Id from storage.
removeItemFromSessionStorage(`qb_${_ticket}-${options.meta.experienceId}`, productId)
Example
// To remove a unique product from storage.
removeItemFromSessionStorage(`qb_${_ticket}-${options.meta.experienceId}`, product, 'productId')
Array
storageHelper~removeItemFromLocalStorage(storageKey, value, [uniqueProperty]) ⇒ Removes an item with a unique queue that is stored in local storage.
Kind: inner method of storageHelper
Returns: Array
- The updated array of queued items.
Param | Type | Description |
---|---|---|
storageKey | string |
key name for the queue that has been stored. |
value | any |
The object or primitive type to be removed from the queue. |
[uniqueProperty] | string |
The object's property name to use for uniqueness within the queue. |
Example
// To remove a unique product Id from storage.
removeItemFromSessionStorage(`qb_${_ticket}-${options.meta.experienceId}`, productId)
Example
// To remove a unique product from storage.
removeItemFromSessionStorage(`qb_${_ticket}-${options.meta.experienceId}`, product, 'productId')
stringHelper
A module that provides helper functions for strings and URIs.
-
stringHelper
-
~toTitleCase(string) ⇒
string
-
~toLowerTrim(string) ⇒
string
-
~toRelativeUrl(url) ⇒
string
-
~toAbsoluteUrl(url, [domain]) ⇒
string
-
~toTitleCase(string) ⇒
string
stringHelper~toTitleCase(string) ⇒ Capitalises first letter of each word in a space separated string
Kind: inner method of stringHelper
Returns: string
- Converted string.
Param | Type | Description |
---|---|---|
string | string |
String to transform. |
Example
'Converted String' = convertToTitleCase('converted string').
string
stringHelper~toLowerTrim(string) ⇒ Converts a string to lower case and trims whitespace
Kind: inner method of stringHelper
Returns: string
- Trimmed lower case string
Param | Type | Description |
---|---|---|
string | string |
The string to convert |
string
stringHelper~toRelativeUrl(url) ⇒ Converts an absolute (or protocol relative) URL to a relative URL
Kind: inner method of stringHelper
Returns: string
- The relative URL
Param | Type | Description |
---|---|---|
url | string |
The absolute URL to convert |
string
stringHelper~toAbsoluteUrl(url, [domain]) ⇒ Converts a relative (not protocol relative) URL to an absolute URL
Kind: inner method of stringHelper
Returns: string
- The absolute URL
Param | Type | Description |
---|---|---|
url | string |
The relative URL to convert |
[domain] | string |
The optional domain to use, otherwise use current domain |
tallyHelper
A module that provides a helper for the Qubit tally, including error handling and encoding/decoding of keys and data.
uvHelper
A module that provides helper functions for Qubit API events including page, product, basket, and transactions.
-
uvHelper
-
~waitForPage() ⇒
Promise
-
~waitForProductDetails() ⇒
Promise
-
~waitForProductListing() ⇒
Promise
-
~waitForBasketSummary([allowEmpty]) ⇒
Promise
-
~waitForTransactionSummary([allowEmpty]) ⇒
Promise
-
~waitForBasketItems([allowEmpty]) ⇒
Promise
-
~waitForTransactionItems([allowEmpty]) ⇒
Promise
-
~waitForUser() ⇒
Promise
-
~waitForPage() ⇒
Promise
uvHelper~waitForPage() ⇒ Waits for an ecView, trView, or egView event.
Kind: inner method of uvHelper
Returns: Promise
- A Promise that resolves with the ecView event data.
Promise
uvHelper~waitForProductDetails() ⇒ Waits for an ecProduct detail event.
Kind: inner method of uvHelper
Returns: Promise
- A Promise that resolves with the ecProduct event data.
Promise
uvHelper~waitForProductListing() ⇒ Waits for an ecProduct listing event.
Kind: inner method of uvHelper
Returns: Promise
- A Promise that resolves with the ecProduct event data.
Promise
uvHelper~waitForBasketSummary([allowEmpty]) ⇒ Waits for an ecBasketSummary event.
Kind: inner method of uvHelper
Returns: Promise
- A Promise that resolves with the ecBasketSummary event data.
Throws:
- Throws a warning if the basket is empty and allowEmpty has not been specified.
Param | Type | Description |
---|---|---|
[allowEmpty] | boolean |
If true the function can resolve with empty baskets. |
Promise
uvHelper~waitForTransactionSummary([allowEmpty]) ⇒ Waits for an ecBasketTransactionSummary event.
Kind: inner method of uvHelper
Returns: Promise
- A Promise that resolves with the ecBasketTransactionSummary event data.
Throws:
- Throws a warning if the transaction is empty and allowEmpty has not been specified.
Param | Type | Description |
---|---|---|
[allowEmpty] | boolean |
If true the function can resolve with empty transactions. |
Promise
uvHelper~waitForBasketItems([allowEmpty]) ⇒ Waits for an ecBasketSummary followed by all ecBasketItem events.
Kind: inner method of uvHelper
Returns: Promise
- A Promise that resolves with all the event data { summary, items }.
Throws:
- Throws a warning if the basket is empty and allowEmpty has not been specified.
Param | Type | Description |
---|---|---|
[allowEmpty] | boolean |
If true the function can resolve with empty baskets. |
Promise
uvHelper~waitForTransactionItems([allowEmpty]) ⇒ Waits for an ecBasketTransactionSummary followed by all ecBasketItemTransaction events.
Kind: inner method of uvHelper
Returns: Promise
- A Promise that resolves with all the event data { summary, items }.
Throws:
- Throws a warning if the transaction is empty and allowEmpty has not been specified.
Param | Type | Description |
---|---|---|
[allowEmpty] | boolean |
If true the function can resolve with empty transactions. |
Promise
uvHelper~waitForUser() ⇒ Waits for an ecUser, trUser, or egUser event.
Kind: inner method of uvHelper
Returns: Promise
- A Promise that resolves with the User event data.
utils
A utility library for working with Qubit experiences.
any
utils~Promise : Kind: inner constant of utils