Utils

(utils)

Methods Summarized

Type	Name	Summary
Array	base64ToBytes(base64String:)	Return the byte array representation of the Base64 value
String	base64ToString(base64String:)	Return the String representation of the Base64 value
String	bytesToBase64(byteArray:)	Return the Base64 value representation of the byteArray
String	bytesToHex(bytearray)
String	bytesToString(byteArray:)	Return the string conversion of the byteArray
String	dateFormat(date, format)	Format a date object to a text representation.
String	dateFormat(date, format, timezone)	Format a date object to a text representation using the format and timezone given.
String	dateFormat(date, format, language, country)	Format a date object to a text representation.
String	dateFormat(date, format, timezone, language, country)	Format a date object to a text representation using the format, timezone, language and country given.
String	getUnicodeCharacter(unicodeCharacterNumber)	Returns a string containing the character for the unicode number.
Boolean	hasRecords(foundset)	Returns true if the (related)foundset exists and has records.
Boolean	hasRecords(record, relationString)	Returns true if the (related)foundset exists and has records.
Array	hexToBytes(hex)
String	hexToString(hex)
Boolean	isMondayFirstDayOfWeek()	Returns true when Monday is the first day of the week for your current locale setting.
String	numberFormat(number, digits)	Format a number to have a defined fraction.
String	numberFormat(number, digits, language, country)	Format a number to have a defined fraction.
String	numberFormat(number, format)	Format a number to specification.
String	numberFormat(number, format, language, country)	Format a number to specification.
Date	parseDate(date, format)	Parse a string to a date object.
Date	parseDate(date, format, timezone)	Parse a string to a date object.
Date	parseDate(date, format, language, country)	Parse a string to a date object.
Date	parseDate(date, format, timezone, language, country)	Parse a string to a date object.
String	stringEscapeMarkup(textString)	Returns the escaped markup text (HTML/XML).
String	stringEscapeMarkup(textString, escapeSpaces)	Returns the escaped markup text (HTML/XML).
String	stringEscapeMarkup(textString, escapeSpaces, convertToHtmlUnicodeEscapes)	Returns the escaped markup text (HTML/XML).
String	stringFormat(text_to_format, parameters)	Formats a string according to format specifiers and arguments.
String	stringFormat(text, format)	Format a string using mask.
String	stringIndexReplace(text, i_start, i_size, replacement_text)	Replaces a portion of a string with replacement text from a specified index.
String	stringInitCap(text)	Returns all words starting with capital chars.
String	stringLeft(text, i_size)	Returns a string with the requested number of characters, starting from the left.
String	stringLeftWords(text, numberof_words)	Returns the number of words, starting from the left.
String	stringMD5HashBase16(textString)	Returns the md5 hash (encoded as base16) for specified text.
String	stringMD5HashBase64(textString)	Returns the md5 hash (encoded as base64) for specified text.
String	stringMiddle(text, i_start, i_size)	Returns a substring from the original string.
String	stringMiddleWords(text, i_start, numberof_words)	Returns a substring from the original string.
String	stringPBKDF2Hash(textString)	Returns the PBKDF2 hash for specified text.
String	stringPBKDF2Hash(textString, iterations)	Returns the PBKDF2 hash for specified text.
Number	stringPatternCount(text, toSearchFor)	Returns the number of times searchString appears in textString.
Number	stringPosition(textString, toSearchFor, i_start, i_occurrence)	Returns the position of the string to search for, from a certain start position and occurrence.
String	stringReplace(text, search_text, replacement_text)	Replaces a portion of a string with replacement text.
String	stringReplaceTags(text, scriptable)	Returns the text with %%tags%% replaced, based on provided record or foundset or form.
String	stringRight(text, i_size)	Returns a string with the requested number of characters, starting from the right.
String	stringRightWords(text, numberof_words)	Returns the number of words, starting from the right.
String	stringToBase64(string:)	Return the Base64 representation of the string
Array	stringToBytes(string:)	Return the byte array representation of the string
String	stringToHex(string)
Number	stringToNumber(textString)	Filters characters out of from a string and leaves digits, returns the number.
Number	stringToNumber(textString, decimalSeparator)	Filters characters out of from a string and leaves digits, returns the number.
String	stringTrim(textString)	Returns the string without leading or trailing spaces.
Number	stringWordCount(text)	Returns the number of words in the text string.
Date	timestampToDate(date)	Returns a datestamp from the timestamp (sets hours,minutes,seconds and milliseconds to 0).
Boolean	validatePBKDF2Hash(password, hash)	Validates the given password against the given hash.

Methods Detailed

base64ToBytes(base64String:)

Return the byte array representation of the Base64 value

Parameters

• Object base64String: the Base64 encoded string to convert to byte array

Returns: Array byteArray representation of the base64 string using UTF-8 charset for conversion

Sample

var string = utils.base64ToBytes(base64String);

