❤
npm
Sign UpSign In

@unipro/dms-utils

0.6.2 • Public • Published

DMS Utility Library

arrayHelper

A module that provides common array helper functions.

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

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

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)

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

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

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

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

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

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

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

Dependencies (8)

Dev Dependencies (0)

    Package Sidebar

    Install

    npm i @unipro/dms-utils

    Weekly Downloads

    9

    Version

    0.6.2

    License

    ISC

    Unpacked Size

    98.9 kB

    Total Files

    24

    Last publish

    Collaborators

    • alex.gill
    • steve.sutton
    • itdeaprtment
    Try on RunKit
    Report malware