[intro]     [up]

JavaScriptUtil - Top-Level Functions

All top-level functions declared on this script are detailed here


Object manipulation functions
 
booleanValue
Determine if the object represents a true value. If is a boolean, return it. Otherwise, check it's first character for the trueChars parameter, ingnoring case. The default are T1YS.
Arguments
Name Type Default Description
object Object   The object
trueChars String T1YS The characters for the object be considered true
 
debug
Returns all properties in the object, sorted or not, with the separator between them
Arguments
Name Type Default Description
object Object   The object
separator String \n The separator between properties
sort boolean true Will the properties be sorted?
includeObject boolean true Will the object.toString() be included?
objectSeparator String A line The text separating the object.toString() from the properties
 
decode
Returns an argument depending on the value of the first argument. Example: decode(param, 1, 'A', 2, 'B', 'C'). When param == 1, returns 'A'.When param == 2, return 'B'. Otherwise, return 'C'
Arguments
Name Type Default Description
object Object   The object to test
(additional variable arguments) Object   The arguments to test or return
 
functionName
Returns the name of a function, given a function reference. If the parameter is an object, uses it's constructor function
Arguments
Name Type Default Description
funct Object   The function or object reference
unnamed String [unnamed] The String returned when the function is unnamed
 
getObject
Returns the reference to a named object
Arguments
Name Type Default Description
objectName String or Object   The object's name or id. When a reference is passed instead of a String, return the reference itself
source Object self The reference to the object where to search in
 
ifEmpty
Returns the first object if it is not empty (according to the isEmpty function), or the second object otherwise
Arguments
Name Type Default Description
object Object   The object
emptyValue Object   The object to return if the first one is empty
 
ifNull
Returns the first object if it is not null, or the second object otherwise
Arguments
Name Type Default Description
object Object   The object
nullValue Object   The object to return if the first one is null
 
invoke
Invokes a given function with the given arguments. It's useful when you have a variable number of arguments and have to invoke a function passing each element as a different argument, not as a single argument as an array
Arguments
Name Type Default Description
functionName String or Function   The function name or reference
args Object or Object[]   The arguments. When null, invokes without parameters. When an object, invokes with a single argument. When an array, invokes with each element as a different argument
 
invokeAsMethod
Invokes a given function with the given arguments as if it were a method of the given object
Arguments
Name Type Default Description
object Object   The object that will invoke the method
functionName String or Function   The function name or reference to be invoked as method
args Object or Object[]   The arguments. When null, invokes without parameters. When an object, invokes with a single argument. When an array, invokes with each element as a different argument
 
isEmpty
Returns if the object is null, an empty string, undefined or NaN
Arguments
Name Type Default Description
object Object   The object
 
isUndefined
Returns if the object is undefined
Arguments
Name Type Default Description
object Object   The object to test
 
select
Returns an argument depending on the boolean value of the prior argument. Example: select(a > b, 'A', b > a, 'B', 'Equals'). When a > b, returns 'A'. When b > a, return 'B'. Otherwise, return 'Equals'
Arguments
Name Type Default Description
(variable arguments) Object   The arguments to test or return


Form elements manipulation functions
 
addOption
Adds an option to a select
Arguments
Name Type Default Description
select Object or String   The select reference, id or name
options Option or Object   The Option. When not an Option instance, uses the textProperty and labelProperty to build a new Option
sort boolean false Will the options be sorted?
textProperty String text The object property, when not an Option, to read the text
valueProperty String value The object property, when not an Option, to read the value
selectedProperty String selected The object property, when not an Option, to read if the option is selected
 
addOptions
Adds all options from the array to a select
Arguments
Name Type Default Description
select Object or String   The select reference, id or name
options Option[] or Object[]   The Options array. When an element is not an Option instance, uses the textProperty and labelProperty to build a new Option
sort boolean false Will the options be sorted?
textProperty String text The object property, when not an Option, to read the text
valueProperty String value The object property, when not an Option, to read the value
selectedProperty String selected The object property, when not an Option, to read if the option is selected
 
checkAll
Checks (or unchecks) all checkboxes
Arguments
Name Type Default Description
object Object or String   The object reference, id or name
flag boolean   Will the checkboxes be checked (true) or unchecked (false)?
 
clearOptions
Removes all options from a select
Arguments
Name Type Default Description
select Object or String   The select reference, id or name
 
compareOptions
Function used to compare two options by their text
Arguments
Name Type Default Description
opt1 Object   The first Option
opt2 Object   The second Option
 
getCaret
Returns the caret position. When a range is selected, returns the range end. For IE, requires prepareForCaret() to be first called on the object
Arguments
Name Type Default Description
object Object or String   The object reference, id or name
 
getInputSelection
Returns an input's selected text. For IE, requires prepareForCaret() to be first called on the object
Arguments
Name Type Default Description
object Object or String   The object reference, id or name
 
getInputSelectionRange
Returns an input's selected range. For IE, requires prepareForCaret() to be first called on the object
Arguments
Name Type Default Description
object Object or String   The object reference, id or name
 
getValue
Returns an object value. The object may be an form input or an HTML element
Arguments
Name Type Default Description
object Object or String   The object reference, id or name
 
