APIs that can be used to get a value from an input field or set a value on the Task operating screen (Input form). You can also register an event handler.
As a product characteristic, it takes a certain amount of time to "build a DOM tree". It is necessary to consider the timing of event ignition.
1. Get/Set the value of the input field
1-1. Script Format
Get value
qbpms.form.get("FIELD NAME")
- FIELD NAME: "title" or "q_field_name" (the Field name of the Data Item)
- Available when the editing permission setting on the form is "editable" or "display only"
Set value
qbpms.form.set("FIELD NAME", Value in the format according to the Data-type)
- FIELD NAME: "title" or "q_field_name" (the Field name of the Data Item)
- Value in the format according to the Data-type: (refer to "Get/Set Object Value" below)
- Available when the editing permission setting on the form is "editable"
- Merely changes the displaying value on the form, the value on the server will not be updated unless you save or complete the Task
1-2. Get/Set Object Value
Title/String-type
- Get: string
- If the value is not set, it will be an empty string when editable and null when only display
- Set: string
- Clears the value when null is set
Numeric-type
- Get: Big Object
- If the value is not set, it will be null
- Set: Big object/string/Number object/numeric
- If it is a string, the value will be set in the input field as it is
- If other than string, it sets the string whose value has been converted according to the format of the Data Item definition into the input field
- Clears the value when null is set
About Big object
- You can generate an object using new Big("string")
- You can get value in string format using toString()
- Format of string: period as decimal separator, no delimiter (e.g.1234.56)
- See big.js Documentation for the details
Select-type
- Get: Array of objects
- The object has value (choice ID) and display (display label) as properties.
- If not selected, the array will be empty
- Set: string or string array
- String will be the choice ID
- If an array of multiple elements is passed to a single selection (other than a checkbox), the first value will be set
- If you set an empty array or null, the value will be cleared (deselected)
User-type (Ver. 14.0 -)
- Get: User object
- The object has id (numeric), name (string) and email (string) as properties.
- If the value is not set, it will be null
- Set: string
- String will be the Email Address
- The user with the specified email address is set to the value
- If you set null, the value will be cleared (deselected)
Organization-type (Ver. 14.0 -)
- Get: Organization object
- The object has id (numeric), name (string) and email (string) as properties.
- If the value is not set, it will be null
- If the retained value is a deleted organization, id will be null
- Set: string
- String will be the organization name
- The organization with the specified name is set to the value
- If you set null, the value will be cleared (deselected)
Other Data-types
(Not available)
1-3. Script Examples
Title
Get
let title = qbpms.form.get("title");
Set
let strTitle = "PROCESS TITLE";
qbpms.form.set("title", strTitle);
String-type
Get
let string = qbpms.form.get("q_string");
Set
qbpms.form.set("q_string1", "STRING");
qbpms.form.set("q_string2", "ORANGE\nAPPLE\nPEACH\nGRAPE"); //multiple lines
Numeric-type
Get
let strNum = "null";
let obj = qbpms.form.get("q_numeric");
if (obj !== null) {
strNum = obj.toString();
}
Set
qbpms.form.set("q_numeric1", "1001.101");
qbpms.form.set("q_numeric2", new Number("1002.102"));
qbpms.form.set("q_numeric3", new Big("1003.103"));
qbpms.form.set("q_numeric4", 1004.104);
Select-type
Get
let array1 = qbpms.form.get("q_radioButton");
let display1 = array1[0].display; //display label
let array2 = qbpms.form.get("q_checkBox");
let value2 = array2[1].value; //Choice ID of the second choice
Set
qbpms.form.set("q_radioButton", "true");
qbpms.form.set("q_selectBox", ["true", "false"]); // "true", the first one, will be set
qbpms.form.set("q_checkBox", ["true", "false"]);
User-type (Ver. 14.0 -)
Get
let userName = qbpms.form.get("q_user").name;
Set
qbpms.form.set("q_user", "yamada@example.com");
Organization-type (Ver. 14.0 -)
Get
let orgId = qbpms.form.get("q_org").id;
Set
qbpms.form.set("q_org", "Sales");
Other Data-types
(Not available)
2. Registering and Deleting Event Handlers
* To avoid conflicts with what is used in Questetra, define your own function's name/element ID to start with "user_".
2-1. Form-wide Event
2-1-1. Script format
Registering event handler
qbpms.form.on(EVENT-TYPE, EVENT-HANDLER)
Deleting event handler
qbpms.form.off(EVENT-TYPE, EVENT-HANDLER)
- Event-type: "ready"
- Event handler: Is a function, which has one parameter that is an event object
2-1-2. Event-type
ready
- Fires when the form is displayed and the form API is available
- If registered after displaying the form, the event handler will be executed immediately
- Event object is fixed
2-1-3. Script example
"Hello world!" Is displayed in the message dialog when the Operating Form screen is displayed
function user_readyHandler(e) {
window.alert("Hello world!");
}
qbpms.form.on('ready', user_readyHandler);
2-2. Data Item Event
2-2-1. Script Format
Registering event handler
qbpms.form.on(EVENT-TYPE, FIELD NAME, EVENT-HANDLER)
Deleting event handler
qbpms.form.off(EVENT-TYPE, FIELD NAME, EVENT-HANDLER)
- Event-type: "change"
- Field Name: "title" or "q_field_name" (Field Name of the Data Item)
- Event-handler: Is a function, which has one parameter that is an event object
2-2-2. Event-type
change
- Fires when the value of an editable Data Item input field changes
- Fires when the value is set by qbpms.form.set (/em>, in addition to manually changing the value
- Supported Data-types
- Title/String-type/Numeric-type/Select-type
- Event object properties
- type: "change"
- varName: Field Name
- value: A value to be set (Same as those got by qbpms.form.get())
2-2-3. Script example
Display a message dialog when the value of the target Data Item changes
function user_addedQbpmsEvent(e) {
window.alert("VALUE CHANED:" + e.value);
}
qbpms.form.on('change', 'q_string1', user_addedQbpmsEvent);
Comments
0 comments
Article is closed for comments.