Sidecar API Reference Module: Utils/Utils

The Utils module provides several utility methods, such as those for number formatting.

Members

<inner> cookie :Utils/Utils.Cookie

Type:

Utils/Utils.Cookie

Methods

<static> addNumberSeparators(numberString, numberGroupSeparator, decimalSeparator)

Adds number separators to a number string.

Parameters:

Name	Type	Description
`numberString`	string	String of number to be modified of the format nn.nnn.
`numberGroupSeparator`	string	Character separator for number groups of 3 digits to the left of the decimal to add.
`decimalSeparator`	string	Character to replace decimal in arg number with.

Returns:

numberString with the appropriate separators added.

Type: string

<static> areBeanValuesEqual(value1, value2)

Checks to see if values in beans are equal to each other.

Parameters:

Name	Type	Description
`value1`	*	The first value.
`value2`	*	The second value.

Returns:

true if the values are equal; false otherwise.

Type: boolean

<static> buildUrl(url)

Builds a good url based on siteUrl from configuration.

It is ready for the several use cases that siteUrl can have:

relative path (aka context);
full path;
empty path.

Parameters:

Name	Type	Description
`url`	string	The full url or a relative url without the prepended `/`.

Returns:

The constructed URL.

Type: string

<static> capitalize(s)

Capitalizes a string.

Parameters:

Name	Type	Description
`s`	string	The string to capitalize.

Returns:

s capitalized, or an empty string if s is undefined or null.

Type: string

<static> capitalizeHyphenated(s)

Capitalizes a hyphenated string and removes the hyphens. The first letter, and all letters after a hyphen, are capitalized, so "my-string" becomes "MyString".

Parameters:

Name	Type	Description
`s`	string	The string to capitalize.

Returns:

s capitalized or an empty string if s is undefined or null.

Type: string

<static> classify(s)

Capitalizes an underscored string and removes the underscores. The first letter, and all letters after an underscore, are capitalized, so "my_string" becomes "MyString".

Parameters:

Name	Type	Description
`s`	string	The string to capitalize.

Returns:

s capitalized or an empty string if s is undefined or null.

Type: string

<static> compareBeans(beanA, beanB)

Compare field values in the first bean with the second bean and return the field names that have different values.

Parameters:

Name	Type	Description
`beanA`	Data/Bean	The first bean.
`beanB`	Data/Bean	The second bean.

Returns:

A list of names of fields whose values differ between beanA and beanB.

Type: Array.<string>

<static> convertNumericType(value, type)

Converts provided value to provided type. Intended to convert numbers stored as strings using the appropriate conversion function.

Parameters:

Name	Type	Description
`value`	string	The value to convert
`type`	string	Abbreviated type to be converted to

Returns:

Value converted to provided type

Type: number

<static> deepCopy(obj)

Creates a deep clone of an object.

Parameters:

Name	Type	Description
`obj`	*	The object to clone.

Returns:

A value of the same type as the input.

Type: *

<static> doWhen(condition, callback [, params] [, scope])

Based on YUI's onAvailable, but will use any boolean function instead of an ID. Once the given condition is met, the callback function will be executed.

// Execute a callback once an Object is defined
Utils.doWhen('SUGAR.ObjectToWaitFor', function(){
    // Use the object here
    console.log(SUGAR.ObjectToWaitFor);
});

// Use a function for condition and set parameters for the callback
var el = $('#myId');
var cond = function(){return el.hasClass('foo')};
var callback = function(params) {
    this.log(params.msg);
    el.html(params.html);
};
Utils.doWhen(cond, callback, {
    msg: 'Hello World',
    html: '<h1>Exists!</h1>'
}, console);

Parameters:

Name	Type	Argument	Description
`condition`	function \| string		Function/evaluatable string which must return a boolean value.
`callback`	function		Function to execute when `condition` is met.
`params`	Object	<optional>	Object to pass to `callback`.
`scope`	Object	<optional>	Object to use as `this` when executing `callback`.

<static> extendClass(cache, defaultBase, className, controller, platformNamespace)

Extends a Class based on the given controller.

If the controller has an extendsFrom property, it will be used to define its parent class. It should be defined as a string in order for the system to detect if there is any customization on that parent (normally prefixed with Custom like Custom<ClassName>).

