Maestro API Reference

Namespace: Util

Util

Methods

Util.addRepeatContent(repeatItem, dataArray)

Adds repeated content as a new row via an array of data or an object of data. The keys must match the item ids of the repeat content.
Parameters:
Name Type Description
repeatItem Object | Array The repeat item to add the data to.
dataArray Array The array of objects to add to the repeat as a new row. The object keys must be the same as the ids in the repeat.

Util.append(target, newItems)

Appends one array to another array.
Parameters:
Name Type Description
target Array The first array.
newItems Array The second array.
Returns:
Returns the modified array.
Type
Array
Example
var firstArray = [1, 2, 3];
var secondArray = [4, 5, 6];
Util.append(firstArray, secondArray);
console.log(firstArray);
// => [1, 2, 3, 4, 5, 6]

Util.assert(assertion, message)

Throws an error message if the assertion is `false`.
Parameters:
Name Type Description
assertion *
message string
Examples

An assertion that returns `true`.

this.assert(1 != 2, "These aren't equal numbers.")

An assertion that returns `false`.

this.assert(1 === 2, "These are equal numbers.")

Util.base64ToFile(base64Data, tempfilename [, contentType])

Convert a base64 string to a `File` object.
Parameters:
Name Type Argument Default Description
base64Data string
tempfilename string
contentType string <optional>
 ''
Returns:
Returns a `File` object.
Type
File

Util.capitalizeFirstLetter(str)

Capitalizes the first letter of a string.
Parameters:
Name Type Description
str string The string to capitalize.
Returns:
Returns a string with the first character capitalized.
Type
string
Example
Util.capitalizeFirstLetter("hello world")
// => Hello world

Util.children(items)

Get direct children of a single item or array of items.
Parameters:
Name Type Description
items The item or array of items to check.
Returns:
Returns an array of the item's direct children.
Type
Array
Examples

Get the direct children of a single component.

Util.children(Form.items.address_global);

Get the direct children of multiple components.

Util.children([Form.items.page_one, Form.items.page_two, Form.items.page_three]);

Get all direct child components that are marked as mandatory.

Util.children(Form.items.address_global, function(parent) {
	return parent.mandatory;
});

Util.contains(val, item)

Checks if an item is in an array or string.
Parameters:
Name Type Description
val Array | string An array or a string to test against.
item The item to check.
Returns:
Returns `true` if the supplied `item` is contained within `val`.
Examples
Util.contains([[1, 2, 3], 3])
// => true
Util.contains(["Hello World", "Hello"])
// => true
Util.contains([[1, 2, 3], 4])
// => false
Util.contains(["Hello World", "Earth"])
// => false

Util.copy(source)

Performs a JSON-based copy of the provided parameter.
Parameters:
Name Type Description
source
Returns:
Returns a copy of the provided parameter *without* dollar properties.

Util.descendants(item [, includeTest])

Gets all descendants of an item.
Parameters:
Name Type Argument Description
item The item to check.
includeTest function <optional>
 A function that takes an item and determines whether that item and its children should be included.
Returns:
Returns all descendants of the specified item.
Type
Array
Examples

Get all descendants of a single component.

Util.descendants(Form.items.address_global);

Get all descendants of multiple components.

Util.descendants([Form.items.page_one, Form.items.page_two, Form.items.page_three]);

Get all descendant components that are marked as mandatory.

Util.descendants(Form.items.address_global, function(parent) {
	return parent.mandatory;
});

Util.endsWith(stringToSearch, searchString [, position])

Checks if a string ends with another string.
Parameters:
Name Type Argument Description
stringToSearch string The string to test against.
searchString string The string to use for the search.
position integer <optional>
 The position to start from.
Returns:
Returns `true` if the string ends with the search string.
Type
boolean
Examples
Util.endsWidth("Hello World", "World")
// => true
Util.endsWidth("Hello World", "Hello")
// => false

Util.equals(a, b)

Checks if two values are equal. If the values are objects (or arrays of objects), dollar properties will be ignored. Similar to `angular.equals`, but usable in Node.
Parameters:
Name Type Description
a * The first value.
b * The second value.
Returns:
Returns `true` if the provided values are equal.
Type
boolean

Util.find(array, name, value [, fetchMultiple])

Finds the first array item with the specified value for the named property.
Parameters:
Name Type Argument Description
array Array The array to search.
name The key to test against.
value The value to test against.
fetchMultiple boolean <optional>
 If `true`, an array of results will be returned.
