Perform Processing When an Event Occurs on the Form Screen

In the following three articles, you will learn the basic usage of the Questetra Form JavaScript API available for form screen decoration.

• Retrieve/Set Data Item Values on the Form Screen
• Perform Processing When an Event Occurs on the Form Screen
• Perform Your Own Input Checks on Form Screens

This series of articles is a split and re-edited version of Using [Questetra Form JavaScript API] on the Form Screen.

1. Detecting Events on Form Screens

The Questetra Form JavaScript API can detect when the value of a Data Item is changed in a form screen (change event) or when the display of a form screen is completed (ready event).

By writing code to process when these events are detected, the operation that counts the number of characters when a button is clicked can be changed to count the number of characters when the input value is changed.

In order to process an event when it is detected, it is necessary to register an event handler that defines the event to be detected and processed. In this article, you will learn how to use event handlers for the change event of Data Items (input fields) and the ready event of form screens.

• Registration/deletion of change event handlers for Data Items on the form screen
• Registration/deletion of ready event handler on the form screen

For details on available event handlers, see reference R2132: Questetra Form JavaScript API.

2. Data Item Change Event

We will implement a process to count the number of characters entered so that it will operate when the change event of a Data Item (input field) occurs. Through this implementation, you will learn how to register/delete event handlers for Data Items on the form screen using the Questetra Form JavaScript API.

We’ll continue to use the workflow App created in the “Preparing a Workflow App” section of the article Get/Set Data Item Values on the Form Screen. If you have not yet created one, please refer to the previous article to create a new workflow App for the sample.

Write sample code that performs the following processing when a button is clicked.

• Registers the change event handler for the “Text Input” Data Item by clicking the [Register Event] button
  • When the change event triggers, the number of characters in the input string is counted and the count result is set to the “Character Count” Data Item
• Deletes the change event handler from the ” Text Input” Data Item with a click of the Delete Event button
  • Disables processing when the change event is triggered

Questetra Form JavaScript API registers/deletes event handlers for Data Items in the following format.

• Register a change event handler for a Data Item
  • qbpms.form.on(
    ‘change’,
    ‘{data item field name}’,
    {event handler} );
• Remove the change event handler from the Data Item
  • qbpms.form.off(
    ‘change’,
    ‘{data item field name}’,
    {event handler} );

※ Note that it is on/off, not get/set.

The change event handled in this chapter is strictly different from a change event in HTML.
For example, qbpms.form.set( ‘{data item field name}’, {value to be set} ); The change event handler fires even at runtime (when not losing focus).

2.1. Code Setup

Set the following code in the Description field of the Data Item “Character Count”.

<button type="button" onclick="user_registerHandlers()">Event Registration</button>
<button type="button" onclick="user_deregisterHandlers()">Event Deletion</button> 
<script>

//  "Text Input" Data Item ChangeEvent Handler Registration Process
function user_registerHandlers(){
  qbpms.form.on('change', 'q_Input_Text', user_countInputText);
}

// "Text input" Data Item ChangeEvent Handler Deletion Process
function user_deregisterHandlers(){
  qbpms.form.off('change', 'q_Input_Text', user_countInputText);
}

// Character Counting Process
function user_countInputText(){

  //Obtaining the value of the "Text Input" Data Item
  const strInputText = qbpms.form.get('q_Input_Text');

  // Counting the number of characters and setting the value of the number of characters in the "Character Count" Data Item
  qbpms.form.set('q_Characters_Count', strInputText.length);
}
</script>

After setting the code, display the “H1. Input” process preview screen. If two buttons [Event Registration] and [Event Deletion] are added under the Data Item “Character Count”, the settings are complete.

2.2. Operation Check

Let’s check the operation of the script you have written. Open the preview screen of the “H1. Input” step.

Let’s enter appropriate characters in the “Text Input” Data Item and trigger the change event (remove focus from the input field). The number of characters entered is not yet displayed in the “Character Count” field. This is because the change event handler for “Text Input” is not yet registered and enabled at this point, so the character count process will not work.

Click on the [Event Registration] button. The change event handler is now registered, and the character count will be processed when the change event is triggered.

Again, enter appropriate characters in the “Text Input” field and trigger the change event. Now, each time the change event for “Text Input” is triggered, the number of characters entered is displayed in the “Character Count” field.

Next, click on the [Event Deletion] button. The change event handler is now deleted and the character count process is no longer invoked.
Even if you trigger the change event for “Text Input” the character count process will no longer be performed.

By registering/deleting change event handlers for Data Items, it was possible to control the execution of the process to be operated when the event is triggered.

3. Ready Event on the Form Screen

The registration of the change event handler, which was done when the [Event Registration] button was clicked, will be changed so that it is automatically done when the form screen is displayed. Through this implementation, you will learn how to register the ready event handler on the form screen using the Questetra Form JavaScript API.

Write sample code that performs the following processing when the form screen is displayed.

• Registers the ready event handler for the form screen
  • When the ready event fires, the change event handler for the “Text Input” Data Item is registered.
    • When the change event fires, the number of characters in the input string is counted, and the count result is set in the “Character Count” Data Item.

Questetra Form JavaScript API registers/deletes event handlers to/from the form screen in the following format.

• Registering a ready event handler to a form screen
  • qbpms.form.on(
    ‘ready‘,
    {event handler});
• Removing the ready event handler from the form screen
  • qbpms.form.off(
    ‘ready‘,
    {event handler} );

※ Note that this is a ready event, not a change event, and that the Data Item (field name) is not included in the argument.

3.1. Code Setup

Set the following code in the Description field of the Data Item “Character Count”.

<script type="text/javascript">

// Character count process
function user_countInputText(){

  // Process to obtain the value of the "Text Input" Data Item
  const strInputText = qbpms.form.get('q_Input_Text');

  // Count the number of characters and set the character count value to the "Character Count" Data Item
  qbpms.form.set('q_Characters_Count', strInputText.length);
}

// "Text Input" Data Item ChangeEvent handler registration process
function user_registerHandlers(){
  qbpms.form.on('change', 'q_Input_Text', user_countInputText);
}

// Form ReadyEvent handler registration process
function user_onReady(){
  qbpms.form.on('ready', user_registerHandlers);
}

// Execute the form ReadyEvent handler registration process
user_onReady();

// Execute form ReadyEvent handler deletion process
// qbpms.form.off('ready', user_registerHandlers); // Commented out, process disabled
</script>

After setting the code, display the preview screen of the “H1. Input” step. If the two buttons [Event Registration] and [Event Deletion] disappear from under the Data Item “Character Count”, the settings are complete.

3.2. Operation Check

Check the operation of the script you have written. Open the preview screen of the “H1. Input” step.

Let’s enter appropriate characters in the “Text Input” field and trigger the change event. When the form screen is displayed (when the ready event is triggered), the change event handler is registered in the “Text Input” field, so the number of characters is automatically counted.

The input character count process now operates with the form screen display without the need to click on a button, etc. The usability for the Operator has been improved by making the process available when the screen is displayed.

Although not mentioned in the sample, the code qbpms.form.off(‘ready’, user_registerHandlers); can be used to disable registration of the process that counts the number of characters entered. Please try to modify the sample code to remove the event handlers on the form screen.

In this article you learned how to use the Questetra Form JavaScript API to register/delete event handlers for Data Items on the form screen and on the form screen itself.
The next step is to use what you have learned so far to implement your own input checks on the form screen.