Utils

Utils

General utilities class

Constructor

new Utils()

Source:

Members

(static) forceASCII :boolean

Source:
forceASCII forces ASCII representation of all text input. This solves the problem of Unicode characters being too long for an ASCII SQL column. If your database uses Unicode, then this should be set to false. If set to true, it should be set elsewhere so that this file can remain untouched.
Type:
  • boolean

(static) waitMessageStack

Source:
This is a stack for the Utils.waitMessage method. Each element contains a string which is the message at each nesting level.

Methods

(static) appendChild(tag, html) → {object}

Source:
Append html (as text) to the list of children of a node.

Parameters:
Name Type Description
tag object | string see above
html string the html to be
Returns:
the jQuery node
Type
object

(static) assureArray(x) → {Array}

Source:
When calling a SOAP web service, array returns are not arrays but single objects when there is only one element. (XML to Json problem). This function assures that an element is an array when one is expected.
Parameters:
Name Type Description
x
Returns:
Type
Array

(static) beep()

Source:
Emits an audible beep on the user's computer.

(static) cleanup()

Source:
Perform all cleanup operations between screens

(static) clearAllEnterContexts()

Source:
Clear all enter key contexts that have been created

(static) clearSomeControlValueChanged(executeFunction)

Source:
This function clears the state of some control value having been changed.

Also, if a function is attached (via the setSomeControlValueChangeFunction function), it will be executed if some value had changed and a true argument is passed to this function. The some-control-value-changed function will be passed a false.
Parameters:
Name Type Default Description
executeFunction true optional boolean

(static) cloneArrayShallow(ary) → {Array}

Source:
Perform a shallow clone on an array.
Parameters:
Name Type Description
ary
Returns:
shallow copy of ary
Type
Array

(static) convertToArray(obj) → {array}

Source:
Convert an object into an array. This is especially useful for the arguments variable.
Parameters:
Name Type Description
obj
Returns:
Type
array

(static) countProperties(obj) → {number}

Source:
Count properties associated with an object.
Parameters:
Name Type Description
obj
Returns:
Type
number

(static) didSomeControlValueChange() → {boolean}

Source:
Returns:
true if any control value changed, false otherwise
Type
boolean

(static) drop(s, n) → {string}

Source:
APL-like drop for strings.
Parameters:
Name Type Description
s string
n number
Returns:
Type
string

(static) eraseChildren(tag) → {object}

Source:
Erase all the child nodes.

Parameters:
Name Type Description
tag object | string see above
Returns:
the jQuery node
Type
object

(static) fileNameExtension(filename) → {string}

Source:
Get the extension of the file name. So, "abc.def" would return "def".
Parameters:
Name Type Description
filename string
Returns:
Type
string

(static) fixCapitalization(s) → {string}

Source:
This method attempts to correct incorrect word capitalization. It tries to assure that the first letter of each word is uppercase and the rest is lowercase. If the incoming string is already mixed-case, it leaves it alone.
Parameters:
Name Type Description
s string
Returns:
Type
string

(static) format(num, msk, wth, dp) → {string}

Source:
Numeric formatter. Takes a number and converts it to a nicely formatted String (for number in base 10). Correctly handles international formatting rules.
Parameters:
Name Type Description
num number number to be formatted
msk string format mask - any combination of the following:
  • B = blank if zero
  • C = add commas
  • L = left justify number
  • P = put parentheses around negative numbers
  • Z = zero fill
  • D = floating dollar or monetary symbol
  • M = monetary (same as 'D')
  • R = add a percent sign to the end of the number
wth number total field width (0 means auto)
dp number number of decimal places (-1 means auto)
Returns:
string the formatted String

example:

let r = Utils.format(-12345.348, "CP", 12, 2);

result in r: "(12,345.35)"

Type
string

(static) formatb(num, base, msk, wth, dp) → {string}

