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

arrayHelper~sliceRandom(array, [outputArrayLength]) ⇒ Array

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)

arrayHelper~flattenArrays(arrayOfArrays) ⇒ Array

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]

arrayHelper~filterTallyByThreshold(tally, threshold, [noWarning]) ⇒ Array

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.

arrayHelper~isItemInArray(array, item) ⇒ boolean

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.

arrayHelper~findItemInArray(array, item) ⇒ string

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.

arrayHelper~isArrayItemInArray(array1, array2) ⇒ boolean

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.

arrayHelper~findArrayItemInArray(array1, array2) ⇒ string

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

deviceHelper~isMobileDevice() ⇒ boolean

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()) {
  ...
}

deviceHelper~isTabletDevice() ⇒ boolean

Determines whether the visitor's device type is tablet.

Kind: inner method of deviceHelper
Returns: boolean - true if tablet, false if not.

deviceHelper~isDesktopDevice() ⇒ boolean

Determines whether the visitor's device type is desktop.

Kind: inner method of deviceHelper
Returns: boolean - true if desktop, false if not.

deviceHelper~isMobileOrTabletDevice() ⇒ boolean

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.

deviceHelper~isTabletOrDesktopDevice() ⇒ boolean

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.

• elementHelper
  • ~waitForScrollIntoView($element, [offset], [wait], [throttleOptions]) ⇒ Promise
  • ~waitForElementVisible($target, toggle, [isVisibleCallback]) ⇒ Promise

elementHelper~waitForScrollIntoView($element, [offset], [wait], [throttleOptions]) ⇒ Promise

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)

elementHelper~waitForElementVisible($target, toggle, [isVisibleCallback]) ⇒ Promise

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)
  • ~onErrorStop(e)
  • ~Warning(message) ⇒ void

errorHelper~onError(e)

Kind: inner method of errorHelper

Param	Type
e	Error

errorHelper~onErrorStop(e)

Kind: inner method of errorHelper

Param	Type
e	Error

errorHelper~Warning(message) ⇒ void

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])
  • ~onActivation(callback, [removeCallback], [namespace])
  • ~removeCliStyle() ⇒ HTMLElement
  • ~runOnRemove([namespace])
  • ~runOnActivation([namespace])

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.

hooksHelper~removeCliStyle() ⇒ HTMLElement

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

jQueryHelper~ajax(url, [settings]) ⇒ Promise

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

jQueryHelper~get(url, [data], [dataType]) ⇒ Promise

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).

jQueryHelper~post(url, [data], [dataType]) ⇒ Promise

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).

jQueryHelper~insertElement($element, target, insertionMethod) ⇒ any

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.

moneyHelper~formatPrice(price, locale, currency, [trim]) ⇒ string

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.

objectHelper~deepCopy(object) ⇒ 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.

pollerHelper~pollerPromise(pollFor, [timeoutMessage]) ⇒ Object

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

requireHelper~requireCountdownPackage() ⇒ Promise

Gets the Countdown package for Qubit.

Kind: inner method of requireHelper
Returns: Promise - Promise that resolves with the Countdown object.

requireHelper~requireSlickPackage() ⇒ Promise

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.

segmentHelper~getSegments() ⇒ Promise

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

storageHelper~isSessionStorageAccessible() ⇒ boolean

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.

storageHelper~isLocalStorageAccessible() ⇒ boolean

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.

storageHelper~getQueueFromSessionStorage(storageKey) ⇒ Array

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}`)

storageHelper~getQueueFromLocalStorage(storageKey) ⇒ Array

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}`)

storageHelper~queueItemToSessionStorage(storageKey, value, max, [uniqueProperty]) ⇒ Array

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)

storageHelper~queueItemToLocalStorage(storageKey, value, max, [uniqueProperty]) ⇒ Array

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)

storageHelper~removeItemFromSessionStorage(storageKey, value, [uniqueProperty]) ⇒ Array

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')

storageHelper~removeItemFromLocalStorage(storageKey, value, [uniqueProperty]) ⇒ Array

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

stringHelper~toTitleCase(string) ⇒ 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').

stringHelper~toLowerTrim(string) ⇒ 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

stringHelper~toRelativeUrl(url) ⇒ string

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

stringHelper~toAbsoluteUrl(url, [domain]) ⇒ string

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

uvHelper~waitForPage() ⇒ Promise

Waits for an ecView, trView, or egView event.

Kind: inner method of uvHelper
Returns: Promise - A Promise that resolves with the ecView event data.

uvHelper~waitForProductDetails() ⇒ Promise

Waits for an ecProduct detail event.

Kind: inner method of uvHelper
Returns: Promise - A Promise that resolves with the ecProduct event data.

uvHelper~waitForProductListing() ⇒ Promise

Waits for an ecProduct listing event.

Kind: inner method of uvHelper
Returns: Promise - A Promise that resolves with the ecProduct event data.

uvHelper~waitForBasketSummary([allowEmpty]) ⇒ Promise

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.

uvHelper~waitForTransactionSummary([allowEmpty]) ⇒ Promise

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.

uvHelper~waitForBasketItems([allowEmpty]) ⇒ Promise

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.

uvHelper~waitForTransactionItems([allowEmpty]) ⇒ Promise

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.

uvHelper~waitForUser() ⇒ Promise

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.

utils~Promise : any

Kind: inner constant of utils