Utils/Utils

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

Source:

Members

# (inner) cookie :Utils/Utils.Cookie

Type:
Source:

Methods

# (static) addNumberSeparators(numberString, numberGroupSeparator, decimalSeparator) → {string}

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.
Source:
Returns:

numberString with the appropriate separators added.

Type
string

# (static) areBeanValuesEqual(value1, value2) → {boolean}

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

Parameters:
Name Type Description
value1 *

The first value.
value2 *

The second value.
Source:
Returns:

true if the values are equal; false otherwise.

Type
boolean

# (static) buildUrl(url) → {string}

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 /.
Source:
Returns:

The constructed URL.

Type
string

# (static) capitalize(s) → {string}

Capitalizes a string.

Parameters:
Name Type Description
s string

The string to capitalize.
Source:
Returns:

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

Type
string

# (static) capitalizeHyphenated(s) → {string}

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.
Source:
Returns:

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

Type
string

# (static) classify(s) → {string}

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.
Source:
Returns:

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

Type
string

# (static) compareBeans(beanA, beanB) → {Array.<string>}

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.
Source:
Returns:

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

Type
Array.<string>

# (static) convertNumericType(value, type) → {number}

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
Source:
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.
Source:
Returns:

A value of the same type as the input.

Type
*

# (static) doWhen(condition, callback, paramsopt, scopeopt)

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 Attributes 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.
Source:

# (static) extendClass(cache, defaultBase, className, controller, platformNamespace) → {Object}

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.
Source:
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.
Source:

# (static) formatName(params, format) → {string}

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]).
Source:
Returns:

Formatted string.

Type
string

# (static) formatNameLocale(params) → {string}

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.
Source:
Returns:

Formatted string.

Type
string

# (static) formatNameModel(module, data, formatopt) → {string}

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 Attributes 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.
Source:
Returns:

The formatted full name string.

Type
string

# (static) formatNumber(value, round, precision, numberGroupSeparator, decimalSeparator, toStringOnly) → {string}

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.
Source:
Returns:

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

Type
string

# (static) formatNumberLocale(value) → {string}

Formats a number according to the current user locale.

Parameters:
Name Type Description
value number

Value to format.
Source:
Returns:

Formatted number.

Type
string

# (static) formatString(format, args) → {string}

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

Parameters:
Name Type Description
format string

String to format.
args string

Arguments to replace.
Source:
Returns:

Formatted string.

Type
string

# (static) generateUUID() → {string}

Generates and returns a UUID according to RFC 4122.

Source:
Returns:

A UUID.

Type
string

# (static) getChangedProps(data1, data2, strictopt) → {Object}

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

Parameters:
Name Type Attributes 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.
Source:
Returns:

Hash of fields from data1 which are different from data2.

Type
Object

# (static) getParentLayout(component) → {View/Layout}

Gets the layout container for the given component.

Parameters:
Name Type Description
component View/Component

The component whose layout you want.
Source:
Returns:

The layout container for the given component.

Type
View/Layout

# (static) getTimestamp(dateValueopt, optionsopt) → {string}

Returns ISO8601 timestamp in UTC time.

Parameters:
Name Type Attributes Default Description
dateValue string | number <optional>
 new Date()

Date string or raw msec number.
options Object <optional>
 {}

Extra parameters.

Properties
Name Type Attributes Default Description
msecPrecision boolean <optional>
 false

If true, include milliseconds in the output.
Source:
Returns:

Passed date or current date converted to UTC timezone.

Type
string

# (static) hardRefresh()

Performs a hard refresh of the current page.

Source:

# (static) hasDefaultValueChanged(attribute, bean) → {boolean}

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.
Source:
Returns:

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

Type
boolean

# (static) isConnectivityError(ajaxError) → {boolean}

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

Parameters:
Name Type Description
ajaxError Api.HttpError

AJAX error.
Source:
Returns:

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

Type
boolean

# (static) isDirectionRTL(value) → {boolean}

Checks if the value should be rendered in RTL.

Parameters:
Name Type Description
value string

The value to check.
Source:
Returns:

true if the string is in a RTL language.

Type
boolean

# (static) isSortable(module, fieldViewdef) → {boolean}

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 Attributes 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.
Source:
Returns:

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

Type
boolean

# (static) isValidEmailAddress(address) → {boolean}

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.
Source:
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) → {string}

Escapes a given string for use in a JavaScript regex.

Parameters:
Name Type Description
string string

The string to escape.
Source:
Returns:

string escaped.

Type
string

# (static) stripHttpPrefix(url) → {string}

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

Parameters:
Name Type Description
url string

Input url.
Source:
Returns:

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

Type
string

# (static) unformatNumberString(numberString, numberGroupSeparator, decimalSeparator, toFloatopt) → {string}

Unformats number strings.

Parameters:
Name Type Attributes 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.
Source:
Returns:

Formatted number string.

Type
string

# (static) unformatNumberStringLocale(value, toFloatopt) → {string}

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

Parameters:
Name Type Attributes Default Description
value string

The number string to unformat.
toFloat boolean <optional>
 false

If true, convert string to float value.
Source:
Returns:

The formatted value.

Type
string

# (static) versionCompare(v1, v2, operatoropt) → {number|boolean}

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 Attributes 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.
Source:
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