Returns:
Returns the first array item with the specified value for the named property or an array of values if `fetchMultiple` is `true`. If there are no matches, `null` will be returned.
Type
Object | Array
Examples

Without `fetchMultiple`.

Util.find([{ name: "David", age: 28 }, { name: "Ken", age: 45 }, { name: "David", age: 31 }], "name", "David")
// => { name: "David", age: 28 }

With `fetchMultiple`.

Util.find([{ name: "David", age: 28 }, { name: "Ken", age: 45 }, { name: "David", age: 31 }], "name", "David", true)
// => [{ name: "David", age: 28 }, { name: "David", age: 31 }]

Util.flatten(array)

Recursively flattens the provided array.
Parameters:
Name Type Description
array Array The array to flatten.
Returns:
Returns a flattened array.
Type
Array
Example
Util.flatten([1, 2, 3, [1, 2, 3, [1, 2, 3]]])
// => [1, 2, 3, 1, 2, 3, 1, 2, 3]

Util.getGeoLocation()

Get's the user's coordinates, including latitude and longitude. The user will have to allow the form to access their location.
Returns:
Type
Promise.<result>
Example
Util.getGeoLocation().then(function(result) {
	console.log(result)
});
// => {
// 	accuracy: 41
// 	altitude: null
// 	altitudeAccuracy: null
// 	heading: null
// 	latitude: -33.7981214
// 	longitude: 151.2869892
// 	speed: null
// }

Util.getMimeType(ext)

Gets the MIME type for the provided file extension. The following extensions are supported: PNG, JPG, SVG, JSON, LESS, JS, and CSV.
Parameters:
Name Type Description
ext string An extension or a complete file name.
Returns:
Returns a MIME type for the provided file extension or `undefined` if not found.
Type
string
Examples
Util.getMimeType("jpg")
// => "image/jpeg"
Util.getMimeType("example.png")
// => "image/png"

Util.getUrlQueryParam(key)

Gets the value of a URL parameter.
Parameters:
Name Type Description
key string The name of the URL parameter.
Returns:
Returns the value of the provided URL parameter. If the parameter doesn't exist, `null` is returned.
Type
string | null
Examples

If the form code is "myexampleform".

Util.getUrlQueryParam("formCode")
// => myexampleform

If the query parameter doesn't exist.

Util.getUrlQueryParam("aFakeParameter")
// => null

Util.getUrlQueryParams()

Gets the current URL's parameters.
Returns:
Returns an object of the current URL parameters. The keys are the parameter names.
Type
Object
Example

If the form code parameter is "myexampleform".

Util.getUrlQueryParams();
// => { formCode: "myexampleform" }

Util.getVal(name)

Returns a getter function for the specified property name on any given object.
Parameters:
Name Type Description
name
Returns:
Type
function

Util.hasDescendants(item)

Checks if an item is a container with children.
Parameters:
Name Type Description
item
Returns:
Returns `true` if the item is a container with children or `false` if it's not.
Type
boolean
Examples

Checking if the "Address Block (Global)" component has descendants.

Util.hasDescendants(Form.items.address_global);
// => true

Checking if the "Text Field" component has descendants.

Util.hasDescendants(Form.items.textField);
// => false

Util.isBlank(value)

Checks if the supplied value is considered blank.
Parameters:
Name Type Description
value * The value to test.
Returns:
Returns `true` if the supplied value is a blank string, `null`, or `undefined`.
Examples
Util.isBlank();
// => true
Util.isBlank("");
// => true
Util.isBlank(null);
// => true
Util.isBlank("Hello World");
// => false
Util.isBlank(123456);
// => false
Util.isBlank(false);
// => false

Util.isLeapYear(year)

Checks if the provided year is a leap year
Parameters:
Name Type Description
year number | string The 4 digit year to test.
Returns:
Returns `true` if the provided year is a leap year.
Type
boolean
Examples
Util.isLeapYear(2020);
// => true
Util.isLeapYear("2020");
// => true
Util.isLeapYear(2019);
// => false
Util.isLeapYear("2019");
// => false

Util.jsonify(item [, exclusions] [, uglify] [, transform] [, sortByKeys])

