New Package Monster

    @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

    Keywords

    none

    Install

    npm i @unipro/dms-utils

    DownloadsWeekly Downloads

    21

    Version

    0.6.2

    License

    ISC

    Unpacked Size

    98.9 kB

    Total Files

    24

    Last publish

    Collaborators

    • alex.gill
    • steve.sutton
    • itdeaprtment