Overview

Skill Level: Any Skill Level

IBM Forms Experience Builder allows custom Javascript attached to the Properties of each field. Here's how to perform basic calculations and output the results to the front-end fields.

Ingredients

Access to edit a form on IBM Forms Experience Builder (https://w3-01.ibm.com/tools/cio/forms)

Step-by-step

  1. What We Will Accomplish:

    This screenshot shows you what this recipe will accomplish. This is an example that you may use, tweak, or customize for your own purposes to perform calculations or other scripting logic for your FEB application.

    s1

    We will use various fields (Number, Numeric Slider, and Select One) and add their values together. Then we will output the result into a read-only field to be displayed back to the user after clicking the “Calculate Addition” button.

  2. Let’s Begin: Drag a New Field into Your Form (or Select an Existing Field)

    Every field in FEB can hold a value, that captures data in various forms, such as numbers or letters (strings). For the first part of this example, I will perform calculations on numerical data, so I will use the Number field.

    Picture1

    Drag and drop this field into your form.

    s2

  3. Select "Edit Properties"

    In the top-right corner of the field, select the gear icon (“Edit Properties”):

    s3

  4. Edit Title and ID

    In the “Basic” tab, we can change the field title from “Number” to something else.

    4a

    In the “Advanced” tab, we can set the ID of the field. The ID is important for it will be used in our Javascript to refer to this specific field. It must be unique and ideally easily identifiable. In FEB, a field ID must begin with “F_”. For this example, I am naming this field ID: “F_Q1” to signal that it will serve as Question 1 in our example survey.

    4b

    Click the “OK” button when done.

  5. Preview Changes

    Our field for Question 1 is now ready. If you click the preview button (preview) in the top-right, you can test this field in action:

    5a

    The Number field will show an error for alphabet or non-numeric characters.

    5b

    By default, the Number field will round to two decimal places. To change this feature, you can choose “Type” and “Decimal Places” under the “Advanced” tab above.

  6. Using the Numeric Slider field

    Let’s do the same with the Numeric Slider field. Drag and drop the field into your form and click the “Edit Properties” icon.

    6-1

  7. Set the Value Properties

    The Numeric Slider field allows the user to drag to select its number value. Edit the Title as needed, then enter your chosen Start and Stop Value, as well as the Number of Ticks you’d like the slider to provide.

    7-1

  8. Set the ID

    In the “Advanced” tab, set the Numeric Slider’s ID to a unique identifier to be used in the Javascript. As this field will serve as Question 2 in my example, I named the ID “F_Q2”.

    8-1

  9. Feel Free to Preview the Numeric Slider

    9-1

  10. Using the Select One Field

    For our final question, we will drag and drop the Select One field into our form.

    10

  11. Input Value Properties

    For the Select One field, the user will be able to select one out of various options. These choices can be displayed however you choose, with an underlying unseen value we can use in our calculations. In “Edit Properties”, we can choose how many options the user will have and what they say under “Displayed Value”. For each “Displayed Value”, the “Saved Value” will be recorded as the value of this field should the user select that option.

    11

  12. Set the ID

    In the “Advanced Tab”, remember to make the ID unique and easily identifiable for our Javascript code.

    12

  13. Feel Free to Preview the Select One field

    13

    (the choices can be displayed horizontally or vertically under “Edit Properties” -> “Advanced” -> “Choice Layout”)

  14. Create the Calculate Button

    Open the “Specialized” menu on the left, then drag and drop Button into your form.

    14

  15. Edit Properties

    Click the “Edit Properties” icon to change the caption as necessary and navigate to the “Events” tab. This is where we will write our custom Javascript. Our intention is for the user to click this button to perform a calculation using the values of our three questions. For this example, this button will calculate the sum of these values.

    15

  16. Click onClick

    Because we want the calculation performed when the user clicks our Button, we will input our code under the onClick event. When you click the link, this screen will pop up for us to input our code.

    16

  17. Writing the Javascript Code

    Here, I will go into detail on how to write our code for our purposes. Since we want to add the values of each of our questions, we need to first get each question value.

    To access a value, we can use the term BO which stands for “Business Object”. Then to specify which field we want to access, we use its ID – for instance, “F_Q1” as set in Question 1, our Number field. To tell the program that we want to retrieve the value, we use the function getValue(). This results in:

    BO.F_Q1.getValue();

    We got the value, but that is not enough because we need to store the value to use later. We store data in variables, signified as “var” with a label we set ourselves. For the value of Question 1, I will store it in a variable I simply call “a”

    var a = BO.F_Q1.getValue();

    This process can easily be repeated for the other two questions. Each field in FEB has a value regardless of its type, so we can use the same method to get all three question values into three different variables

    var a = BO.F_Q1.getValue();
    var b = BO.F_Q2.getValue();
    var c = BO.F_Q3.getValue();

    We now have all three question values stored into three different variables.  To add them together, we simply use “+” on all three of our variables. Let’s store this into a variable too:

    var ans = a + b + c;

    Looking at our solution so far, it should be straight-forward. We extract the value of each field into variables, then store the sum into another variable. However, there is one not-so-noticeable problem. If we tested the code as-is, the calculation would be incorrect:

    17a

    Why does this happen? The short answer: We need to tell the code that we want to add numbers, not strings.

    In Javascript, the “+” operator can perform either addition or string concatenation depending on the type of variables it is used on. If the variables are numbers, it will add them. If one or more are strings, it will concatenate them, or join them together to form one string. In our example, we want to add numbers, so we should make sure the variables a, b, and c are numbers.

    In FEB, the Number and Numerical Slider fields store their values as numbers. However, the Select One field does not. This is because the Select One field can also store strings as their value, so the default value type is string. Even though we set the Saved Values as numbers, they are actually stored as strings.

    This means, if we kept the calculation as-is, the “+” operation will think we are adding strings and not numbers. We will use the above screenshot to demonstrate how the calculation went wrong. Here is the break-down of what is happening to the variables in our code:

    var a = BO.F_Q1.getValue(); // 1
    var b = BO.F_Q2.getValue(); // 3
    var c = BO.F_Q3.getValue(); // “2”
    var ans = a + b + c; // 1 + 3 + “2” -> 4 + “2” -> “4” + “2” -> “42”

    We need to explicitly tell the code that we want to add the values as numbers. There are several different ways to do this, but an easy one is to use a Javascript function called Number(). In the most simple terms, this function simply turns the data it is used on to a number.

    Since the only variable that is not a number is c, we can safely use only use it on c. However, if you are not fully sure if a variable is being read as a number or not, feel free to use it on as many variables you need to be numbers.

    Here we use the function on our variable c:

    var c = Number(BO.F_Q3.getValue());

    Our code should now look like this and perform accurately.

    17b

    However, one thing is missing. We have the sum answer stored in our variable ans but want to display it back to the user. Click the OK button when done with this step.

  18. Create a Single Line Entry field

    Drag and drop a Single Line Entry field into your form. This will serve as a read-only field that displays the answer to the user.

    18

  19. Edit Properties

    Set its Title as “Answer” and rename its ID to something unique and easily identifiable in your code. Click the OK button when done.

    19

  20. Set the Value of “Answer” in the Javascript Code

    Open the onClick event code again (“Edit Properties” on our Button -> “Events” tab -> “onClick”). Now we add a line of code to set the value of our “Answer” field. The value will appear in the white box under the title “Answer”.

    BO.F_Ans.setValue(ans);

    So now the value stored in the variable ans will show up under “Answer”. Click OK when done.

    20

  21. Set the Answer as Read-Only

    Our final missing piece is a nice-to-have feature. By making the Answer field read-only, this prevents the user from erroneously editing the field to fabricate the answer.

    Save (21a) your form and navigate to the “Stages” tab at the top of your screen. Scroll down to your Answer field and click the lock button on the right side. This sets the field as read-only. To set it back to editable, just click it again.

    21b

     21c <- If you see this icon, this field is editable. Click to make it read-only.

    21d <- If you see this icon, this field is read-only. Click to make it editable.

  22. Save and Preview Your Work. You’re Done!

    This recipe is intended for beginner FEB users to learn how to access and manipulate the data stored in FEB. Although I simply added values in this recipe, you can easily apply the same concept to subtract, multiply, perform string operations, and more! Using getValue() and setValue() on BOs is only scratching the surface of what Javascript in FEB can do.

     

    For more information, feel free to refer to the official IBM FEB Javascript API Structure (https://www.ibm.com/support/knowledgecenter/en/SS6KJL_8.6.1/FEB/ref_javascript_api.html) and this wiki page on Javascript Functions in FEB (https://www.ibm.com/developerworks/community/wikis/home?lang=en#!/wiki/W65fd19fc117a_4d18_87e4_5f7b8a6727cc/page/JavaScript%20Functions).

Join The Discussion