Converts the provided data into JSON. By default, all dollar attributes are excluded.
Parameters:
Name Type Argument Description
item Array | Object
exclusions Array | string <optional>
 An array of properties to exclude from serialisation. If you pass through an empty array, dollar attributes will be included in the returned data. By default, the following properties are excluded: `data`, `propDefs`, `ruleTemplates`, `ruleHelpers`, `validChildren`, `validParents`, `html`.
uglify boolean <optional>
 If `true`, the JSON will be minified.
transform function <optional>
 A function to transform the object prior to other processing.
sortByKeys boolean <optional>
 If `true`, objects will be sorted by their keys in alphabetical order.
Returns:
Returns data in the JSON format.
Type
Object
Examples

Converting a simple object to JSON.

var object = { name: "David", location: "Australia" }
Util.jsonify(object)
// => {
//	"name": "David",
//	"location": "Australia"
// }

With "uglify" enabled.

var object = { name: "David", location: "Australia" }
Util.jsonify(object, null, true);
// => {"name":"David","location":"Australia"}

Sorting the keys in alphabetical order.

var object = { name: "David", location: "Australia" }
Util.jsonify(object, null, null, null, true);
// => {
//	"location": "Australia",
//	"name": "David"
// }

Util.keys(object)

Like `Object.keys` but includes properties from prototype chain
Parameters:
Name Type Description
object Object
Returns:
Returns an array of an object's keys, including properties from prototype chain
Type
Array
Example
Util.keys({ name: "David", age: 28, location: "Australia" })
// => ["name", "age", "location"]

Util.lastItem(array)

Gets the last item from an array.
Parameters:
Name Type Description
array Array The array to get the last item from.
Returns:
Returns the last item in the array.
Type
*
Examples
Util.lastItem(["Nicole", "Ken", "David"]);
// => "David"
Util.lastItem([1, 2, 3]);
// => 3

Util.locate(item)

Gets the position of an item within its parent.
Parameters:
Name Type Description
item
Returns:
Returns an object with "row" and "col" keys, which provide the position of the item within its parent.
Type
Object
Example
Util.locate(Form.items.firstName);
// => {
// 	col: 0,
// 	row: 0
// }

Util.logError(error)

Logs an error to the JavaScript Console. Equivalent to the `console.error` method.
Parameters:
Name Type Description
error The error message to log to the console.
Example
Util.logError("Something went terribly wrong.");

Util.logItem(item [, renderer] [, indent])

Prettifies an item's structure
Parameters:
Name Type Argument Description
item
renderer function <optional>
 Can provide a custom function which takes an item and returns a string to render for that item, otherwise just shows ID
indent integer <optional>
 Don't pass anything to this parameter. It's used for internal recursion.
Returns:
Returns a prettified version of an item's structure.
Example

The structure of the "Address Block (Global)" component.

Util.logItem(First.items.address_global)
// => address_global
// 	─ address_line_1
// 	─ address_line_2
// 	┌ suburb_city
// 	│ state_province
// 	└ postcode_zipcode
//  	─ country

Util.merge(fromObj, toObj [, trim] [, handler])

Add nodes to toObj that are in fromObj but missing from toObj. This is recursive for plain objects but not arrays - for special array handling use handler parameter. If trim is set, any nodes that exist in the structure of toObj that do not have an equivalent node in fromObj will be removed. If handler is provided, it will be called for each node (other then trimmed nodes in toObj), following any value assignment but before any child-node processing, with the parameters (fromObj, toObj, key), allowing use-case-specific post processing of node values.
Parameters:
Name Type Argument Description
fromObj Object The first object. Keys from this object that are not in the second object will be added to the second object.
toObj Object The second object.
trim boolean <optional>
 If `true`, any nodes that exist in the structure of `toObj` that do not have an equivalent node in `fromObj` will be removed.
handler function <optional>
Returns:
Returns the modified `toObj` object
Type
Object
Examples

Merging two simple objects.

var firstObject = { name: "David", location: "Australia" };
var secondObject = { name: "David", age: 28 };
Util.merge(firstObject, secondObject);
// => { name: "David", location: "Australia", age: 28 }

With `trim` set to `true`.

var firstObject = { name: "David", location: "Australia" }
var secondObject = { name: "David", age: 28 }
Util.merge(firstObject, secondObject, true);
// => { name: "David", location: "Australia" }

Util.nextItem(item)

Finds the next form item, either the first leaf node of the specified item or recursively up its path until a subsequent sibling is found and then back down to its first leaf node.
Parameters:
Name Type Description
item
Returns:
Type
Object

