Using [Questetra Form JavaScript API] on the Form Screen

1. Customize the Form Screen

In Questetra BPM Suite you can decorate and customize form screens using HTML / JavaScript, to perform such actions as:

• Display explanatory text such as precautions for data entry
• Decorate the text to be displayed
• Display links to websites for reference
• Automatically count the number of input characters
• Add input checks of your own　　　　　　　etc.

Form screen decoration and customization can be done by writing HTML or JavaScript in the Description field of the Data Item settings (including for Guide Panel-type). For customization using JavaScript, you can use the Questetra Form JavaScript API (in Professional Edition).

The following can be achieved by using the Questetra Form JavaScript API.

• Getting/assigning input field values
• Registering/deleting change event handlers for input fields
• Registering/deleting a ready event handler for a form

The next chapter explains the actual usage of Questetra Form JavaScript API through sample code.

The Questetra Form JavaScript API is guaranteed to work, but other JavaScript codes are not guaranteed to work. Please consider the need for future maintenance when using it, as there is a possibility that the behavior may change in future versions.

2. Using Questetra Form JavaScript API

2.0. (Advance Preparation) Create a New Workflow Application

Create a new workflow application and open the edit screen.

2.0.1. Setting Up Workflow Diagrams

Place one Swimlane, one Start Event, one Human Task, and one End Event in the Workflow Diagram tab. For the Human Task, rename the task “H1. Input”.

2.0.2. Data Item Settings

Add and set the Data Items as follows.

2.0.3. Confirmation after Setup

Click the Form Preview button to open the Form Preview screen.
The setup is complete when the Data Items [Text Entry] and [Character Count] are displayed on the preview screen as input fields respectively.

2.1. Get/Assign Input Field Values

In this section we will incorporate a process into the form screen that counts the number of characters entered when a button is clicked. Through this implementation, you will learn how to get/assign values to input fields.

The description method using Questetra Form JavaScript API is as follows.

• Get the value from an input field
  • const value = qbpms.form.get( ‘{data item field name}’ );
• Assign a value to an input field
  • qbpms.form.set( ‘{data item field name}’, {value to be assigned} );

※ Please refer to the reference page R2132: Questetra Form JavaScript API for details on the data types and restrictions of the values you want to get/assign.

2.1.1. Setting Codes

Paste the following code into the description field on the Character Count Data Item settings screen and click [Apply and Save].

<button type="button" onclick="user_countInputText()">Character Count</button> 
<script>
function user_countInputText(){

  // Retrieving values from input fields
  const strInputText = qbpms.form.get('q_Input_Text');

  // Counting the number of characters and assigning the result of the count to the input field
  qbpms.form.set('q_Characters_Count', strInputText.length);
}
</script>

This code does the following.

1. Adds the button [Character Count] and sets the processing when the button is clicked
2. Definition of function “user_countInputText()” for processing when the character count button is clicked
   • Obtains the value entered from the [Text Entry] input field
   • The number of characters entered is counted and set to the [Character Count] input field

To avoid conflicts with those used in Questetra, define your own function names/element IDs to begin with “user_”.

After setting the code, a [Character Count] button will be added below the [Character Count] input field. Reload the form preview screen for confirmation.

Once you have confirmed that the [Character Count] button has been added, release the workflow application.

2.1.2. Operation Check

Check the operation of the incorporated code. Start a new workflow application process and open the “H1. Input” task processing screen.

Enter appropriate characters in the [Text Entry] input field and click the [Character Count] button. The number of characters entered in the [Text Input] input field is now displayed in the [Character Count] input field.

Processing that displays the number of entered characters each time the [Character Count] button is clicked has been added.

2.2. Register/Delete Event Handlers for Input Fields

In this section, we will make the processing of counting the number of entered characters work when the change event of an input field occurs. Through this implementation, you will learn how to register/delete event handlers for input fields.

The description method using Questetra Form JavaScript API is as follows.

• Register an event handler for an input field
  • qbpms.form.on(
    ‘change’,
    ‘{data item field name}’,
    {function to be called when the event occurs} );
• Remove the event handler from the input field
  • qbpms.form.off(
    ‘change’,
    ‘{data item field name}’,
    {function to call when an event occurs} );

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

