Copyright © TIBCO Software Inc. All Rights Reserved
Copyright © TIBCO Software Inc. All Rights Reserved


Chapter 7 Reference : API for Scripting

API for Scripting
This section describes API methods that can be used in your JavaScript scripts for accessing the form model at runtime.
Methods
The following tables describe the API for scripting.
The API described here can be used for writing validations as well as actions. Updating form fields or their properties using set methods is allowed only in the context of actions. Validation scripts cannot modify the fields or their properties.
Table 92 FormRunner Class
initialData: specifies the JSON representation of the initial data that are provided to the form.
bomJSPath: specifies the root folder path used for loading the BOM JavaScript files used by the form.
For example: http://10.97.110.17:8080/bpmresources/1.0.0.201107291435
locale: specifies the locale to be used in the runtime form with the <lc>[_<CC>] format, where [] denotes optionality.
For example: "en_US". The locale needs to be represented such that <lc> is a valid two-character lower case ISO-639 language code, and, if present, the optional <CC> is a valid two-character upper case ISO-3166 country code. Both '_' and '-' are supported as delimiters.
parentNodeId: specifies the DOM identifier of the node to which the form must be added. The value cannot be null.
onSuccess: is a function that is called after the form is successfully initialized. The Form object is passed into this function. It can be used to add custom callback handlers that implement lifecycle events such as submit, close, and cancel.
onError: is a function that is called on encountering any error in initializing the form. The function receives the exception encountered during the initialization.
provideCloseAction: if it is set to true, the form is rendered with a button that closes the form and cleans up any resources used. If it is set to false, then it is the responsibility of the containing application to clean up the form when it is no longer needed.
JSONP: informs the Forms Runtime Adapter to use JSON with Padding (JSONP) when loading JSON resources. The default value is false. When the custom client and Forms Runtime Adapter are hosted on different servers, set the JSONP parameter to true. In this scenario, there are SOP (Single Origin Policy) issues while loading JSON resources. By using the JSONP technique, the JSON response is wrapped as a function by the server and is sent to the client. A JSON resource can then be loaded using a script tag to avoid any SOP violations.
Table 93 Form Class
Returns custom CSS classnames set on the form. The value may be null, a single CSS classname, or a space-separated list of CSS classnames that are applied to the root level of the form.
Invokes the shared or default action specified by the actionName parameter. The object passed as the control parameter is used as the this variable inside the script of the invoked action. The third argument is used as the context variable in the invoked script. If the third argument is null, then a default context is used in the invoked script. Example usage:
Validates whether the value passed is a number or not. It returns true if the parameter value is a number, and false otherwise.
Validates whether the value passed is less than the length specified. Used to validate the length of parameters like strings and numbers. It returns true if the value passed is less than length specified, false otherwise.
Validates whether the number represented by the value parameter is less than totalLength parameter and number of decimal digits is less than decimalLength specified. It returns true if the value passed is less than length specified in terms of both total length and length of the decimal digits, false otherwise.
Sets the custom CSS classnames on the form. The value may be null, a single CSS classname, or a space-separated list of CSS classnames that are applied to the root level of the form. The value replaces any previously set classname whether that was set in the model or by a previous call to setClassName().
Forces validation to run on the form and all child panes and controls. Returns true if all validations return true. If updateMessagePane is true, then validation messages are displayed in the messages pane for any validation that failed. If updateMessagePane is not specified, it is treated as false.
Table 94 Control Class
Returns custom CSS classnames set on the control. The value may be null, a single CSS classname, or a space-separated list of CSS classnames that are applied to the root level of the form.
Returns the tab index setting configured on the control, or 0 if it is not set. This is useful for custom controls that support the setting of the tab index in their HTML markup.
The only property supported in versions prior to 2.x was bgColor. The value for bgColor is hexadecimal, and is the same format as for font color.
The enabled setting of a control is controlled both by its own enabled property, and the enabled properties of any of its ancestors. If the parent pane of a control is disabled, then isReallyEnabled() returns false for that control. The method returns true only if it's own enabled property is true and all of its ancestor's enabled properties are set to true.
The visibility of a control is controlled both by its own visibility property, and the visibility properties of any of its ancestors. If the parent pane of a control is not visible, then isReallyVisible() returns false for that control. The method returns true only if it's own visibility property is true and all of its ancestor's visibility properties are set to true.
Sets the custom CSS classnames on the control. The value may be null, a single CSS classname, or a space-separated list of CSS classnames that are applied to the component level of the control. The value replaces any previously set classname whether that was set in the model or by a previous call to setClassName().
index: Use this parameter for controls within a grid or record pane. Sets the focus on a control instance in the row specified by the given index. If the specified row is not visible, scrolls the grid control to the specified row and page. If the specified row does not exist, logs a warning message and does not shift the focus. This parameter is ignored if the control is in a singleton pane (for instance vertical pane, horizontal pane, and so on). The default value is 0.
index: Use this parameter for controls within a grid or record pane. Sets the focus on a control instance in the row specified by the given index. If the specified row is not visible, scrolls the grid control to the specified row and page. If the specified row does not exist, logs a warning message and does not shift the focus. This parameter is ignored if the control is in a singleton pane (for instance vertical pane, horizontal pane, and so on). The default value is 0.
item: Is used for list controls and specifies the item within the list that is to receive the focus. If the specified item does not exist, logs a warning message and does not shift the focus. This parameter is ignored if the control is not a list control. The default value is 0.
For a tabbed pane, you need to activate the particular tab (See setActiveTab() API on pane) before calling this API on a control within the corresponding child pane.
The fontName parameter is provided as a string to specify the name of the font.
The size parameter is provided as an integer to specify the font size in points.
The weight parameter is provided as a string to specify the weight of the font. It can be either "normal", or "bold".
The only property supported in versions prior to 2.x was bgColor. The value for bgColor is hexadecimal, and is the same format as for font color.
This is only supported for text, textarea, date, datetime, time, and duration controls.
Forces validation to run on the control. Returns true if all validations for the control return true. If updateMessagePane is true, then validation messages are displayed in the messages pane for any validation that failed. If the control is not visible, the validation runs, but updateMessagePane is ignored. If updateMessagePane is not specified, it is treated as false.
Table 95 Pane Class
message: is the message string that is added at the end of the message pane
cssClasses: is the space-separated list of CSS classes to allow custom styling of the message. You need to add the cssClasses string to the element containing the message.
target: is either a control or a pane to which the message is targeted. If specified, renders a message as a link, to allow users to navigate directly to the target of the message. If null, then the message is not rendered as a link.
row: is the row of the list control or the control in a grid pane, to which the message is targeted. This is used only if a control is specified in the target parameter, and it is a list control or the control is in a grid pane. This is an optional parameter. If null, then the first element in the list control or grid pane column is targeted with a clickable message. If the target is a list control within a grid pane, then an array of length two needs to be specified. The first number in the array indicates the row of the control. The second value indicates the index of the value within the list control that receives the focus.
Returns the pane type of this pane (for example,
"com.tibco.forms.panes.vertical").
For grid and record panes returns a list. Returns null or a complex object value for other pane types.
The only property supported in versions prior to 2.x was bgColor. The value for bgColor is hexadecimal, and is the same format as for font color.
The enabled setting of a pane is controlled both by its own enabled property, and the enabled properties of any of its ancestors. If the parent pane of a pane is disabled, then isReallyEnabled() returns false for that control. The method returns true only if its own enabled property is true and all of its ancestor's enabled properties are set to true.
The visibility of a pane is controlled both by its own visibility property, and the visibility properties of any of its ancestors. If the parent pane of a pane is not visible, then isReallyVisible() returns false for that control. The method returns true only if it's own visibility property is true and all of its ancestor's visibility properties are set to true.
Removes a message previously added to the message pane using the addMessage()API. You may only remove the messages added using the addMessage() API. The messageId is an identifier used to specify which message needs to be removed.
Sets the active child pane for a tabbed pane. The tab to be set as active tab is passed as childPane parameter to the method. The childPane parameter must be a direct child pane of the tabbed pane.
The color parameter is provided as a String in the form #RRGGBB, where RR, GG, and BB are hexadecimal numbers representing the red, blue, and green components respectively.
The fontName parameter is provided as a string to specify the name of the font.
The size parameter is provided as an integer to specify the font size in points.
The weight parameter is provided as a string to specify the weight of the font. It can be either "normal", or "bold."
Valid only for grid and record panes. Sets the selected row or record of the pane to the object passed into the method. Passing null or an empty list clears the selection. If the selection is not present in the list managed by the pane, then this has no effect.
The only property supported in versions prior to 2.x was bgColor. The value for bgColor is hexadecimal, and is the same format as for font color.
Forces validation to run on the pane and all child panes and controls. Returns true if all validations return true. If updateMessagePane is true, then validation messages are displayed in the messages pane for any validation that failed. If updateMessagePane is not specified, it is treated as false
Table 96 List Class
Returns true if the specified element is part of the list, and false otherwise.
Returns true if there are no elements in the list, and false otherwise.
Returns a list over a subset (between the specified fromIndex, inclusive, and toIndex, exclusive) of items from the original list. The sublist is backed by the original list, so changes to the sublist is reflected in the original list and vice-versa until the original list is structurally modified.
Table 97 Iterator Class
Inserts the specified element into the list immediately before the element that would be returned by next(), if any, and after the element that would be returned by previous(), if any. If the element already exists on the list, an exception is thrown.
Returns true if the list iterator has more elements when traversing the list in the forward direction.
Returns true if the list iterator has more elements when traversing the list in the reverse direction.
Returns the next element in the list. Returns null if the iteration does not have a next element.
Returns the index of the element that would be returned by a subsequent call to next(). Returns list size if the iterator is at the end of the list.
Returns the previous element in the list. Returns null if the iteration does not have a previous element.
Removes from the list the last element that was returned by next() or previous(). This method can be called only if either next() or previous() have been called and there were no calls to add() or remove() after the last call to next() or previous().
Replaces the last element returned by next() or previous() with the specified element. This method can be called only if either next() or previous() have been called and there were no calls to add() or remove() after the last call to next() or previous().
Table 98 Logger Class
Logs the given messages at the trace logging level.
Checks whether the Fatal logging level is enabled. It returns true if the logging level is enabled, and false otherwise.
Checks whether the Error logging level is enabled. It returns true if the logging level is enabled, and false otherwise.
Checks whether the Warn logging level is enabled. It returns true if the logging level is enabled, and false otherwise.
Checks whether the Info logging level is enabled. It returns true if the logging level is enabled, and false otherwise.
Checks whether the Debug logging level is enabled. It returns true if the logging level is enabled, and false otherwise.
Checks whether the Trace logging level is enabled. It returns true if the logging level is enabled, and false otherwise.
Complex Data
The classes defined in the business object model (BOM) are represented in the runtime JavaScript API. Parameters can be defined as external types to classes defined in a BOM, either in the same project as the form or in dependent projects. Each attribute defined in a class results in corresponding get[AttributeName]() and set[AttributeName](value) methods. For example, a BOM class Customer that had a firstName attribute would generate a Customer class with the methods:
String getFirstName();
void setFirstName(String firstName);
Factories
For each package defined in the business object model in the project, or in any projects upon which the project depends, there is an instance of a factory available in the form script editors. These are accessed via the available factory variable in each script.
New instances of complex types are created via the use of these factories. Each factory has a set of static methods that can be used to create instances of the classes defined within that package.
The factory for each package is referenced via an instance variable of the form: factory.[business_object_model_name], where [business_object_model_name] is the fully qualified BOM package name, with "." replaced by an underscore "_".
A create method for each class is provided with the signature:
<class-name> create<class-name>()
For example, suppose the package com.example.customer contains classes for Customer and Address. We would create instances of each of these objects using the following:
var address = factory.com_example_customer.createAddress();
var customer = factory.com_example_customer.createCustomer();
A factory is only available for packages that directly contain class definitions. For example, there would not be a factory for the com.example package if there were no classes defined directly in that package.
The content assist in any script editor displays the available factories after typing factory. Only factories for packages in the current project or referenced projects is displayed.
Packages
There is also a corresponding package instance available in the pkg variable.
The naming of the instance of this package follows the same rule as for factories.
Enumerations defined in the package can be retrieved as read-only arrays using a method with the pattern get[enumName](). So, for example, if the com.example.customer package contains an enumeration named ServiceLevel that contains the Enum Literals GOLD, SILVER, BRONZE, then you could access an array containing these three values using:
pkg.com_example_customer.getServiceLevel()
DateTimeUtil Factory
There is a built-in factory named DateTimeUtil. This factory provides access to methods used in creating Duration objects:
Creates a Duration object that can then be used to set as a value on duration controls, the value on parameters or data fields of type Duration, or as attributes of complex objects with type Duration.
Duration Class
The value expected by the setValue of the duration control is an object of type Duration. The Duration class has the following methods:
Returns true if the duration passed in is equal to this duration.
Utility Methods
The following table describes the Util class API methods for scripting.
 