Util.objectPaths(obj [, renderer] [, parentKey])

Return an array containing entries for each path within the given object. If a renderer function is provided, the entry will be the result of calling renderer passing the path and the value at that path as the two parameters. Otherwise the entry will be the path.
Parameters:
Name Type Argument Description
obj Object
renderer function <optional>
parentKey string <optional>
 Used for internal recursion, this key is appended to the start of all paths
Returns:
Returns an array of entries for each path within the given object.
Type
Array
Example
Util.objectPaths({ name: "David", location: { suburb: "Manly", postcode: 2095, country: "Australia" } })
// => ["name", "location.suburb", "location.postcode", "location.country"]

Util.objectsToMap(objects, keyGetter, valueGetter)

Returns a map with a key value pair derived from each of the provided objects.
Parameters:
Name Type Description
objects Array
keyGetter string | function Can be a property name within the object containing the map key, or a function which takes that object and returns a map key
valueGetter string | function Can be a property name within the object containing the value, or a function which takes the object and returns the value, or null / undefined, in which case the whole object is the value (i.e. same as specifying the identity function for valueGetter)
Returns:
Returns a map with a key value pair derived from the provided objects.
Type
Object

Util.openURL(url)

Opens a URL in a new window.
Parameters:
Name Type Description
url string The URL of the page to open.
Example

Open a valid URL.

Util.openURL("https://google.com")

Util.openWithPopupBlockerCheck(url, id)

Opens the specified URL (with an ID if specified) in a new tab. (Use the same tab if running in homescreen mode on iOS.) Checks for a popup blocker and warns the user.
Parameters:
Name Type Description
url string
id string
Examples
Util.openWithPopupBlockerCheck("https://google.com");
Util.openWithPopupBlockerCheck("https://google.com", "myNewTab");

Util.parents(item [, includeTest], reverse)

Gets all parents of an item.
Parameters:
Name Type Argument Description
item The item to check.
includeTest function <optional>
 A function that takes an item and determines whether that item and its parents should be included.
reverse boolean If `true`, the parents will be in the order of lowest to highest level of nesting.
Returns:
Returns all parents of the specified item.
Type
Array
Examples

Get all ancestors of a component.

Util.parents(Form.items.firstName);

Get all ancestors of a component that are marked as mandatory.

Util.parents(Form.items.firstName, function(parent) {
	return parent.mandatory;
});

Reverse the order of the returned array.

Util.parents(Form.items.firstName, null, true);

Util.range(from, to)

Creates an array of numbers.
Parameters:
Name Type Description
from number The number to begin the range with.
to number The number to end the range with.
Returns:
Returns an array of numbers.
Type
Array
Example
Util.range(1, 7);
// => [1, 2, 3, 4, 5, 6, 7]

Util.removeItem(array, item)

Removes an item from an array. If the item appears more than once in the array, all instances are removed.
Parameters:
Name Type Description
array Array The array to remove the item from.
item The item to remove from the array.
Returns:
Returns an array with the specified item(s) removed.
Type
Array
Examples
Util.removeItem(["Nicole", "Ken", "David"], "Nicole");
// => ["Ken", "David"]
Util.removeItem(["Nicole", "Nicole", "Nicole", "Ken", "David"], "Nicole");
// => ["Ken", "David"]

Util.replace(array, remove, add)

Replaces an item in an array with a different item. The original array is modified, rather than a new array being created.
Parameters:
Name Type Description
array Array The array to modify.
remove * The item to remove from the array.
add * The item to add into the array.
Example
var array = ["David", "Nicole", "Simone"];
Util.replace(array, "Nicole", "Ken");
console.log(array);
// => ["David", "Ken", "Simone"];

Util.resizeImage(img, width, height [, quality])

Resize an image using step-down technique.
Parameters:
Name Type Argument Default Description
img
width number
height number
quality number <optional>
 1.0
Returns:
Returns an image.

Util.sendAll(item, handler, childrenOnly, includeDialogsModals, checkExcluded)

Apply the given handler to the given form view item (unless childrenOnly is specified) and all its sub-items, including the sub-items of dialogs and modals if the provided item is a base form view. If the handler function returns the boolean value _false_ then the handler function will not be called for its children.
Parameters:
Name Type Description
item
handler function
childrenOnly boolean Do not apply the handler to the item itself, only its children
includeDialogsModals boolean will check modals and dialogs
checkExcluded boolean