isCaretSupported
Returns if caret operations are supported in the given object
Arguments
Name Type Default Description
object Object or String   The object reference, id or name
 
isInputSelectionSupported
Returns if input selection operations are supported in the given object
Arguments
Name Type Default Description
object Object or String   The object reference, id or name
 
prepareForCaret
Prepares the input object to use caret or selection manipulation functions on Internet Explorer. Should be called only once on each input
Arguments
Name Type Default Description
object Object or String   The object reference, id or name
 
replaceSelection
Replaces the selected text for a new one. On IE, only works if the object has focus. For IE, requires prepareForCaret() to be first called on the object
Arguments
Name Type Default Description
object Object or String   The object reference, id or name
string String   The new text
 
selectString
Selects a given string on the input text
Arguments
Name Type Default Description
object Object or String   The object reference, id or name
string String   The string to select
 
setCaret
Sets the caret to the specified position
Arguments
Name Type Default Description
object Object or String   The object reference, id or name
pos Numeric   The caret position
 
setCaretToEnd
Sets the caret to the text end
Arguments
Name Type Default Description
object Object or String   The object reference, id or name
 
setCaretToStart
Sets the caret to the text start
Arguments
Name Type Default Description
object Object or String   The object reference, id or name
 
setInputSelectionRange
Sets the selection range on an input field
Arguments
Name Type Default Description
object Object or String   The object reference, id or name
start Numeric   The selection start
end Numeric   The selection end
 
setOptions
Sets a select's options from an array
Arguments
Name Type Default Description
select Object or String   The select reference, id or name
options Option[]   The Options array
addEmpty boolean or String false When boolean, add an empty option when true. When a string, add an empty option with the given text
sort boolean false Will the options be sorted?
textProperty String text The object property, when not an Option, to read the text
valueProperty String value The object property, when not an Option, to read the value
selectedProperty String selected The object property, when not an Option, to read if the option is selected
 
setValue
Sets an object value. If the value and the object are arrays, set each value
Arguments
Name Type Default Description
object Object or String   The object reference, id or name
value Object   The new value
 
sortOptions
Sorts the options on a Select
Arguments
Name Type Default Description
select Object or String   The select reference, id or name
sortFunction Function compareOptions The comparator function
 
transferOptions
Transfers options from a select to another. May transfer all or just the selected ones
Arguments
Name Type Default Description
select Object or String   The select reference, id or name
dest Object   The destination Select
all boolean false Will transfer all options (true) or only the selected ones (false)?
sort boolean false Will the options be sorted?


Array manipulation functions
 
arrayConcat
Returns an array containing all elements of both arrays
Arguments
Name Type Default Description
array1..arrayN Array or Object   The arrays or objetcs to concatenate
 
arrayEquals
Returns an the two arrays have exactly the same elements
Arguments
Name Type Default Description
array1 Array   The first array
array2 Array   The second array
 
ensureArray
Ensurea an array is returned. When the object is null or undefined, returns an empty array. When an array return it. Otherwise, return an array with the argument in
Arguments
Name Type Default Description
object Object   The object to test
 
inArray
Returns if the object is in the array
Arguments
Name Type Default Description
object Object   The object to search
array Array   The array where to search
 
indexOf
Returns the first index of the object within the array
Arguments
Name Type Default Description
object Object   The object to search
array Array   The array where to search
startingAt Number 0 The initial position
 
removeFromArray
Removes all occurrences of the given objects is in the array
Arguments
Name Type Default Description
array Array   The array
object1..objectN Object   The objects to remove


Event manipulation functions
 
observeEvent
Adds an event listener to a given object. The function may safely use this to refer to the object
Arguments
Name Type Default Description
object Object   The object that generates the events
eventName String   An event name, like: click, focus, blur or keypress
handler Function   The event handler function. May use this safely to refer to the object (even in Internet Explorer)
 
preventDefault
Makes the given event to not be completed (example: on keypress, the key is not accepted)
Arguments
Name Type Default Description
event Event   The event
 
stopPropagation
Makes the event to stop propagating to innermost elements
Arguments
Name Type Default Description
event Event   The event
 
typedCode
Returns the key code of the given event. If you need the type char, use String.fromCharCode(typedCode(event))
Arguments
Name Type Default Description
event Event   The event


String manipulation functions
 
capitalize
Capitalizes a String
Arguments
Name Type Default Description
string String   The String
separators String JST_CHARS_WHITESPACE + '.?!' An String containing the word separator characters
 
crop
Removes a specified number of characters from a String after a specified position
Arguments
Name Type Default Description
string String   The String
pos Number   The initial position
size Number 1 The String
 
escapeCharacters
Escapes the string's special characters to their escaped form ('\\' to '\\\\', '\n' to '\\n', ...) and the extraChars are escaped via unicode (\uXXXX, where XXXX is the charcode)
Arguments
Name Type Default Description
string String   The String
extraChars String   An String with the extra characters to be encoded in the \uXXXX form
onlyExtra boolean   If true, will only process the extra characters
 
insertString
Insert a String on another
Arguments
Name Type Default Description
string String   The original String
pos Number   The insert position
value String   The String to be inserted
 