Source:
See:
Numeric formatter. Takes a number and converts it to a nicely formatted String in a specified number base.
Parameters:
Name Type Description
num number number to be formatted
base number numeric base (like base 2 = binary, 16=hex...)
msk string format mask - any combination of the following:
  • B = blank if zero
  • C = add commas
  • L = left justify number
  • P = put parentheses around negative numbers
  • Z = zero fill
  • D = floating dollar sign
  • U = uppercase letters in conversion
  • R = add a percent sign to the end of the number
wth number total field width (0 means auto)
dp number number of decimal places (-1 means auto)
Returns:
the formatted String

Example:

let r = Utils.formatb(-12345.348, 10, "CP", 12, 2);

result in r: "(12,345.35)"

Type
string

(static) formatSsn(s) → {string|null}

Source:
Formats a social security number into a standard format. If it is an invalid SSN, whatever is passed in is returned.
Parameters:
Name Type Description
s string | null
Returns:
Type
string | null

(static) getAndEraseData(key) → {*}

Source:
See:
Erase an application global data item returning its prior value.
Parameters:
Name Type Description
key string
Returns:
the value before it was erased
Type
*

(static) getAppUrl() → {string}

Source:
Returns the root URL of the application.
Returns:
Type
string

(static) getData(key) → {*}

Source:
See:
Retrieve the application global data associated with a key.
Parameters:
Name Type Description
key string
Returns:
Type
*

(static) getEmailFromAddressWithName(ad) → {string}

Source:
Returns the email portion of an email address with a name. For example, all of the following will return "abc.com": name@abc.com George Tall "Tall, George"
Parameters:
Name Type Description
ad string
Returns:
Type
string

(static) getFileUploadCount(id) → {number}

Source:
See:
Return the number of files the user selected for upload.
Parameters:
Name Type Description
id string the id of the control
Returns:
Type
number

(static) getFileUploadFormData(id) → {FormData}

Source:
See:
Creates and initializes a FormData instance used for file uploading. Before the FormData instance is sent, arbitrary additional data may be added by using fd.append(name, data)

where fd is the object return by this call.
Parameters:
Name Type Description
id string the id of the control
Returns:
Type
FormData

(static) getLocation() → {Promise.<GeolocationCoordinates>}

Source:
Get current location.
Returns:
or null
Type
Promise.<GeolocationCoordinates>

(static) getMilliseconds(dateField, timeField) → {number}

Source:
Return number of milliseconds since 1970 UTC from a date and time control.
Parameters:
Name Type Description
dateField string the ID of the date field
timeField string the ID of the time field
Returns:
Type
number

(static) getNameFromAddressWithName(ad) → {string}

Source:
Returns the name portion of an email address with a name. For example: name@abc.com -> "" -> "" George Tall -> "George Tall" "Tall, George" -> "Tall, George"
Parameters:
Name Type Description
ad string
Returns:
Type
string

(static) getPageArgv() → {object}

Source:
See:
Returns an object representing the values passed to the current screen by a parent screen.

This value remains constant through subsequent pushPage and popPage calls.
Returns:
Type
object

(static) getPageRetv() → {object}

Source:
See:
Returns an object representing the return value from the child screen.
Returns:
Type
object

(static) getURLParam(key) → {string}

Source:
Parse the URL string and extract the URL parameters.
Parameters:
Name Type Description
key string parameter name
Returns:
the parameter value or null if not there
Type
string

(static) globalEnterHandler(fun) → {function}

Source:
Set a global handler for the enter/return key. If fun is null, the enter function is cancelled.
Parameters:
Name Type Description
fun function the new enter function handler or null
Returns:
the previous enter function or null if none
Type
function

(static) htmlToText(html) → {string}

Source:
Convert an HTML string into a text string. Also convert Unicode to ASCII when possible.
Parameters:
Name Type Description
html
Returns:
Type
string

(static) isChangeChar(event) → {boolean}

Source:
Returns true if the key hit is the kind of keyboard character that changes the value. (Textarea will need to check 'Enter' too.)
Parameters:
Name Type Description
event
Returns:
Type
boolean

(static) isOnline() → {boolean}