Util.slot(array, object, key [, reverse])

Slots an object into an array in the correct position to maintain existing alphabetical ordering on a given key.
Parameters:
Name Type Argument Description
array Array The array to modify.
object Object The object to insert into the array.
key string The key in the object to maintain existing ordering.
reverse Array <optional>
 If `true`, operates from last element backwards.
Returns:
Returns an array that contains the new object.
Type
Array

Util.sortBy(property [, ignoreCase])

Creates an array `sort` function for sorting on the specified property name.
Parameters:
Name Type Argument Description
property The property to sort the array by.
ignoreCase boolean <optional>
 If `true`, the case of the property name will not affect the sorting.
Returns:
Returns a `sort` function for the specified property name.
Type
function
Examples

Create a case-sensitive `sort` function.

var mySortFunction = Util.sortBy("name");
var object = [{ name: "Nicole" }, { name: "David" }, { name: "Ken" }];
object.sort(mySortFunction)
// => [{ name: "David" }, { name: "Ken" }, { name: "Nicole" }]

Create a case-insensitive `sort` function.

Util.sortBy("name", true);

Util.sortItems(items, context)

Given a set of items and a context which contains all those items somewhere within it, return an array of the items sorted into the order in which they appear.
Parameters:
Name Type Description
items Array
context
Returns:
Returns an array of the items, sorted in the order they appear.
Type
Array

Util.startsWith(stringToSearch, searchString [, position])

Checks if a string starts with another string
Parameters:
Name Type Argument Description
stringToSearch string The string to test against.
searchString string The string to use for the search.
position integer <optional>
 The position to start from.
Returns:
Retuns `true` if the string starts with the search string.
Type
boolean
Examples
Util.startsWith("Hello World", "World");
// => false
Util.startsWith("Hello World", "Hello");
// => true
Util.startsWith("Hello World", "World", 6);
// => true

Util.sum(array)

Sums the values in an array.
Parameters:
Name Type Description
array Array The array of values to sum.
Returns:
Returns a sum of the values in an array. If the array is empty, `0` will be returned.
Type
integer
Examples
Util.sum([])
// => 0
Util.sum([1, 2, 3])
// => 6

Util.testKeys(object)

Gets the keys of truthy values from an object.
Parameters:
Name Type Description
object Object
Returns:
Returns an array of keys.
Type
Array
Example
Util.testKeys({ name: "David", age: 28, location: null });
// => ["name", "age"]

Util.toCamelCase(str)

Converts the supplied string to camel case.
Parameters:
Name Type Description
str string
Returns:
Returns the provided string in camel case.
Type
string
Example
Util.toCamelCase("Hello World");
// => "helloWorld"

Util.unique(array [, key])

Removes duplicate values from an array. For values that aren't primitive types, the test for duplication uses referential equality, not value equality.
Parameters:
Name Type Argument Description
array Array The array with duplicate values.
key string <optional>
 If specified, use this key to check. Useful of arrays of objects.
Returns:
Returns an array without duplicate values.
Type
Array
Examples
Util.unique([1, 2, 3, 1, 2, 3]);
// => [1, 2, 3]
Util.unique(["David", "John", "David"]);
// => ["David", "John"]

Util.values(object [, renderer])

Gets all of the values from an object.
Parameters:
Name Type Argument Description
object Object The object to get the values from.
renderer function <optional>
 A function to render each key-value entry.
Returns:
Returns an array of the object's values. This method doesn't define an order for the returned values, but they will generally be ordered alphabetically based on their key.
Type
Array
Example
Util.values({ name: "David", age: 28, location: "Australia" })
// => [28, "David", "Australia"]

Util.xray(object [, preprocessor] [, includeCheck])

Return an object with all key values of the given object (including those in the prototype chain) promoted to top-level keys. The process is recursive through nested objects. If preprocessor is provided, it will be called with (key, value) and can return either a {key, value} object that specifies both the key and its value in the resulting object, or any other type of value, in which case that value is associated with the original key in the resulting object. If includeCheck is provided, it will be called with (key, value) after preprocessing and if it returns a falsey value then the key/value will be excluded from the resulting object.
Parameters:
Name Type Argument Description
object Object
preprocessor function <optional>
includeCheck function <optional>
Returns:
Returns an object with all key values of the provided object, including those in the prototype chain.
Type
Object