Table 99 Util Class
value1: first value to compare
value2: second value to compare
returns < 0: value1 less than value2.
returns 0: value1 equal to value2.
returns > 0: value1 greater than value2.
text: text to be escaped
formatString: a format string that conforms to the Java date format syntax, as used in the Forms framework
date: either a Date object or a string that conforms to the ISO-8601 date format
formatString: a format string that conforms to the Java number format syntax, as used in the Forms framework
number: a JavaScript number or a string containing a numeric value
template: containing substitution variables of the form {0}, {1}, .. {n}
args: string array containing values to substitute into the template. The first value in the array replaces {0} in the template, the second replaces {1}, and so on.
value: string containing the date value
It returns true if the date is in the required edit format, and false otherwise.
value: string containing the time value
Returns true if the time is in the required edit format, and false otherwise.
value: is a string date-time value
Returns true if the date-time is in the required edit format, and false otherwise.
value: is an object to be validated
totalLength: is an integer value specifying the maximum number of digits
decimalLength: is an integer value specifying the maximum number of digits following the decimal place
Validates whether the value parameter has no more than totalLength digits and at most decimalLength digits following the decimal place.
Returns true if the value conforms to both totalLength and decimalLength constraints.
value: is a string value to be tested against regExp
regExp: JavaScript RegExp object with which the value is to be tested
Validates a value against a regular expression.
Returns true if the value matches regExp.
value: is a string value to be validated for length
length: is an integer value specifying the maximum length
Checks whether the specified value conforms to the given length constraint.
Returns true if the length of the specified value is less than or equal to the given length.
value: is a string value to be checked
lowerLimit: is a string value specifying the lower limit
lowerLimitInclusive: is a boolean value. If true, the lowerLimit is inclusive.
Checks whether the value is numerically greater than lowerLimit, or if lowerLimitInclusive is true, greater than or equal to lowerLimit.
Returns true if the value satisfies the lower limit constraint.
value: is a string value to be checked
upperLimit: is a string specifying the upper limit
upperLimitInclusive: is a boolean value. If true, the upperLimit is inclusive.
Checks whether the value is numerically less than upperLimit, or if upperLimitInclusive is true, less than or equal to upperLimit.
Returns true if the value satisfies the upper limit constraint.
value: is a string value to be checked
Returns true if the value is a valid integer.
value: is a string value to be checked
Returns true if the value is a valid number.
value: is an object (array or list) to be checked
lowerBound:is an integer value specifying the lower bound
upperBound: is an integer value specifying the upper bound. Set upperBound to -1 to signify an unbounded object.
Returns true if the constraints are satisfied.

Copyright © TIBCO Software Inc. All Rights Reserved
Copyright © TIBCO Software Inc. All Rights Reserved