Source:
Is the user's computer connected to the Internet?
Returns:
Type
boolean

(static) isValidDomain(d) → {boolean}

Source:
Test the validity of a domain name.
Parameters:
Name Type Description
d string the domain to be tested
Returns:
Type
boolean

(static) isValidEmailAddress(add) → {boolean}

Source:
Test the validity of an email address.
Parameters:
Name Type Description
add string the email address to be tested
Returns:
Type
boolean

(static) isValidEmailAddressWithName(ad) → {boolean}

Source:
Determines if an email address with or without a name is valid. This accepts things like: name@abc.com George Tall "Tall, George"
Parameters:
Name Type Description
ad string
Returns:
Type
boolean

(static) isValidSsn(s) → {boolean}

Source:
Return true if the passed in string is a valid SSN.
Parameters:
Name Type Description
s string | null
Returns:
Type
boolean

(static) loadPage(page, tag, initialFocus, argv, retv)

Source:
See:
Loads a new HTML/JS page. The new page will replace the body of the current page. Also, the loaded code is processed for custom tags / components.

.html and .js are appended to page to determine what to load. The HTML file is loaded first and then the JS file.
Parameters:
Name Type Description
page string path to the page to be loaded
tag string optional ID of div to fill (if empty, "body" tag is used)
initialFocus string optional, ID of control to set initial focus on
argv object arguments for the page being loaded
retv object return value array from child screen (mainly used internally)

(static) makeDraggable(header, content)

Source:
This makes a window draggable.
Parameters:
Name Type Description
header jQuery object
content jQuery object

(static) newEnterContext()

Source:
Create a new enter key context.

(static) popEnterContext()

Source:
Destroy all grids in last context and remove the context

(static) popPage(retv, howmany)

Source:
See:
Re-load the prior screen.

Be careful. While this function loads the old screen, execution continues after this call and not in the new screen until this screen's code exits.
Parameters:
Name Type Default Description
retv object values being returned to the prior screen
howmany number 1 how many screens to go back (default 1)

(static) popup_close()

Source:
See:
Close the most recent modal popup.

(static) popup_open(id, focus_ctl, replace)

Source:
See:
Open a modal popup window identified by id id.

If replace is used and there isn't a prior popup, it just acts like a plain open. So, if the popup is being used as a wizard, all the opens should set this to true.
Parameters:
Name Type Default Description
id string the id of the popup to evoke
focus_ctl string null optional, control to set initial focus
replace boolean false optional, if true, replace prior popup with this popup at the same coordinates

(static) popup_set_height(id, height)

Source:
Dynamically change the height of a popup. Only works after a popup is open.
Parameters:
Name Type Description
id string popup id
height string like "200px"

(static) popup_set_width(id, width)

Source:
Dynamically change the width of a popup. Only works after a popup is open.
Parameters:
Name Type Description
id string popup id
width string like "200px"

(static) pushPage(page, tag, initialFocus, argv)

Source:
See:
Load a new screen but also remember what is loaded so that it can be returned to.
Parameters:
Name Type Description
page string path to the page to be loaded
tag string optional ID of div to fill (if empty, "body" tag is used)
initialFocus string optional, ID of control to set initial focus on
argv object values being passed to the new screen

(static) rescan()

Source:
Rescan the HTML file and replace KISS components with HTML components. This needs to be done each time new KISS controls are attached. This method is mainly used internally. However, it may be useful when dynamically adding controls to the DOM. At the end of those additions, this method would be called to activate the Kiss custom HTML tags.

(static) saveData(key, val)

Source:
See:
Save an application global data item associated with a key.
Parameters:
Name Type Description
key string
val *

(static) setEnterFunction(fun)

Source:
Function to execute if the user hits the enter key
Parameters:
Name Type Description
fun

(static) setSomeControlValueChangeFunction(fun)

Source:
Used for setting an application specific function to be executed the first time any control value is changed by the user or if the change status is cleared. Other programmatic changes do not trigger this condition.

A null value may be passed in order to clear the function.

