|
Object: sapphire.util |
Description
API for utility methods and classes.
File
WEB-CORE\scripts\sapphirecore.js
Properties
None.
getAll |
| DEPRECATED | Deprecated in R5.2 (DM0503). Use sapphire.util.dom.getAll instead. The getAll method still works by redirecting to sapphire.util.dom.getAll. |
Functionality
Cross-browser method for obtaining all nodes/elements that are inside of an element. This resolves the crisis ensuing when one finds that the element.all method works in IE, but not in other browsers.
Parameters
| Parameter | Type | Description |
| oElement | Object | Element for which all children are obtained. |
Returns
Object Array.
evaluateExpression |
Functionality
Evaluates a string containing [] tokens and replaces them with the values. Similar to the EvaluationUtil.evaluate Java equivalent. This will work with field/column names, keyid1, sdcid and JavaScript strings (starting javascript:).
Parameters
| Parameter | Type | Description |
| sString | String | String to evaluate. |
Returns
Evaluated String.
|
Object: sapphire.util.number |
Description
Number conversion and formatting utility.
File
WEB-CORE\scripts\sapphirecore.js
Properties
None.
parseFraction |
Functionality
Converts a string fraction into decimal.
Parameters
| Parameter | Type | Description |
| sNumber | String | Takes a string representing a fraction in x y/z or y/z
format and converts it into a decimal that is returned.
If the fraction is invalid, a NaN is returned. |
Returns
Number.
number |
Functionality
Determines if fractions sould be considered valid numbers.
Parameters
| Parameter | Type | Description |
| sNumber | String | Takes a string of a number. |
| lAllowFractions | Boolean | Specifies whether or not you want to allow fractions as
valid numbers.
Returns true if the string is a valid number, false if not. |
Returns
Boolean.
|
Object: sapphire.util.array |
Description
String array utility. All of these are added as prototypes to the array object.
File
WEB-CORE\scripts\sapphirecore.js
Properties
None.
findInArray |
Functionality
Takes a string array and returns the index of the string. This method is also accessible as a prototype to Array: find(sValue, lIgnoreCase).
Parameters
| Parameter | Type | Description |
| saArray | String Array | String array input. |
| sValue | String | String to find in the array |
| lIgnoreCase | Boolean | Specifies whether or not the operation is case sensitive. |
Returns
Number.
toString |
Functionality
Converts an array into a string using the provided array and delimiter.
Parameters
| Parameter | Type | Description |
| saArray | String Array | Array to convert. |
| sDelim | String | Delimiter. |
Returns
None.
|
Object: sapphire.util.string |
Description
String utilities. All of these are added as prototypes to the array object.
File
WEB-CORE\scripts\sapphirecore.js
Properties
None.
escapeRegExp |
Functionality
Takes a regular expression string and escapes any special characters, then returns the escaped string.
Parameters
| Parameter | Type | Description |
| sStr | String | Regular expression string input. |
Returns
String.
trim |
Functionality
Trims a string of the character that is provided (defaults to space). This replaces the many usages of trim throughout LabVantage. This method is also accessible as a prototype to String: trim(sChars).
Parameters
| Parameter | Type | Description |
| sString | String | String input. |
| sChars | Character or String | Character input. |
Returns
String.
leftTrim |
Functionality
Trims a string of the character that is provided (defaults to space) from the left of the string. This method is also accessible as a prototype to String: leftTrim(sChars).
Parameters
| Parameter | Type | Description |
| sString | String | String input. |
| sChars | Character or String | Character input. |
Returns
String.
rightTrim |
Functionality
Trims a string of the character that is provided (defaults to space) from the right of the string. This method is also accessible as a prototype to String: rightTrim(sChars).
Parameters
| Parameter | Type | Description |
| sString | String | String input. |
| sChars | Character or String | Character input. |
Returns
String.
getTokens |
Functionality
Returns an array of tokens (such as [keyid1]) that is found in the string. This method is also accessible as a prototype to String: getTokens(sStartToken,sEndToken).
Parameters
| Parameter | Type | Description |
| sInput | String | String input. |
| sStartToken | String | Starting token. Defaults to [ |
| sEndToken | String | Eding token. Defaults to ] |
Returns
String Array.
replaceAll |
Functionality
Replaces all occurrences of a string in a string. This replaces many usages of replaceAll throughout LabVantage. This method is also accessible as a prototype to String: replaceAll(sOld, sNew).
Parameters
| Parameter | Type | Description |
| sStr | String | String input. |
| sOld | String | Original string. |
| sNew | String | New string. |
Returns
String.
startsWith |
Functionality
Checks if a string starts with the prefix provided. If yes, returns true. This method is also accessible as a prototype to String: startsWith(sStr,sPrefix).
Parameters
| Parameter | Type | Description |
| sStr | String | String input. |
| sPrefix | String | Prefix. |
Returns
Boolean.
endWith |
Functionality
Checks if a string ends with the suffix provided. If yes, returns true.
Parameters
| Parameter | Type | Description |
| sStr | String | String input. |
| sPostfix | String | Suffix. |
Returns
Boolean.
|
Object: sapphire.util.timer |
Description
Timer utilities. The timer can be used to time functionality or record time stamps.
File
WEB-CORE\scripts\sapphirecore.js
Properties
None.
start |
Functionality
Starts the timer.
Parameters
None.
Returns
Void.
lap |
Functionality
Creates a timer lap (time point). If a name is provided, this lap is labelled.
Parameters
| Parameter | Type | Description |
| sName | String | Name of the timer. |
Returns
Void.
stop |
Functionality
Stops the timer and shows a message with the report of the timer.
Parameters
None.
Returns
Void.
|
Object: sapphire.util.propertyList |
Description
Handles client-side Property Lists (JSON-rendered). All methods except create are added as prototypes to any new property list created using the create method.
File
WEB-CORE\scripts\sapphirecore.js
Properties
None.
create |
Functionality
Creates a new client-side Property List object. Returns the object with the prototype of this class. You can therefore use myPropertyList.get(), myPropertyList.set(), etc.
Parameters
| Parameter | Type | Description |
| NoneoPropertyList | Object | Property List on which to base the new Property List on. This can be a Property List object or any collection object. This clones the object. |
Returns
Object.
set |
Functionality
Sets a value in a Property List.
Parameters
| Parameter | Type | Description |
| oPropertyList | Object | Property List to modify. |
| sPropertyId | String | Identifier of the property to set. |
| oValue | Object | Value of the property. |
Returns
None.
get |
Functionality
Gets a value from a Property List.
Parameters
| Parameter | Type | Description |
| oPropertyList | Object | Property List containing the value. |
| sPropertyId | String | Identifier of the property. |
| sDefault | String | Default value of the property. |
Returns
Object.
setId |
Functionality
Sets the Id of a Property List.
Parameters
| Parameter | Type | Description |
| oPropertyList | Object | Property List to modify. |
| sId | String | Property List Id. |
| sDefault | String | Default value of the property. |
Returns
None.
getId |
Functionality
Gets the Id of a Property List.
Parameters
| Parameter | Type | Description |
| oPropertyList | Object | Property List to use. |
| sId | String | Property List Id. |
| sDefault | String | Default value of the property. |
Returns
String.
setSequence |
Functionality
Sets the sequence number of a Property List.
Parameters
| Parameter | Type | Description |
| oPropertyList | Object | Property List to modify. |
| vSequence | Variant | Sequence number (can be integer or string). |
Returns
None.
toForm |
Functionality
Renders the contents of the client-side Property List as an HTML form object.
Parameters
| Parameter | Type | Description |
| oPropertyList | Object | Property List to render. |
Returns
Object.
remove |
Functionality
Removes a value from a Property List.
Parameters
| Parameter | Type | Description |
| oPropertyList | Object | Property List to modify. |
| sPropertyId | String | Identifier of the property. |
Returns
None.
getCollection |
Functionality
Gets a client-side Property List Collection from a Property List. The returned collection has the prototype of the sapphire.util.PropertyListCollection class. You can hterefore use calls such as myCollection.add(), myCollection.remove(), etc.
Parameters
| Parameter | Type | Description |
| oPropertyList | Object | Property List to modify. |
| sPropertyId | String | Identifier of the property. |
Returns
Object.
getPropertyList |
Functionality
Gets a client-side Property List from a specified Property List. The returned Property List has the prototype of the sapphire.util.PropertyList class. You can therefore use calls such as myPropertyList.set(), myPropertyList.get(), etc.
Parameters
| Parameter | Type | Description |
| oPropertyList | Object | Property List to modify. |
| sPropertyId | String | Identifier of the property. |
Returns
Object.
toJSONString |
Functionality
Returns a JSON string representation of the Property List object and all of its properties.
Parameters
| Parameter | Type | Description |
| oPropertyList | Object | Property List to use. |
Returns
String.
clone |
Functionality
Creates a replica of a Property List and returns it as a new object. Note that all property list methods (such as get, set, clone, etc.) are available as prototypes to property list objects: get(sPropertyId), set(sPropertyId, sValue), clone(), etc.
Parameters
| Parameter | Type | Description |
| oPropertyList | Object | Property List to use. |
Returns
Object.
|
Object: sapphire.util.propertyListCollection |
Description
Handles client-side Property List Collections (JSON-rendered).
File
WEB-CORE\scripts\sapphirecore.js
Properties
None.
create |
Functionality
Creates a new client-side Property List Collection object. This returns the object with the prototype of this class. You can therefore use myCollection.add(), myCollection.remove(), etc.
Parameters
| Parameter | Type | Description |
| oCollection | Object | Property List collection on which to base the new Property List. This can be a Property List collection object or any array object. This clones the object. |
Returns
Object.
get |
Functionality
Gets a Property List object from a Property List Collection.
Parameters
| Parameter | Type | Description |
| oPropertyListCollection | Object | Property List Collection to use. |
| vKeyOrIndex | Object | Collection key or index. |
Returns
Object.
add |
Functionality
Adds a new Property List to a Property List Collection.
Parameters
| Parameter | Type | Description |
| oPropertyListCollection | Object | Property List Collection to use. |
| oPropertyList | Object | Property List to add. |
| vKeyOrIndex | Object | Collection key or index. |
Returns
None.
remove |
Functionality
Removes a Property List from a Property List Collection.
Parameters
| Parameter | Type | Description |
| oPropertyListCollection | Object | Property List Collection to use. |
| iIndex | Integer | Index of Collection to remove. |
Returns
None.
findIndex |
Functionality
Finds the index of a collection item with a specified property and value. If found, returns the index of the collection. If not found, returns -1.
Parameters
| Parameter | Type | Description |
| oPropertyListCollection | Object | Property List Collection to use. |
| sPropertyId | String | Property Id for which to search. |
| sValue | String | Value of the property for which to search. |
Returns
Integer.
find |
Functionality
Finds a collection item with a specified property and value. If found, returns the collection. If not found, returns null.
Parameters
| Parameter | Type | Description |
| oPropertyListCollection | Object | Property List Collection to use. |
| sPropertyId | String | Property Id for which to search. |
| sValue | String | Value of the property for which to search. |
Returns
Integer.
move |
Functionality
Moves an item in the collection by a specified delta. Returns the new index of the item.
Parameters
| Parameter | Type | Description |
| oPropertyListCollection | Object | Property List Collection to use. |
| iIndex | Integer | Collection items index to move. |
| iDelta | Integer | Delta to move. For example, -1 moves a collection item down one position in the collection, +3 moves it up three positions. |
Returns
Integer.
copy |
Functionality
Copies an item in the collection by a specified number of copies. Returns the new index of the items.
Parameters
| Parameter | Type | Description |
| oPropertyListCollection | Object | Property List Collection to use. |
Returns
Object.
clone |
Functionality
Creates a replica of a Property List Collection and returns it as a new object.
Parameters
| Parameter | Type | Description |
| oPropertyListCollection | Object | Property List Collection to use. |
Returns
Object.
toJSONString |
Functionality
Returns the JSON string representation of the collection. Note that all property list collection methods (such as get, add, find, etc.) are available as prototypes to property list collection objects: get(iIndex), add(oPropertyList, vKeyOrIndex), find (sPropertyId, sValue), etc.
Parameters
| Parameter | Type | Description |
| oPropertyListCollection | Object | Property List Collection to use. |
Returns
String.
|
Object: sapphire.util.script |
Description
Handles client-side script.
File
WEB-CORE\scripts\sapphirecore.js
Properties
None.
createProxyFunction |
Functionality
Creates a function pointer around an existing function so that original function can be replaced. This is used internally to replace the Maint page save by first proxying the save method and then calling the proxied method from the new save method.
Parameters
| Parameter | Type | Description |
| vOldFunc | Object/String | Function name or function pointer to function to proxy. |
Returns
Object.
execScript |
Functionality
Similar to eval, executes the script applied. The difference is that this uses Functions and apply to execute the script and is able to pass in a "this" object for execution. Also like eval, it also iterates through a set of provided windows.
Parameters
| Parameter | Type | Description |
| sScript | String | Script string to execute. |
| oThis | Object | Object reference (defaults to the current window). |
| oaWindows | Array | Array of window objects to evaluate script against (will try each one until it succeeds). |
Returns
Object.
getRequestArguments |
Functionality
Pass Id string of the script include and will return the array of request arguments passed through the query string of the Script URL.
Parameters
| Parameter | Type | Description |
| sId | String | The id of the script tag. |
Returns
Object - the collection of request variables in JSON object.
|
Object: sapphire.util.dom |
Description
Manages browser-independent DOM manipulation.
File
WEB-CORE\scripts\sapphirecore.js
Properties
None.
getElementByName |
Functionality
Returns a single element that has the specified name attribute. This works for Mozilla, web kit and IE.
Parameters
| Parameter | Type | Description |
| sName | String | Name attribute to find. |
| oDoc | Object | Document object to use. |
Returns
Object.
getAttribute |
Functionality
Gets an attribute on an element. For non-IE browser custom attributes, you must use get and set attributes. This method wraps the usage for both IE and other browsers.
Parameters
| Parameter | Type | Description |
| vEl | Object/String | Element object or id of element for which the attribute is retrieved. |
| sAttribute | String | Id of the attribute for which the value is retrieved. |
Returns
Object.
setAttribute |
Functionality
Sets an attribute on an element. For non-IE browser custom attributes, you must use get and set attributes. This method wraps the usage for both IE and other browsers.
Parameters
| Parameter | Type | Description |
| vEl | Object/String | Element object or id of element for which the attribute is set. |
| sAttribute | String | Id of the attribute for which the value is set. |
| vValue | Variant | Value to set. |
Returns
None.
containsNode |
Functionality
Returns true if a parent element contains a child element. Mozilla and web kit misses this functionality; therefore, this method covers IE, Mozilla based, and web kit based browsers.
Parameters
| Parameter | Type | Description |
| oParent | Object | Parent element/node of the child element. |
| oChild | Object | Child element/node to be checked (to see if it is under the parent). |
Returns
None.
getAll |
Functionality
Cross-browser method for obtaining all nodes/elements that are inside of an element. This resolves the crisis ensuing when one finds that the element.all method works in IE, but not in other browsers.
Parameters
| Parameter | Type | Description |
| oElement | Object | Element for which all children are obtained. |
Returns
Object Array.
setFormField |
Functionality
Sets a field in a form and creates it if not present. This is multi-browser-compatiable and works around different browser limitations with dynamic fields.
Parameters
| Parameter | Type | Description |
| vForm | Object/String | Form id or form object to which the field is added. |
| sName | String | Name of the field. |
| sValue | String | Value of field (defaulst to empty string). |
| sType | String | Type attribute for the field (defaults to hidden). |
| sId | String | Id of the field (defaults to the name). |
Returns
None.
getOuterHTML |
Functionality
Gets the outer HTML around an element. The usual getOuterHTML method on an element works only in IE. This version is multi-browser and uses the typical way for IE and the custom way for other browsers.
Parameters
| Parameter | Type | Description |
| oEl | Object | Element for which to get the outer HTML. |
Returns
String.
findFrame |
Functionality
Pass window name and the frame object will be returned. Will return null if frame is not found.
Parameters
| Parameter | Type | Description |
| sObjectName | String | Object to search for. |
| oStart | Object | Frame to start in. |
Returns
Object - the frame with the object.
focusElement |
Functionality
Pass element object and will focus the element.
Parameters
| Parameter | Type | Description |
| oEl | Object | The element to focus. |
Returns
None.
createDocumentFragment |
Functionality
Pass document object (defaults to current document) and creates a multibrowser compatable fragment which is returned.
Parameters
| Parameter | Type | Description |
| oDoc | Object | Document object. |
Returns
Object - Document fragment.
getChildren |
Functionality
Pass element object, id of child element to find (leave undefined to find all), the tag string to filter by tag and true if you want to return as soon as the first matching child is found. Will return an array of elements.
Parameters
| Parameter | Type | Description |
| oElement | Object | Element to get children for. |
| sId | String | Id to filter by. |
| SName | String | Id to filter by. |
| sTag | String | Tag to filter by. |
| lBreakOnFind | Boolean | Set to true to return immediately as a filter parameter is met. |
Returns
Object Array - Array of child nodes.
createForm |
Functionality
Pass the action url string, true of post, an object of inputs (array of objects with each object having name, type, id and value), the parent to attach the form to (pass null for no appending to dom) and true if hidden. Will then return the form object.
Parameters
| Parameter | Type | Description |
| sURL | String | URL for form. |
| lPost | Boolean | Set to true for post form or false for get form. |
| oInputs | Object Array | Array of objects depicting input attributes. |
| oParent | Object | If provided, will attach form object to parent node. If not provided, will not attach form to DOM. |
| lHidden | Boolean | Set to true to create the form with hidden style. |
Returns
Form object.
moveTableRow |
Functionality
Pass the table body object, the from integer and the to integer. Will then move the table row.
Parameters
| Parameter | Type | Description |
| tbody | Object | The tbody object for the table. |
| from | Integer | Row number from. |
| to | Integer | Row number to. |
Returns
None.
|
Object: sapphire.util.date |
Description
Manages date manipulation client-side.
File
WEB-CORE\scripts\sapphirecore.js
Properties
None.
compare |
Functionality
Compares two dates. Returns 1 if the second date is greater than the first date, 0 if the dates are the same, and -1 if the second date is less than the first date.
Parameters
| Parameter | Type | Description |
| dDate1 | Date | First date. |
| dDate2 | Date | Second date. |
Returns
Integer.
compareTime |
Functionality
Compares the time between two dates and return the exact difference. For example, you can use this to find how many days, years, or milliseconds are between two points.
Parameters
| Parameter | Type | Description |
| dDate1 | Date | First date. |
| dDate2 | Date | Second date. |
| iTimeType | Integer | Number of milliseconds for the comparison. Use sapphire.util.date.SECONDS, sapphire.util.date.MINUTES, sapphire.util.date.DAYS, etc. |
Returns
Integer.
|
Object: sapphire.util.url |
Description
Manages manipulation of URLs. This is used with Unicode to encode and decode URLs or move URLs to forms and post requests.
File
WEB-CORE\scripts\sapphirecore.js
Properties
| Property | Type | Description |
| defaultExcludes | Object | Object containing the list of request parameters to exclude from form generation and encoding. |
encode |
Functionality
Encodes a URL to allow special characters to pass through the request. Will also avoid doubly encoding values and will individually encode the query string parameters. Returns the encoded URL.
Parameters
| Parameter | Type | Description |
| sUrl | String | URL string to encode. |
Returns
String.
decode |
Functionality
Decodes a URL to remove any encoding added using encode. Returns the decoded URL.
Parameters
| Parameter | Type | Description |
| sUrl | String | URL string to decode. |
Returns
String.
addToForm |
Functionality
Takes the specified URL and builds or adds to a form. All query parameters will be added as hidden fields and the main URL will become the action.
Parameters
| Parameter | Type | Description |
| sUrl | String | URL to add to the form. |
| oForm | Object | Form object to be added to. If none supplied, creates a new form. |
| oExcludes | Object | List of excludes to miss from the input fields and leave on the URL (defaults to sapphire.util.url.defaultExcludes). |
Returns
None.
getFromForm |
Functionality
Take the specified form and builds a URL from it. All input fields will become query parameters.
Parameters
| Parameter | Type | Description |
| oForm | Object | Form object. |
Returns
None.
|
Object: sapphire.util.url.href |
Description
Encodes and decodes URLs. The constructor takes the URL details and uses them to build an object.
File
WEB-CORE\scripts\sapphirecore.js
Properties
| Property | Type | Description |
| url | String | URL on which the object is based. |
| address | String | Address of the URL (IP or machine name). |
| protocol | String | Protocol of the URL. |
| server | String | Server name of the URL. |
| port | String | Port of the URL. |
| page | String | Page of the URL. |
| querystring | String | Query string part of the URL. |
| query | Object | Object containing a key-value pair of all query string parameters (except excluded parameters). |
| queryExclude | Object | Object containin a key-value pair of query parameters to miss extraction from the URL. |
These are the Constructor properties:
| Property | Type | Description |
| sUrl | String | URL to build from. |
| lEncode | Boolean | True if you want to encode the URL as it is processed. |
| oQueryExcludes | Object | Key-value pair of query parameters to exclude. |
| fQueryProcess | Function Pointer | Function to execute when processing parameters. |
| lSimple | Boolean | If true, will not completely extract the URL and instead will provide the simple breakdown of the URL (less work). |
get |
Functionality
Gets a URL string based of the object. This can be used to modify a URL or build new URLs.
Parameters
| Parameter | Type | Description |
| lFull | Boolean | If false, returns only the intial URL and leaves the query string. |
| lDecode | Boolean | If true, decodes the parameters as it rebuilds the URL. |
Returns
String.
|
Object: sapphire.util.dataset |
Description
Client side representation of a dataset in JSON. Uses GWT dataset or raw JSON dataset structure.
File
WEB-CORE\scripts\sapphirecore.js
Properties
None.
create |
Functionality
Create a dataset object. Pass the JSON object.
Parameters
| Parameter | Type | Description |
| oDataSet | Object | The JSON dataset object. |
Returns
Object.
isValidColumn |
Functionality
Passes the dataset object and column id string and return true.
Parameters
| Parameter | Type | Description |
| oDataSet | Object | The dataset object. |
Returns
Boolean.
getValue |
Functionality
Passes the dataset object, row integer, column name string or column integer and default string and returns the value or default if no value is found.
Parameters
| Parameter | Type | Description |
| oDataSet | Object | The dataset object. |
| iRow | Integer | The row number. |
| VColumnId | Variant | Column name or column number. |
| sDefault | String | Default value. |
Returns
String.
setValue |
Functionality
Passes the dataset object, row integer, column name string or column integer and value string.
Parameters
| Parameter | Type | Description |
| oDataSet | Object | The dataset object. |
| iRow | Integer | The row number. |
| VColumnId | Variant | Column name or column number. |
| sDefault | String | Default value. |
Returns
None.
find |
Functionality
Passes the dataset object, column name string and value string to look for and will return row index.
Parameters
| Parameter | Type | Description |
| oDataSet | Object | The dataset object. |
| sColumnId | String | Column name to find in. |
| sValue | String | Value to search for. |
Returns
Integer - row number where value is found.
addColumn |
Functionality
Passes the dataset object, column name string and type integer (uses Java dataset type).
Parameters
| Parameter | Type | Description |
| oDataSet | Object | The dataset object. |
| sColumnId | String | The column id for the new column. |
| iType | Integer | The column type (as in the server side dataset type enumeration). |
Returns
None.
addRow |
Functionality
Passes the dataset object and returns row number integer.
Parameters
| Parameter | Type | Description |
| oDataSet | Object | The dataset object. |
Returns
Integer.
getRowCount |
Functionality
Passes the dataset object and returns row count integer.
Parameters
| Parameter | Type | Description |
| oDataSet | Object | The dataset object. |
Returns
Integer.
getColumnCount |
Functionality
Passes the dataset object and returns column count integer.
Parameters
| Parameter | Type | Description |
| oDataSet | Object | The dataset object. |
Returns
Integer.
toJSONString |
Functionality
Passes the dataset object and returns JSON string of dataset.
Parameters
| Parameter | Type | Description |
| oDataSet | Object | The dataset object. |
Returns
String.
clone |
Functionality
Passes the dataset object and returns cloned dataset.
Parameters
| Parameter | Type | Description |
| oDataSet | Object | The dataset object. |
Returns
Object - The new dataset object.