Beginner Tutorial Part 5 - Adding Complexity to a Form
How to make questions required
How to add a display condition using the Expression Builder
How to add a validation condition using the Expression Builder
To start, from Part 3 of the tutorial you developed a simple form that looks something like this:
We did this by working with the Main Properties of each question, which included the Question ID and the Label Text. Now we are going to work with the Logic Properties section.
Click on the first question in the Question Tree (i.e. Village Name). Then add the Logic section by selecting the drop down menu in the top right hand corner of the question properties section. Once added, scroll down to Logic Properties in the Question Properties frame.
There are two sections here:
Display Condition ("Skip logic")- this is where you can determine when a question is relevant and should be displayed. For example, in our form the question "how many living boys?" should not be displayed if the woman answers "no" to the question "Has the woman given birth to children that are still alive?" Â Don't worry, we'll fix that!
Validation Condition- this is where we can limit the acceptable answers to a question. For example, if we are asking age, we might not want the mobile user to accidentally put 200 instead of 20, so we can put a reasonable limit on age- say that the age must be between 15 and 60. If a mobile user then puts something outside of that range they will get an error message and will be prevented from going on to the next question.
Let's start using these tools!
Requiring Questions
It is good practice to make questions required if you are confident everyone should be able to answer them. This prevents a mobile worker from accidentally skipping questions. In this example, let's say that the following questions should be required:
woman_name
village_name
lmp
Go to each of the above questions and put a mark in the box for "Is this Question Required?"
Â
Display Condition
We want to put a display condition on the question living_boys because this question should only be shown if the answer to the question "Has the woman given birth to children that are still alive?" is "yes."
Where do I put my display condition?
You always put a display condition on the question that is affected by the answer to another question- NOT on the question that determines whether or not a subsequent question is shown. For that reason we call it a "display condition" and not a "skip condition." In this example, you put the display condition on living_boys because sometimes we want to see that question, and sometimes we don't.
Â
Navigate to the question living_boys and find "Display Condition" under "Logic Properties"
Click on the "edit" button on the right side.
This will give open the Expression Editor - use it to help write the expressions that will determine your display conditions. It may look confusing, but don't panic!
Let's think through what we want to do here. Â We want to show this question (living_boys) if the answer to living_children is 'yes'
In other words, the display condition is:Â living_children = 'yes'Â (If living_children = 'no' we want to skip this question)
You can use this tool to help write that expression. Focus on the Configure Expression section.
Click on the question "Has the woman given birth to children that are still alive?" in the Question Tree and drag it over to the box on the left.
You will see a green check mark when you are hovering over it:
When you let go you will see that CommCare has created a blue reference in the box. You can hover your mouse over the reference to see the full text of the question:
Right now there is an error indicator because the expression is incomplete:
Â
We need to specify what we want the answer to living_children to be!
You can use the same method as before- grab the answer "yes" and drag it into the box on the right:
You'll see a green check because your expression is now complete.Â
Click on "Save" to keep your changes.
Â
Back on the main screen you will see that CommCare is now showing the complete expression!
Now build the same display condition thing for the question living_girls
Â
Â
Do I have to use the Expression Builder? Can't I just write the display condition directly?
Yes, you can just write the display condition directly in the Question Properties. However, we strongly recommend that you start by using the Expression Builder to get comfortable with the syntax used in CommCare forms. You can write fairly complex expressions using the Expression Builder, including long AND and OR statements. When you want to start composing expressions directly you can click on the "Show Advanced Mode" button in the Expression Editor. Using Advanced Mode will automatically check your statement for basic errors.
Â
Â
Validation Conditions
Great work, now we're ready for a validation condition
Our goal here is to put a validation condition that prevents the user from writing a number higher than 15 for the number of boys or the number of girls.
So what we want for the question living_boys is that the answer must be less than or equal to 15. Or, to put it another way: living_boys <= 15
We can again use the expression builder to help!
Go to the question living_boys and click on the "edit" button next to Validation Condition
The editor looks very familiar!
Â
Drag the question living_boys (yes- that's the same question you are working on) over to the left side of the expression.
When you refer to the same question you are working in, CommCare just puts a nice little "." in the box, so it should look like this:
Now, to continue our expression:
Change the middle drop-down menu to "less than or equal to" and then just write "15" directly in the second box, so it looks like this:
Go ahead and hit "save" to see the expression on the main page:
It is good practice, whenever you make a validation condition, to make a validation message that explains what the validation condition is. That way the mobile user can understand how to correct the error and how they should be able to proceed.
In the "Validation Message" box type: "The number of living boys must be less than or equal to 15!"
Don't forget to save your changes.
Add the same validation condition for the question living_girls and add a Validation Message as well:Â "The number of living girls must be less than or equal to 15!"
Â
Test Your Changes
Now that we've added a bit of complexity to the form, let's test those changes! Open App Preview and select the refresh button to get the latest changes to your app!
Â
Once you're satisfied, you can go ahead to next section, and test your form on a phone!
Go to the next section, Part 6.
Â
Â