BOOMR. utils

Classes

• Compression

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

Returns:

Type: boolean

Returns true if MutationObserver is supported. 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/

---

isUASameSiteNoneCompatible(uaString)

Parameters:

Name	Type	Description
uaString	string	User agent string

Returns:

Type: boolean

True if a browser can safely create SameSite=None cookie

---

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.

---

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