2.2.1. Setting Codes

Overwrite the codes in the Description field of the [Character Count] Data Item by pasting the following codes, then click [Apply and Save].

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

// Register processing when a Change event occurs
function user_registerHandlers(){
  qbpms.form.on('change', 'q_Input_Text', user_countInputText);
}

// Delete processing when Change event occurs
function user_deregisterHandlers(){
  qbpms.form.off('change', 'q_Input_Text', user_countInputText);
}

// Processing when an event occurs
function user_countInputText(){

  // Retrieving values from input fields
  const strInputText = qbpms.form.get('q_Input_Text');

  // Counting the number of characters and assigning the result of the count to the input field
  qbpms.form.set('q_Characters_Count', strInputText.length);
}
</script>

This code does the following.

1. Adds the buttons [Event Registration] and [Event Deletion] and sets the processing when each button is clicked
2. Definition of functions for registration/deletion of event handlers to be called when each added button is clicked
   1. The function user_registerHandlers() registers a change event handler to the input field [Text Entry]
   2. The function user_deregisterHandlers() removes the change event handler from the input field [Text Entry]
3. The function user_countInputText() counts the number of characters entered

When the code is set, the [Character Count] button disappears and two buttons [Event Registration] and [Event Deletion] appear instead. Reload the form preview screen for confirmation.

After confirming that the button has been changed, release the workflow application again.

2.2.2. Operation Check

Check the operation of the incorporated code. Start a new workflow application process and open the “H1. Input” task processing screen.

Let’s enter the appropriate characters in the [Text Entry] input field and then move the focus to trigger the change event in this field. I believe that the number of entered characters is not displayed in the [Character Count] input field. In fact, at this stage, the processing when the change event occurs in the [Text Entry] input field has not yet been registered.

Now click on the [Event Registration] button. Now the processing when the change event occurs has been registered, and the character count will be performed.

Let’s try typing the appropriate characters in the Text Entry field again. Each time a change event occurs in the Text Entry field, the number of entered characters is now displayed in the Character Count field.

Next, click on the [Event Deletion] button. This deletes the processing that runs when the change event occurs and disables the character count processing. Even if you enter the appropriate character in the [Text Entry] input field, and move the focus to trigger the change event in [Text Entry], the character count processing will no longer be performed.

It is now possible for addition and deletion of processing that displays the number of entered characters each time a change event occurs.

Let’s study it further.

2.3. Register/delete ready event handlers on form screens

In this section, we will challenge configuring that when the ready event of the form screen occurs, the processing of counting the number of entered characters is registered.
Through this exercise you will learn how to register/delete ready event handlers on form screens.

The description method using Questetra Form JavaScript API is as follows.

• Register a ready event handler to a form screen
  • qbpms.form.on(
    ‘ready‘,
    {function to be called when the event occurs} );
• Remove the ready event handler from the form screen
  • qbpms.form.off(
    ‘ready‘,
    {function to be called when the event occurs} );

※ Note that it is a ready event, not a change, and that the Data Item is not included in the argument.

2.3.1. Setting Codes

Paste the following code into the Description field of the Data Item [Character Count] for overwriting it, and then click [Apply and Save].

<script type="text/javascript">

// Processing when an event occurs
function user_countInputText(){

  // Retrieving values from input fields
  const strInputText = qbpms.form.get('q_Input_Text');

  // Counting the number of characters and assigning the result of the count to the input field
  qbpms.form.set('q_Characters_Count', strInputText.length);
}

// Register processing when a Change event occurs
function user_registerHandlers(){
  qbpms.form.on('change', 'q_Input_Text', user_countInputText);
}

// Add processing to be executed when the form is displayed (ready)
// Call the change event handler registration function so that the function for the data item [Text Entry] is enabled.
function user_onReady(){
  qbpms.form.on('ready', user_registerHandlers);
}

user_onReady();
</script>

This code does the following.

1. Registers a ready event handler on the form screen
   1. When the ready event occurs on the form, the function user_registerHandlers() is called and the change event handler for the input field [text input] is registered
