Hidden Value Calculations Example 1: Adding Two Questions using a Hidden Value
Let's revisit our Beginner's Tutorial form:
Right now, we ask how many boys and girls are still alive that the woman gave birth to. However, let's say we also just want to have a way to reference the total number of children to determine the sum of the number of boys and girls.
Add a Hidden Value by selecting 'Add Question' and then selecting Hidden Value:
This should look familiar, but also a little bit different. Unlike all of the other question types, the Hidden Value only has a Question ID- no label text. This makes sense, because the user is not going to see anything so there is no need for text to be visible.
By default, two properties are displayed:
- Calculate Condition- this is something new! Instead of a validation condition, we have something that we can use to do complex calculations with the data collected in CommCare. We are going to primarily work with this part of the Hidden Value.
- Question ID - this is an internal identifier for the question. This will be how the data is identified in any exports you perform.
To add a display condition to the hidden value, we need to select the menu item in the top right hand corner of form builder and open the Logic Section:
Display Condition- this is the same as in the other questions you have worked with. "Edit" opens the expression builder, or you can type directly in the box. To review the use of display conditions, see the Beginner Tutorial.
But what does it mean to put a "display condition" on something that is never displayed to the user? Great question!
- You can put a display condition in a hidden value
The hidden value will simply hold an empty value (i.e., be blank) until its display condition is met, regardless of the calculate condition. Once its display condition is met, it holds the calculated (using the calculate condition) or loaded (using case management) value.
- If you are using case management to update the case from a hidden value, it will only update the case if its display condition on the hidden value is met.
Default Value - This field allows you to enter a preset value for the question. This will be the stored value by default unless otherwise altered. For example, you could choose to store a case property in this hidden value by default, and then use the calculate condition to update the value stored to the hidden value.
Does it matter where in the Question Tree the hidden value is?
It doesn't matter where you put a hidden value - it can be in the middle of a form or at the end and will not affect calculations or anything else.
Click on "Edit" next to Calculate Condition to see the following:
Now this looks different! Unlike the Display and Validation conditions there is no expression builder immediately visible. If you want to see the Expression Builder you can click on the "Show Simple Mode" button in the top right. However, the Expression Builder, with its limited abilities, is almost never useful for building Calculate Conditions.
The Expression Editor (Advanced) will not help you write anything, but it will help you by "checking" what you write to make sure there are no major errors. When you press "save", CommCare will quickly look at the expression you have written and return an error message if there is a problem.
Okay, let's get back to our first hidden value.
- Change the Question ID to total_children.
We want this hidden value to calculate the number of total children, so we'll sensibly name it "total_children" so it will be easy to interpret when we are looking at the data exports.
- Click on "edit" next to Calculate Condition
- Click and hold on the question "How many living boys?" in the Question Tree and drag it into the Edit Expression (Advanced) box:
- When you see the green check mark in the box you can release. CommCare will then translate that into a blue question Reference:
You can hover your mouse over the reference and you can see details about the question.
- Type "+" next to the living_boys reference in the Expression Editor (Advanced ) box to indicate you want to add the value of that question
- Click and hold on "How many living girls?" in the Question Tree and drag it over to the box until you see the green check mark:
- Release and you will be able to see the full "XPath Expression":
- You can now click "save" to store the expression and make sure you don't have any errors.
This is a simple expression so you should not see any error messages. After clicking "save" you should see your expression here:
Congratulations, you have successfully done your first Hidden Value calculation!
This is easy. Can't I just write that directly in the calculate condition box?
The answer is yes, you can directly write these expressions in the Calculate Condition box. However, we strongly recommend that you open the Expression Editor (Advanced) box and use the drag-and-drop method. Dragging the hidden values ensures that there aren't any spelling errors or confusion. It can be very frustrating when there is a small spelling error. Additionally, if you type directly into the "Calculate Condition" box, CommCare will not validate that the expression will work. This means that you might get an error message only when you try to build your application or use it on your mobile device.
In short, only write directly in the Calculate Condition box if you are sure you know what you are doing- even the Dimagi CommCare field team uses the Expression Editor (Advanced) box, so you are in good company going that route!
You may want to do other types of math. There is a full list of supported expressions here but the basic math functions are as follow:
|Action||How you write it in Calculate Condition|
In the next part of the tutorial, you will carry out a calculation using a date type question.