If the parent class defined in the extendsFrom property doesn't exist or the controller isn't specifying one, it will fallback to the supplied defaultBase param which has it's own set of fallback strategy defined by the components that call this method. See View.ViewManager and Data.DataManager.

Parameters:

Name	Type	Description
`cache`	Object	Object cache to add controller to.
`defaultBase`	Object	Class to be extended from if no override (`extendsFrom`) is defined in the controller.
`className`	string	Class name to be used for new Class.
`controller`	Object	Properties for new Class.
`platformNamespace`	string	Platform name.

Returns:

The new extended class.

Type: Object

<static> extendFrom(subc, superc, overrides)

Forces one class to extend from another and optionally overrides specific properties.

Parameters:

Name	Type	Description
`subc`	function	Constructor for the subclass.
`superc`	function	Constructor for the superclass.
`overrides`	Object	Properties to override on `subc`'s prototype.

<static> formatName(params, format)

Formats a full name with the provided locale format.

Parameters:

Name Type Description

params

Object

Name property values.

Properties

Name	Type	Description
`first_name`	string	First name.
`last_name`	string	Last name.
`salutation`	string	Salutation.

format

string

Locale format (i.e. [f l s], [s l, f]).

Returns:

Formatted string.

Type: string

<static> formatNameLocale(params)

Formats a full name according to the user's locale format.

Parameters:

Name Type Description

params

Object

Name property values.

Properties

Name	Type	Description
`first_name`	string	First name.
`last_name`	string	Last name.
`salutation`	string	Salutation.

Returns:

Formatted string.

Type: string

<static> formatNameModel(module, data [, format])

Formats a record's name (ie. full name) according to the name format passed in parameters or defined in the user preferences.

Format you can pass:

'f l s' will output: `FirstName LastName Salutation`,
's l, f' will output: `Salutation LastName FirstName`.

The module defines a nameFormat object that maps a letter to a field.

{
    s: 'salutation',
    f: 'first_name',
    l: 'last_name'
}

Parameters:

Name	Type	Argument	Default	Description
`module`	string			The module name the record belongs to.
`data`	Object			The record attributes.
`format`	string	<optional>	User.getPreference('default_locale_name_format')	The format definition.

Returns:

The formatted full name string.

Type: string

<static> formatNumber(value, round, precision, numberGroupSeparator, decimalSeparator, toStringOnly)

Formats a number.

Parameters:

Name	Type	Description
`value`	number	Number to be formatted eg 2.134.
`round`	number	number of digits to right of decimal to round at.
`precision`	number	number of digits to right of decimal to take precision at.
`numberGroupSeparator`	string	Character separator for number groups of 3 digits to the left of the decimal to add.
`decimalSeparator`	string	Character to replace decimal in arg number with.
`toStringOnly`	boolean	Flag for integer type field if `true`, convert integer to string value, else rounds it.

Returns:

Formatted number string OR original value if it is not a number.

Type: string

<static> formatNumberLocale(value)

Formats a number according to the current user locale.

Parameters:

Name	Type	Description
`value`	number	Value to format.

Returns:

Formatted number.

Type: string

<static> formatString(format, args)

Replaces tokens like {0}, {1}, etc. with the provided arguments.

Parameters:

Name	Type	Description
`format`	string	String to format.
`args`	string	Arguments to replace.

Returns:

Formatted string.

Type: string

<static> generateUUID()

Generates and returns a UUID according to RFC 4122.

Returns:

A UUID.

Type: string

<static> getChangedProps(data1, data2 [, strict])

Gets the diff between data1 and data2. Intended for comparing objects with the same properties.

Parameters:

Name	Type	Argument	Default	Description
`data1`	Object			Changed object
`data2`	Object			Original object
`strict`	boolean	<optional>	false	By default values are compared property by property via non-strict comparison.

Returns:

Hash of fields from data1 which are different from data2.

Type: Object

<static> getParentLayout(component)

Gets the layout container for the given component.

Parameters:

Name	Type	Description
`component`	View/Component	The component whose layout you want.

Returns:

The layout container for the given component.

Type: View/Layout

<static> getTimestamp( [dateValue] [, options])

Returns ISO8601 timestamp in UTC time.

Parameters:

Name Type Argument Default Description

dateValue

string | number

new Date()

Date string or raw msec number.

options

Object

{}

Extra parameters.

Properties

