@unipro/dms-utils v0.6.2

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.

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.

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.

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.

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.

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.

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.

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.

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.

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

errorHelper~onErrorStop(e)

Kind: inner method of errorHelper

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

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

hooksHelper~onActivation(callback, removeCallback, namespace)

Attaches a tracking function to be called on activation of the experience.

Kind: inner method of hooksHelper

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

hooksHelper~runOnActivation(namespace)

Manually runs any tracking functions added by onActivation.

Kind: inner method of hooksHelper

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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

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

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

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.

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.

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.

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.

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