R2132: Questetra Form JavaScript API

 

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", "[e-mail]");

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);