lcrop
Removes a specified number of characters from the beggining of a String
Arguments
Name Type Default Description
string String   The String
size Number 1 The String
 
left
Return 'n' charactes from the string's left side
Arguments
Name Type Default Description
string String   The String
count Number   The number of characters
 
lpad
Make the string have the specified length, completing with the specified character on the left. If the String is greater than the specified size, it is truncated to it, using the leftmost characters
Arguments
Name Type Default Description
string String   The String
size Number   The expected size
char String An space The character used to complete the String
 
ltrim
Removes all specified characters on the String's left side
Arguments
Name Type Default Description
string String   The String
chars String JST_CHARS_WHITESPACE The string containing all characters to be removed
 
mid
Return 'n' charactes from the string's specified position
Arguments
Name Type Default Description
string String   The String
pos Number   The initial position
count Number   The number of characters
 
onlyAlpha
Return if the string has only letters or numbers
Arguments
Name Type Default Description
string String   The String
 
onlyLetters
Return if the string has only letters
Arguments
Name Type Default Description
string String   The String
 
onlyNumbers
Return if the string has only numbers
Arguments
Name Type Default Description
string String   The String
 
onlySpecified
Return if the string has only the specified characters
Arguments
Name Type Default Description
string String   The String
specified String   The specified characters
 
rcrop
Removes a specified number of characters from the end of a String
Arguments
Name Type Default Description
string String   The String
size Number 1 The String
 
repeat
Repeats the given string a number of times
Arguments
Name Type Default Description
string String   The String
times Numeric   The number of times to repeat
 
replaceAll
Replaces all the occurences in the string
Arguments
Name Type Default Description
find String   What to find
replace String   What to br replaced
 
right
Return 'n' charactes from the string's right side
Arguments
Name Type Default Description
string String   The String
count Number   The number of characters
 
rpad
Make the string have the specified length, completing with the specified character on the right. If the String is greater than the specified size, it is truncated to it, using the leftmost characters
Arguments
Name Type Default Description
string String   The String
size Number   The expected size
char String An space The character used to complete the String
 
rtrim
Removes all specified characters on the String's right side
Arguments
Name Type Default Description
string String   The String
chars String JST_CHARS_WHITESPACE The string containing all characters to be removed
 
trim
Removes all specified characters on both sides of the String
Arguments
Name Type Default Description
string String   The String
chars String JST_CHARS_WHITESPACE The string containing all characters to be removed
 
unescapeCharacters
Unescapes the string, changing the special characters to their unescaped form ('\\\\' to '\\', '\\n' to '\n', '\\\\uXXXX' to the ASC(XXXX), ...)
Arguments
Name Type Default Description
string String   The String
extraChars String   An String with the extra characters to be encoded in the \uXXXX form


Date manipulation functions
 
dateAdd
Adds a given amount on a given date field
Arguments
Name Type Default Description
date Date   The Date
amount Number 1 The amount to add
field enum JST_FIELD_DAY The field
 
dateDiff
Returns the difference, as in date2 - date1
Arguments
Name Type Default Description
date1 Date   The first Date
date2 Date   The second Date
field enum JST_FIELD_DAY The field
 
getDateField
Returns the value of a given date field
Arguments
Name Type Default Description
date Date   The Date
field enum JST_FIELD_DAY The field
 
getFullYear
Returns the full year, given a 2 digit year. 50 or less returns 2050
Arguments
Name Type Default Description
year Number   The year
 
getMaxDay
Returns the maximum day of a given month and year
Arguments
Name Type Default Description
month Number   The month
year Number   The year
 
setDateField
Sets the value of a given date field
Arguments
Name Type Default Description
date Date   The Date
field enum JST_FIELD_DAY The field
value Number   The new field value
 
truncDate
Truncates the date, setting all fields lower than the specified one to its minimum value
Arguments
Name Type Default Description
date Date   The Date
field enum JST_FIELD_DAY The field


Cookie manipulation functions
 
deleteCookie
Removes the specified cookie
Arguments
Name Type Default Description
name String   The cookie name
document Document self.document The document containing the cookie
 
readCookie
Reads the specified cookie
Arguments
Name Type Default Description
name String   The cookie name
document Document self.document The document containing the cookie
 
writeCookie
Writes the specified cookie
Arguments
Name Type Default Description
name String   The cookie name
value String   The new cookie value
document Document self.document The document containing the cookie
expires Date or boolean Until the browser is closed The expiration date, or false indicating it never expires
path String Unspecified The cookie path
domain String Unspecified The cookie domain
secure boolean false The cookie secure flag


Style manipulation functions
 
getOpacity
Returns an object opacity. This function is currently supported by Internet Explorer and Gecko based browsers only.
Arguments
Name Type Default Description
object Object or String   The object reference, id or name
 
setOpacity
Sets an object opacity, to a value ranging from 0 to 100. This function is currently supported by Internet Explorer (where it only works when the element's position is absolute) and Gecko based browsers only.
Arguments
Name Type Default Description
object Object or String   The object reference, id or name
value Numeric 100 The opacity value. Ranges from 0 to 100