cis.js

The cis.js file contains the bulk of the core framework functions. In addition to defining the major framework classes (CisModel, DataElement, List, etc.) it contains a number of important functions that are described here. These functions are typically invoked by navigating to the main level, e.g. main.xyz(), where the global main has been defined to point to the frame containing cisMain.jsp.

  • array_​remove_​element(array, element)

Remove the indicated element from the given array. Do nothing if it is not found. If the element appears more than once in the array, remove only the first one. Uses simple object comparison (==).

  • array_​index_​of(array, element)

Return the index (0-based) of the given element in the given array. Answer -1 if the element cannot be found. If the element appears multiple times, answer the first (lowest) index. Uses simple object comparsion (==).

  • array_​remove(array, index)

Compensate for missing functionality in the built-in JavaScript Array class in early versions of JScript. Answers a new array instance with the element at the given index removed. The length of the new array is one less than the length of the given one.

  • array_​includes(array, element)

Answers a boolean indicating whether the given element is present in the given array. Uses simple object comparison (==).

  • array_​numeric_​sort(array)

Sort the elements of the given array into numeric order, using a simple a < b comparison.

  • arrayDo(array, oneArgClosure)

Perform a loop over the elements of the given array, applying the function given by oneArgClosure to each element in turn. The oneArgClosure function takes exactly one argument. Extremely useful for signalling the intention of looping structures. For example, consider this typical code:

var max = array.length;

for (var i = 0; i < max; i++) {

var element = array[i];

<do something to element>

}

This common structure can be simplified to the following:

arrayDo(array, oneArgFunction)

where oneArgFunction takes an array element as its parameter, and corresponds to the <do something to element> block above.

  • arraySelect(array, selectClosure)

Returns a new array consisting of elements from the given array that return true when applied to the selectClosure (a function that takes one argument). For example, do this to find all numbers greater than 3 in an array:

var closure = function(each) {return each > 3};

var resultArray = arraySelect(array, closure);

  • arrayReject(array, rejectClosure)

Returns a new array consisting of all elements from the given array except those that return true when applied to the rejectClosure (a function that takes one argument). For example, do this to find all numbers not greater than 3 in an array:

var closure = function(each) {return each > 3};

var resultArray = arrayReject(array, closure);

  • arrayDetect(array, detectClosure)

Returns the first element in the given array that returns true when applied to detectClosure, a one-argument function. Return null if no element is found.

  • arrayDetectIfFound(array, detectClosure, doClosure)

Similar to arrayDetect(), but proceeds to execute the one-argument function doClosure with the detected element.

  • arrayDetectIndex(array, detectClosure)

Similar to arrayDetect(), but answers the index of the first element that satisfies the detectClosure function.

  • arrayCollect(array, collectClosure)

Return a new array consisting of the results of applying the collectClosure one-argument function in turn to each element of array. For example, to double the values of an array holding numbers and store the result in a new array:

var closure = function(each) {return each * 2};

var resultArray = arrayCollect(array, closure);

  • arrayCopy(array)

Answers a new array holding the same elements as the given array. Also known as a "shallow copy".

  • arrayContains(array, detectClosure)

Returns a boolean indicating whether the given array contains an element that satisfies detectClosure, a one-argument function returning a boolean.

  • arrayUniquePush(array, object)

Similar to array_​push, but skips appending the given object if an identical object is already present in the array. Uses simple equality (==) for the comparison.

  • configureMainButtons()

Enable or disable the buttons on the main button bar according to the current state of the system. This method should be triggered only if there is a reason to believe that circumstances have left the buttons in an inappropriate state.

  • openPage(navigationKey, tabName, keys, extraPageState, keepMemento, forceOpen, extraLoadKeys)