2. When the change event of the [Text Entry] input field occurs, the function user_countInputText() is executed to process the character count

Once the code is set, the two buttons [Register Event] and [Delete Event] that were displayed in 2.2.1 will disappear and return to the same look and feel as the workflow application in the 2.0.3 prep stage. Please recheck the form screen.

Release the workflow application again after confirming that the button has been removed.

2.3.2. Operation Check

Check the operation of the incorporated code. Start a new workflow application process and open the “H1. Input” task processing screen.

Let’s enter appropriate characters in the [Text Entry] input field and then move the focus to trigger the change event of [Text Entry]. Since the character count processing for the change event is registered at the time of the form’s ready event (i.e. screen drawing), the character count processing for the [Character Count] input field is now performed automatically without the need to click on any button.

It is now possible to automatically count the number of characters entered without having to click on any buttons. I think this is a further improvement in usability over what we have implemented up to now.

2.4. Application) Perform your own input checks on form screens

Let’s try an application based on the knowledge gained through the practice of the samples so far.
We will try to incorporate our own numerical value checks on the client side into the form screen.

2.4.1. Add Data Item Unique Numerical Checks

Add new Data Items as follows.

2.4.2. Setting Codes

Paste the following code into the description field of the added Data Item values, and click Apply and Save.

<div id="user_num_error">
 The values do not meet the requirements
</div> 
<script>
qbpms.form.on('ready', () => {

    // Display/hide errors
    const setErrorVisible = (visible) => {
        const span = document.getElementById('user_num_error');
        span.style.visibility = visible ? 'visible' : 'hidden';
    };

    // Validation
    const validateNum = () => {
        const num = qbpms.form.get('q_num');
        if (num === null) {
            return;
        }
        const condition = qbpms.form.get('q_condition')[0];
        switch (condition.value) {
            case '>=0':
                // num < if 0 display error
                setErrorVisible(num.lt(0));
                break;
            default:
                // num > if 10 display error
                setErrorVisible(num.gt(10));
        }
    };

    qbpms.form.on('change', 'q_num', () => {
        validateNum();
    });
    qbpms.form.on('change', 'q_condition', () => {
        validateNum();
    });

    validateNum();
});
</script>

This code does the following

1. The following is the definition of registering a ready event handler to the form screen and processing (anonymous function) when the ready event of the form occurs.
   1. Validation function validateNum()
   2. setErrorVisible() function for displaying/hiding error messages based on validation results
   3. Process for registering a change event handler to the [Numeric Value] input field.
   4. Registering a change event handler into an [Numeric Condition] input field.

When you are ready to do so, release the workflow application again.

2.4.3. Operation Check

Check the operation of the incorporated code. Start a new workflow application process and open the “H1. Input” task processing screen.

First, select the option “greater than or equal to 0” for the [Numeric Condition] radio button, enter the value “-1” in the [Numeric Value] input field, and then move the focus to trigger the change event. The value entered in [Numeric Value] does not satisfy the [Numeric Condition], so the validation error “Numeric does not satisfy the condition” will be displayed.

Next, change the value of the [Numeric Value] input field to “11” and trigger the change event. This time the numeric condition is met, so the validation error “Numeric value does not meet the condition” will be hidden.

In this state, let’s select the choice “less than or equal to 10” for the [Numeric Condition] radio button.　The numeric condition will not be met again and the validation error “Numeric value does not meet the condition” will reappear.

When a change event occurs for each of the input fields [Numeric Value] and [Numeric Condition], their input contents are validated and an error message is displayed if there is an error.
Please check the behavior of the message by changing the input contents of [Numerical Value] and [Numerical Condition], or by adding or changing the contents of the options or switch to case statements in the code to switch between displaying and not displaying the message.

3. Summary

How was it? We hope you have gained an understanding of how to use the Questetra Form JavaScript API by actually running the sample code up to this point.

Customization of the form screen, such as adding client-side custom input checks, can help improve usability.
(Checking for incomplete input at the back-end process after the task processing button is pressed reduces the number of cases where the task is sent back, etc.)

Questetra Form JavaScript API can customize form screens more conveniently depending on your ideas and usage. Please try out customizing your form screens.