mPulse Boomerang

BOOMR. utils

Classes

Methods

addListener(el, type, fn, passiveOrOpts)

Adds an event listener.

Parameters:

Name Type Description
el DOMElement

DOM element
type string

Event name
fn function

Callback function
passiveOrOpts boolean | object

Passive mode or Options object

addObserver(el, config, timeout, callback, callback_data, callback_ctx)

Add a MutationObserver for a given element and terminate after timeoutms.

Parameters:

Name Type Description
el DOMElement

DOM element to watch for mutations
config MutationObserverInit

MutationObserverInit object (https://developer.mozilla.org/en-US/docs/Web/API/MutationObserver#MutationObserverInit)
timeout number

Number of milliseconds of no mutations after which the observer should be automatically disconnected. If set to a falsy value, the observer will wait indefinitely for Mutations.
callback BOOMR~addObserverCallback

Callback function to call either on timeout or if mutations are detected.
callback_data object

Any data to be passed to the callback function as its second parameter.
callback_ctx object

An object that represents the this object of the callback method. Leave unset the callback function is not a method of an object.

Returns:

Type: object | null

  • null if a MutationObserver could not be created OR
  • An object containing the observer and the timer object: { observer: <MutationObserver>, timer: <Timeout Timer if any> }
  • The caller can use this to disconnect the observer at any point by calling retval.observer.disconnect()
  • Note that the caller should first check to see if retval.observer is set before calling disconnect() as it may have been cleared automatically.

arrayFilter(array, predicate)

filter for arrays

Parameters:

Name Type Description
array Array

The array to iterate over.
predicate function

The function invoked per iteration.

Returns:

Type: Array

Returns the new filtered array.

arrayFind(array, predicate)

find for Arrays

Parameters:

Name Type Description
array Array

The array to iterate over
predicate function

The function invoked per iteration

Returns:

Type: Array

Returns the value of first element that satisfies the predicate

cleanupURL(url, urlLimit)

Cleans up a URL by removing the query string (if configured), and limits the URL to the specified size.

Parameters:

Name Type Description
url string

URL to clean
urlLimit number

Maximum size, in characters, of the URL

Returns:

Type: string

Cleaned up URL

generateId(chars)

Generates a random ID based on the specified number of characters. Uses characters a-z0-9.

Parameters:

Name Type Description
chars number

Number of characters (max 40)

Returns:

Type: string

Random ID

generateUUID()

Generates a pseudo-random UUID (Version 4): https://en.wikipedia.org/wiki/Universally_unique_identifier

Returns:

Type: string

UUID

getCookie(name)

Gets the cached value of the cookie identified by name.

Parameters:

Name Type Description
name string

Cookie name

Returns:

Type: string | undefined

Cookie value, if set.

getLocalStorage(name)

Retrieve items from localStorage

Parameters:

Name Type Description
name string

Name of storage

Returns:

Type: object | null

Returns object retrieved from localStorage. Returns undefined if not found or expired. Returns null if parameters are invalid or an error occured

getQueryParamValue(param [, url])

Get a query parameter value from a URL's query string

Parameters:

Name Type Argument Description
param string

Query parameter name
url string | Object <optional>

URL containing the query string, or a link object. Defaults to BOOMR.window.location

Returns:

Type: string | null

URI decoded value or null if param isn't a query parameter

getRawCookie(name)

Gets the value of the cookie identified by name.

Parameters:

Name Type Description
name string

Cookie name

Returns:

Type: string | null

Cookie value, if set.

getSameSiteAttributeParts()

Depending on Boomerang configuration and checks of current protocol and compatible browsers the logic below will provide an array of cookie attributes that are needed for a successful creation of a cookie that contains the SameSite attribute.

How it works:

  1. We read the Boomerang configuration key same_site_cookie where one of the following values None, Lax or Strict is expected.
  2. A configuration value of same_site_cookie will be read in case-insensitive manner. E.g. Lax, lax and lAx will produce same result - SameSite=Lax.
  3. If a same_site_cookie configuration value is not specified a cookie will be created with SameSite=Lax.
  4. If a same_site_cookie configuration value does't match any of None, Lax or Strict then a cookie will be created with SameSite=Lax.
  5. The Secure cookie attribute will be added when a cookie is created with SameSite=None.
  6. It's possible that a Boomerang plugin or external code may need cookies to be created with SameSite=None. In such cases we check a special flag forced_same_site_cookie_none. If the value of this flag is equal to true then the same_site_cookie value will be ignored and Boomerang cookies will be created with SameSite=None.

SameSite=None - INCOMPATIBILITIES and EXCEPTIONS:

There are known problems with older browsers where cookies created with SameSite=None are dropped or created with SameSite=Strict. Reference: https://www.chromium.org/updates/same-site/incompatible-clients

  1. If we detect a browser that can't create safely a cookie with SameSite=None then Boomerang will create a cookie without the SameSite attribute.
  2. A cookie with SameSite=None can be created only over HTTPS connection. If current connection is HTTP then a cookie will be created without the SameSite attribute.

Returns:

Type: Array

of cookie attributes used for setting a cookie with SameSite attribute

getSubCookies(cookie)

Parse a cookie string returned by BOOMR.utils.getCookie and split it into its constituent subcookies.

Parameters:

Name Type Description
cookie string

Cookie value

Returns:

Type: object

On success, an object of key/value pairs of all sub cookies. Note that some subcookies may have empty values. null if cookie was not set or did not contain valid subcookies.

hashQueryString(url, stripHash)

Gets the URL with the query string replaced with a hash of its contents.

Parameters:

Name Type Description
url string

URL
stripHash boolean

Whether or not to strip the hash

Returns:

Type: string

URL with query string hashed

inArray(val, ary)

Determines if the specified value is in the array

Parameters:

Name Type Description
val object

Value to check
ary object

Object in question

Returns:

Type: boolean

True if the value is in the Array

isArray(ary)

Determines if the specified object is an Array or not

Parameters:

Name Type Description
ary object

Object in question

Returns:

Type: boolean

True if the object is an Array

isCurrentUASameSiteNoneCompatible()

Wrapper of isUASameSiteNoneCompatible() that ensures that we pass correct User Agent string

Returns:

Type: boolean

True if a browser can safely create SameSite=None cookie

isInteger(input)

Determines if the given input is an Integer. Relies on standard Number.isInteger() function that available is most browsers except IE. For IE, this relies on the polyfill provided by MDN: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number/isInteger#Polyfill

Parameters:

Name Type Description
input number

dat

Returns:

Type: string

Random ID

isMutationObserverSupported()

MutationObserver feature detection

Always returns false for IE 11 due several bugs in it's implementation that MS flagged as Won't Fix. In IE11, XHR responseXML might be malformed if MO is enabled (where extra newlines get added in nodes with UTF-8 content).

Another IE 11 MO bug can cause the process to crash when certain mutations occur.

For the process crash issue, see https://developer.microsoft.com/en-us/microsoft-edge/platform/issues/8137215/ and https://developer.microsoft.com/en-us/microsoft-edge/platform/issues/15167323/

Returns:

Type: boolean

Returns true if MutationObserver is supported.

isUASameSiteNoneCompatible(uaString)

Parameters:

Name Type Description
uaString string

User agent string

Returns:

Type: boolean

True if a browser can safely create SameSite=None cookie

makeSelector(elementNode)

Given a HTML node, returns a Pseudo-CSS selector.

Algorithm:

  • Starting at the node itself, gather its selector: elementName#elementId.elementClasses
    • If the ID or classes are missing, skip them, e.g. just elementName or elementName.elementClasses
  • Going up the parent tree via the .parentNode, stop at the first of:
    • The closest node (or itself) with an ID
    • The BODY node
  • For each node found, prepend the node's selector to the full selector string
  • Limit the number of selectors added to 5
    • If it takes more than 5 to get to an element with an ID or BODY, collapse to a * until they are reached

For example:

  • <div> <span> <h1> -> div span h1
  • <div id="test"> <span class="first"> -> div#test span.first
  • <span class="second"> <div id="test"> <span class="first"> -> div#test span.first
  • <span class="second"> <div id="test"> <span class="first second"> -> div#test span.first.second

Parameters:

Name Type Description
elementNode Node

Node to generate a Pseudo-CSS selector for

Returns:

Type: string

Pseudo-CSS selector

objectToString(o, separator, nest_level)

Converts an object to a string.

Parameters:

Name Type Description
o object

Object
separator string

Member separator
nest_level number

Number of levels to recurse

Returns:

Type: string

String representation of the object

pluginConfig(o, config, plugin_name, properties)

Sets the object's properties if anything in config matches one of the property names.

Parameters:

Name Type Description
o object

The plugin's impl object within which it stores all its configuration and private properties
config object

The config object passed in to the plugin's init() method.
plugin_name string

The plugin's name in the BOOMR.plugins object.
properties Array.<string>

An array containing a list of all configurable properties that this plugin has.

Returns:

Type: boolean

True if a property was set

removeCookie(name)

Removes the cookie identified by name by nullifying its value, and making it a session cookie.

Parameters:

Name Type Description
name string

Cookie name

removeListener(el, type, fn)

Removes an event listener.

Parameters:

Name Type Description
el DOMElement

DOM element
type string

Event name
fn function

Callback function

removeLocalStorage(name)

Remove items from localStorage

Parameters:

Name Type Description
name string

Name of storage

Returns:

Type: boolean

True if item was removed from localStorage.

runQuerySelector(queryselector, element, all)

Runs the specified QuerySelector

Parameters:

Name Type Description
queryselector string

QuerySelector
element Element

Root node
all boolean

True to use querySelectorAll

Returns:

Type: Element | null

Matching element

runXPath(xpath, element)

Runs the specified XPath expression

Parameters:

Name Type Description
xpath string

XPath expression
element Element

Root node

Returns:

Type: Element | null

Matching element

setCookie(name, subcookies, max_age)

Sets the cookie named name to the serialized value of subcookies.

Parameters:

Name Type Description
name string

The name of the cookie
subcookies object

Key/value pairs to write into the cookie. These will be serialized as an & separated list of URL encoded key=value pairs.
max_age number

Lifetime in seconds of the cookie. Set this to 0 to create a session cookie that expires when the browser is closed. If not set, defaults to 0.

Returns:

Type: boolean

True if the cookie was set successfully

Example

BOOMR.utils.setCookie("RT", { s: t_start, r: url });

setLocalStorage(name, items, max_age)

Saves items in localStorage The value stored in localStorage will be a JSON string representation of {"items": items, "expiry": expiry} where items is the object we're saving and expiry is an optional epoch number of when the data is to be considered expired

Parameters:

Name Type Description
name string

Name of storage
items object

Items to be saved
max_age number

Age in seconds before items are to be considered expired

Returns:

Type: boolean

True if the localStorage was set successfully