Navigate the system to the tab menu identified by the given navigationKey. The particular tab page may be identified with the given tabName (string), which can also be identified as an integer index (0-based), otherwise the first tab page is used. To display a particular object on the tabMenu/tabPage populate the keys parameter with a key/value object holding the logical keys that identify the object. [The extraPageState parameter is deprecated]. The boolean keepMemento parameter identifies whether a memento should be stored for the current location, e.g. whether it will enter the history menu. If not provided, it defaults to true. The forceOpen boolean (defaults to false) controls whether the system should still show the tabMenu/tabPage if the desired object cannot be read (e.g. it was deleted from the database). The optional extraLoadKeys object is merged with keys prior to performing the read query, allowing the addition or overriding of key values.

  • showMessageDescription(categoryNumberFieldName, messageNumberFieldName, shortDescriptionFieldName)

Open an alert dialog box showing a server message (the long message). The category and message numbers are given indirectly via the categoryNumberFieldName and messageNumberFieldName, which are property names in the model from which the actual numbers are fetched. An optional a short description field name can also be provided. The alertClientWindow is a reference to a window object that should act as "host" to the alert dialog box, in order to keep focus on the correct window when the dialog is dismissed.

  • basicShowMessageDescription(categoryNumber, messageNumber, shortDescription, alertClientWindow)

Similar to showMessageDescription() as above, but directly accepts the desired category and message numbers rather than retrieving them from the model.

  • showErrorMessage(categoryNumber, messageNumber, clientSubstitutions, element, alertClientWindow)

Show the server error message identified by the given category and message numbers, and relating to the HTMLElement given as element (optional), which should receive focus. The alertClientWindow parameter provides an optional reference to the "client" of this dialog that can be useful to preserve the correct focus when the dialog is dismissed. The clientSubstitutions parameter is private.

  • restoreElements()

Frequently used in conjunction with setAvailableSignal(), this method clears flags that are used to implement synchronization control.

  • doSave(specialActionField, successFunction, forceSave)

Submit a change request to the server using the current model. The specialActionField, if specified, is set to boolean true before submitting the model, without otherwise permanently changing the model. Execute the given successFunction if the save operation succeeds. A "clean" model is not submitted to the server unless the optional forceSafe boolean is true. The browser will refresh itself to show the version of the model as returned from the server, unless the operation resulted in a warning or error. In the first case a dialog shows the warning message line(s), and the user can choose to redo the save operation, ignoring further warnings. In the second case a descriptive error dialog is shown.

  • doDelete()

Submit a delete request to the server using the current model. Clears the window if the operation succeeds.

  • safelySetFocus(element)

Attempt to set focus to the given HTMLElement.

  • updateElementFromModel(htmlElement)

Fetch the current value for the model attribute appropriate to the given htmlElement widget (using the name of the element) and display it.

  • setAvailableSignal(aWindow)

Configure the system to accept input after processing a request for the server. Implemented by disabling the cisDisabled.css stylesheet. Typically used in conjunction with restoreElements().

  • convertInternalDateTimeToLocal(value)

Convert the given internal date-time value to the user's localized format and answer it.

  • convertLocalToInternal(htmlElement, value)

Using the datatype associated with the given html element (as described with its className), convert the given localized value into the internal system value and answer it.

  • convertInternalMoneyToLocal(value)

Convert the given money value (a String) into its localized representation and answer it.

  • updateField(event)

Update the value of the relevant HTML element based on the given event object. This may involve side effects such as updating the model.

  • moneyToWholeInteger(amount)

This utility function helps you do simple arithmetic with money amounts. Since the precision of OUAF system monetary amounts can exceed that offered by the built-in JavaScript number types, we cannot perform arithmetic operations with those numbers without risking loss of precision and rounding problems. The solution is to eliminate the decimal point (if any) in the amounts in order to yield "pure" integers, which admit to exact arithmetic (for addition, subtraction, and multiplication) to very high orders of precision. The final result is then converted back into an internal money amount.

This function accepts an internal money amount (String) and returns a JavaScript "integer" representing the value.

  • wholeIntegerToMoney(integer)

Reverse the moneyToWholeInteger operation to yield a monetary amount corresponding to the given integer.

  • getInstallationData(key)
  • Returns the installation data (string) associated with the given key.
  • isUserModified()
  • Returns a boolean indicating whether the user has made any changes to the model that should be preserved (e.g. the system will issue a warning if the changes are not saved).