The function is passed a single boolean value. true means a control value has changed, and false if the state is being reset.
Parameters:
Name Type Description
fun function the function to be executed

(static) showMessage(title, message) → {Promise}

Source:
Display a popup window with a message to the user. The user will click "Ok" when they have read the message. If the title is 'Error' the popup will appear in red.
Parameters:
Name Type Description
title string appears on the title bar of the message window
message string the message to be displayed
Returns:
when popup disappears
Type
Promise

(static) showReport(url)

Source:
Displays a report given a URL from the back-end. Correctly handles dual server development situations.
Parameters:
Name Type Description
url string report url

(static) someControlValueChanged()

Source:
This function is called to indicate to the system that some control value changed by the user. Programmatic changed to not set this. It is mainly used internally as all the Kiss controls use this function.

If there is a function connected to some-control-value-changing via the setSomeControlValueChangeFunction function, it will be executed the first time only that any control value is changed. Subsequent changes will not trigger the some-control-value-changing function. The some-control-value-changing function is passed the single argument true.

Non-Kiss controls should call this function if their value changes.

(static) splitEmailAddresses(s) → {object}

Source:
Splits a string containing any number of full email addresses with possible names into an array where each element is a single address.
Parameters:
Name Type Description
s string
Returns:
an array with the separated email addresses
Type
object

(static) take(s, n) → {string}

Source:
APL-like take for strings.
Parameters:
Name Type Description
s string
n number
Returns:
Type
string

(static) textToHtml(text) → {string}

Source:
Converts a text string into a string suitable to HTML.
Parameters:
Name Type Description
text
Returns:
Type
string

(static) toASCII(str) → {str}

Source:
Converts a potentially non-ASCII string to ASCII.
Parameters:
Name Type Description
str
Returns:
Type
str

(static) toBase64(bytes) → {string}

Source:
See:
Convert a byte array to base64.

Taken from https://gist.github.com/jonleighton/958841
Parameters:
Name Type Description
bytes
Returns:
Type
string

(static) toggleFullscreen()

Source:
Toggle full screen mode. This is mainly good for tablets and phones. It doesn't make sense for desktops or laptops.

You can tell if it is a tablet or phone via: if (screen.width * screen.height < 1000000) ...

This function only works when it is attached to a button on the screen. This is a restriction placed on us by the browsers to assure the user is making the choice.

Note also that this does not work on an iPad. Apple doesn't allow it. They also make sure Chrome on an iPad doesn't work. Presumably this is to assure that browser apps don't compete against their app store.

This does work on Android devices.

(static) toNumber(v) → {number}

Source:
Turn undefined, null, NaN, "", a number, or a string into a number. Handles M and K suffix. Anything (except a valid string or number) becomes a zero.
Parameters:
Name Type Description
v
Returns:
Type
number

(static) useComponent(path)

Source:
Loads a component (new HTML element)
Parameters:
Name Type Description
path string back-end path to the component HTML and JS files.

(static) useTaglessComponent(path)

Source:
Initialize a tagless component.
Parameters:
Name Type Description
path string back-end path to the component

(static) uuid() → {string}

Source:
Create a new UUID.
Returns:
Type
string

(static) waitMessage(message)

Source:
Display a modal popup with a message. The message stays there until the application executes waitMessageEnd(). This method is used when the user needs to be notified to wait for a long-running process.

This method tracks nested wait messages. It displays the last one but shows previous ones once the last one has ended.
Parameters:
Name Type Description
message string the message to be displayed

(static) waitMessageEnd()

Source:
This terminates the wait message initiated by waitMessage() unless there is a previous one in which case it reverts to the previous one.

(static) yesNo(title, message, yesFun, noFun)

Source:
Display a modal popup that asks the user a yes/no question. The yesFun/noFun can be used, or this function returns a promise so that is can be used with async/await.
Parameters:
Name Type Default Description
title string text on the title bar of the popup
message string the question being asked
yesFun function null function that gets executed if the user clicks 'Yes'
noFun function null function that gets executed if the user clicks 'No'