Name	Type	Argument	Default	Description
`msecPrecision`	boolean	<optional>	false	If `true`, include milliseconds in the output.

Returns:

Passed date or current date converted to UTC timezone.

Type: string

<static> hardRefresh()

Performs a hard refresh of the current page.

<static> hasDefaultValueChanged(attribute, bean)

Checks to see if the default value has changed.

Parameters:

Name	Type	Description
`attribute`	string	The bean attribute you are interested in.
`bean`	Data/Bean	The bean to check the value of.

Returns:

true if the value of attribute for bean is different than its default value; false otherwise.

Type: boolean

<static> isConnectivityError(ajaxError)

Checks if the AJAX error is a network connectivity error: timeout, DNS, etc.

Parameters:

Name	Type	Description
`ajaxError`	Api.HttpError	AJAX error.

Returns:

true if the error is a network error; false otherwise.

Type: boolean

<static> isDirectionRTL(value)

Checks if the value should be rendered in RTL.

Parameters:

Name	Type	Description
`value`	string	The value to check.

Returns:

true if the string is in a RTL language.

Type: boolean

<static> isSortable(module, fieldViewdef)

Determines if a given module is sortable on a certain field when in a particular view.

Parameters:

Name Type Description

module

string

The module to check.

fieldViewdef

Object

Viewdef for the field to consider.

Properties

Name	Type	Argument	Description
`name`	string		Name of the field; used to look up vardefs.
`sortable`	boolean	<optional>	If not `undefined`, determines whether the module is sortable or not, regardless of vardefs.

Returns:

true if module can be sorted by the field given by fieldViewdef; false otherwise.

Type: boolean

<static> isValidEmailAddress(address)

Checks if an email address is valid.

Only performs a very basic validation because the complexity of the server-side regular expression is too great to mirror on the client, both in terms of maintenance and difficulty in porting to a different engine. Even if the light-weight validation passes, the server-side validation may fail.

Parameters:

Name	Type	Description
`address`	string	The email address to check.

Returns:

false if this is definitely an invalid email address. A return value of true does not guarantee that this is a valid email address.

Type: boolean

<static> regexEscape(string)

Escapes a given string for use in a JavaScript regex.

Parameters:

Name	Type	Description
`string`	string	The string to escape.

Returns:

string escaped.

Type: string

<static> stripHttpPrefix(url)

Returns a URL without the http(s):// prefix.

Parameters:

Name	Type	Description
`url`	string	Input url.

Returns:

url without the http(s):// prefix.

Type: string

<static> unformatNumberString(numberString, numberGroupSeparator, decimalSeparator [, toFloat])

Unformats number strings.

Parameters:

Name	Type	Argument	Default	Description
`numberString`	string			The number string to unformat.
`numberGroupSeparator`	string			The thousands separator.
`decimalSeparator`	string			The string between number and decimals.
`toFloat`	boolean	<optional>	false	If `true`, convert string to float value.

Returns:

Formatted number string.

Type: string

<static> unformatNumberStringLocale(value [, toFloat])

Unformats a number string based on the current user's locale.

Parameters:

Name	Type	Argument	Default	Description
`value`	string			The number string to unformat.
`toFloat`	boolean	<optional>	false	If `true`, convert string to float value.

Returns:

The formatted value.

Type: string

<static> versionCompare(v1, v2 [, operator])

Compares two version strings.

Example:

Utils.versionCompare('8.2.5rc', '8.2.5a'); // 1
Utils.versionCompare('8.2.50', '8.2.52', '<') // true
Utils.versionCompare('5.3.0-dev', '5.3.0') === -1
Utils.versionCompare('4.1.0.52','4.01.0.51') === 1

Parameters:

Name	Type	Argument	Description
`v1`	string		First version.
`v2`	string		Second version.
`operator`	string	<optional>	Operator argument, if specified, test for a particular relationship. The possible operators are: `<`, `lt`, `<=`, `le`, `>`, `gt`, `>=`, `ge`, `==`, `=`, `eq`, `!=`, `<>`, and `ne`. This parameter is case-sensitive, values should be lowercase.

Returns:

By default, returns -1 if the first version is lower than the second, 0 if they are equal, and 1 if the second is lower. When using the optional operator argument, the function will return true if the relationship is the one specified by the operator, false otherwise.

Type: number | boolean