base64ToString(base64String:)

Return the String representation of the Base64 value

Parameters

• Object base64String: the Base64 value to convert to String

Returns: String String decoded representation of the Base64 value using UTF-8 charset for conversion

Sample

var string = utils.base64ToString(base64Value);

bytesToBase64(byteArray:)

Return the Base64 value representation of the byteArray

Parameters

• Object byteArray: the byte array to convert to Base64 value

Returns: String Base64 representation of the byte array using UTF-8 charset for conversion

Sample

var string = utils.bytesToBase64(byteArray);
x`

bytesToHex(bytearray)

Parameters

• Array bytearray the byte array to convert to hex encoded string

Returns: String returns hex encoded string from bytearray

Sample

var string = utils.bytesToHex(byteArray);

bytesToString(byteArray:)

Return the string conversion of the byteArray

Parameters

• Object byteArray: the byte array to convert to

Returns: String string representation of the byte array using UTF-8 charset for conversion

Sample

var string = utils.bytesToString(byteArray);

dateFormat(date, format)

Format a date object to a text representation.
This will format with the system timezone for the webclient
For NGClient it will use the timezone of the client, the same goes for the Smartclient (but that is the system timezone)
see #dateFormat(Date,String,String) for using the actual clients timezone.

Format can be a string like: 'dd-MM-yyyy' , 'dd-MM-yyyy HH:mm' , 'MM/dd/yyyy', 'MM/dd/yyyy hh:mm aa', 'dd.MM.yyyy'.
Symbols meaning is:
 G        era designator
 y        year
 Y        week year
 M        month in year
 d        day in month
 h        hour in am/pm (1~12)
 H        hour in day (0~23)
 m        minute in hour
 s        second in minute
 S        millisecond
 E        day in week
 D        day in year
 F        day of week in month
 w        week in year
 W        week in month
 a        am/pm marker
 z        time zone
 k        hour in day (1~24)
 K        hour in am/pm (0~11)

Parameters

• Date date the date

• String format the format to output

Returns: String the date as text

Sample

var formattedDateString = utils.dateFormat(dateobject,'EEE, d MMM yyyy HH:mm:ss');

dateFormat(date, format, timezone)

Format a date object to a text representation using the format and timezone given.
If the timezone is not given the timezone of the client itself will be used.
see i18n.getAvailableTimeZoneIDs() to get a timezone string that can be used.

Format can be a string like: 'dd-MM-yyyy' , 'dd-MM-yyyy HH:mm' , 'MM/dd/yyyy', 'MM/dd/yyyy hh:mm aa', 'dd.MM.yyyy'
Symbols meaning is:
 G        era designator
 y        year
 Y        week year
 M        month in year
 d        day in month
 h        hour in am/pm (1~12)
 H        hour in day (0~23)
 m        minute in hour
 s        second in minute
 S        millisecond
 E        day in week
 D        day in year
 F        day of week in month
 w        week in year
 W        week in month
 a        am/pm marker
 z        time zone
 k        hour in day (1~24)
 K        hour in am/pm (0~11)

Parameters

• Date date the date

• String format the format to output

• String timezone The timezone string to use to parse the date (like GMT+3), if null then the timezone of the current client is used.

Returns: String the date as text

Sample

var formattedDateString = utils.dateFormat(dateobject,'EEE, d MMM yyyy HH:mm:ss', "UTC");

dateFormat(date, format, language, country)

Format a date object to a text representation.
This will format with the system timezone for the webclient
With language and/or country the locale will be created.
For NGClient it will use the timezone of the client, the same goes for the Smartclient (but that is the system timezone)
see #dateFormat(Date,String,String) for using the actual clients timezone.

Format can be a string like: 'dd-MM-yyyy' , 'dd-MM-yyyy HH:mm' , 'MM/dd/yyyy', 'MM/dd/yyyy hh:mm aa', 'dd.MM.yyyy'.
Symbols meaning is:
 G        era designator
 y        year
 Y        week year
 M        month in year
 d        day in month
 h        hour in am/pm (1~12)
 H        hour in day (0~23)
 m        minute in hour
 s        second in minute
 S        millisecond
 E        day in week
 D        day in year
 F        day of week in month
 w        week in year
 W        week in month
 a        am/pm marker
 z        time zone
 k        hour in day (1~24)
 K        hour in am/pm (0~11)

Parameters

• Date date the date

• String format the format to output

• String language language used to create locale

• String country country used along side language to create the locale

Returns: String the date as text

Sample

var formattedDateString = utils.dateFormat(dateobject,'EEE, d MMM yyyy HH:mm:ss', "fr", "CA");

dateFormat(date, format, timezone, language, country)

Format a date object to a text representation using the format, timezone, language and country given.
With the language and country given, the locale will be created.
If the timezone is not given the timezone of the client itself will be used.
see i18n.getAvailableTimeZoneIDs() to get a timezone string that can be used.

Format can be a string like: 'dd-MM-yyyy' , 'dd-MM-yyyy HH:mm' , 'MM/dd/yyyy', 'MM/dd/yyyy hh:mm aa', 'dd.MM.yyyy'
Symbols meaning is:
 G        era designator
 y        year
 Y        week year
 M        month in year
 d        day in month
 h        hour in am/pm (1~12)
 H        hour in day (0~23)
 m        minute in hour
 s        second in minute
 S        millisecond
 E        day in week
 D        day in year
 F        day of week in month
 w        week in year
 W        week in month
 a        am/pm marker
 z        time zone
 k        hour in day (1~24)
 K        hour in am/pm (0~11)

Parameters

• Date date the date

• String format the format to output

• String timezone the timezone to use the format, if null then current client timezone is used.

• String language language used to create locale

• String country country used along side language to create the locale

Returns: String the date as text

Sample

var formattedDateString = utils.dateFormat(dateobject,'EEE, d MMM yyyy HH:mm:ss', "UTC", "fr", "CA");

getUnicodeCharacter(unicodeCharacterNumber)

Returns a string containing the character for the unicode number.

Parameters

• Number unicodeCharacterNumber the number indicating the unicode character

Returns: String a string containing the unicode character

Sample

//returns a big dot
var dot = utils.getUnicodeCharacter(9679);

hasRecords(foundset)

Returns true if the (related)foundset exists and has records. Another use is, to pass a record and qualified relations string to test multiple relations/foundset at once

Parameters

• JSFoundSet foundset the foundset to be tested

Returns: Boolean true if exists

Sample

//test the orders_to_orderitems foundset
if (myElement.hasRecords(orders_to_orderitems))
{
	//do work on relatedFoundSet
}
//test the orders_to_orderitems.orderitems_to_products foundset to be reached from the current record
//if (myElement.hasRecords(foundset.getSelectedRecord(),'orders_to_orderitems.orderitems_to_products'))
//{
//	//do work on deeper relatedFoundSet
//}

hasRecords(record, relationString)

Returns true if the (related)foundset exists and has records. Another use is, to pass a record and qualified relations string to test multiple relations/foundset at once

Parameters

• JSRecord record A JSRecord to test.

• String relationString The relation name.

Returns: Boolean true if the foundset/relation has records.

Sample

//test the orders_to_orderitems foundset
if (myElement.hasRecords(orders_to_orderitems))
{
	//do work on relatedFoundSet
}
//test the orders_to_orderitems.orderitems_to_products foundset to be reached from the current record
//if (myElement.hasRecords(foundset.getSelectedRecord(),'orders_to_orderitems.orderitems_to_products'))
//{
//	//do work on deeper relatedFoundSet
//}

hexToBytes(hex)

Parameters

• String hex hex encoded string to be decoded into a byte array.

Returns: Array a byte array from hex encoded string

Sample

var array = utils.hexToBytes(hex);

hexToString(hex)

Parameters

• String hex ;

Returns: String returns decoded string from hex

Sample

var string = utils.hexToString(hex);

isMondayFirstDayOfWeek()

Returns true when Monday is the first day of the week for your current locale setting.

Returns: Boolean true if Monday is first day of the week in current locale

Sample

if(utils.isMondayFirstDayOfWeek())
{
	//a date calculation
}

numberFormat(number, digits)

Format a number to have a defined fraction.

Parameters

• Number number the number to format

• Number digits nr of digits

Returns: String the resulting number in text

Sample

var textalNumber = utils.numberFormat(16.749, 2); //returns 16.75

numberFormat(number, digits, language, country)

Format a number to have a defined fraction.

Parameters

• Number number the number to format

• Number digits nr of digits

• String language language used to create locale

• String country country used along side language to create the locale

Returns: String the resulting number in text

Sample

var textalNumber = utils.numberFormat(16.749, 2, "fr", "CA"); //returns 16.75

numberFormat(number, format)

Format a number to specification.

Parameters

• Number number the number to format

• String format the format

Returns: String the resulting number in text

Sample

var textalNumber2 = utils.numberFormat(100006.749, '#,###.00'); //returns 100,006.75

numberFormat(number, format, language, country)

Format a number to specification.

Parameters

• Number number the number to format

• String format the format

• String language language used to create locale

• String country country used along side language to create the locale

Returns: String the resulting number in text

Sample

var textalNumber2 = utils.numberFormat(100006.749, '#,###.00', "fr", "CA"); //returns 100,006.75

parseDate(date, format)

Parse a string to a date object. This parses the date using the TimeZone of the server Format can be a string like: 'dd-MM-yyyy' , 'dd-MM-yyyy HH:mm' , 'MM/dd/yyyy', 'MM/dd/yyyy hh:mm aa', 'dd.MM.yyyy'

Parameters