Form Display Conditions

Form Display Conditions—also known as Form Filtering or Form Display Logic—are used to filter the content of your CommCare application for a specific use case.

When should I use a form display condition?

Use Form Display Conditions when you have a form that you only want available to a specific group of users or cases. When you put a display condition on a form, it is only accessible on CommCare Mobile when a given user or case matches criteria you've previously defined.

For example:

• you have a form that you want to be available only to certain types of users (in this workflow, you'll use user properties, rather than case properties, as your filter) 

• you have a form that is only relevant to patients with a positive test result.

• you have two versions of a form - one for children under one year of age, and one for all other children- and you want to make sure the user only chooses the correct form.

Watch the introduction video on Form Display Conditions

Getting Started

How do I set up a form display condition?

• On the form's settings page, outside of the Form Builder, you can specify a display condition.  The display condition determines whether or not the form shows up in the form menu.  

• You can view this field by selecting the button with three-bars in the top right hand corner and selecting to display the 'Logic' field

• For this to work, the user must select the case BEFORE filling out the form.  This means that the "Menu Mode" setting on the module must be set to "Display module and then forms", and every form in the module must require a case.

• It accepts the same kind of logical expressions as the Form Builder (see sections above), EXCEPT you must add ./ before any case property name. (For example, in Form Builder, you’d reference something as /data/edd. Here, it would simply be ./edd)

• For example, write the following to say the expected delivery date (property name "edd") must be within the next week:  today() - ./edd <= 7

• You can also refer to properties of some special cases too.

  • Use "#user" to refer to user case properties. e.g. #user/experience_level > 3

    • If a user does not have a value for the case property, you will see an error that says: "Logic references instance(commcaresession)/session/user/data/(...) which is not a valid question or value".

    • In order to avoid this, add an if() statement to check whether the case property exists first. For example:

      • if(count(instance('commcaresession')/session/user/data/USER_PROPERTY) > 0), instance('commcaresession')/session/user/data/USER_PROPERTY = 1, 0)

  • Use "#parent" to refer to the parent case of a child case. e.g. date(#parent/dob) >= date('1997-01-01')

  • Use "#host" to refer to the host case of an extension case. e.g. #host/suburb = #user/suburb
    

• Referencing lookup tables on a form display condition uses a slightly different syntax than in app-builder. Here are some examples :

  •  instance('item-list:country')/country_list/country/id != "kenya"

  • instance('item-list:user_permissions')/user_permissions_list/user_permissions[user_role=#session/user/data/user_role]/f_register_household = '1')

How will this affect exports?

Each form will have a unique form export available in the data export tab on CommCareHQ. Although you may be have multiple forms in an application, form filtering will hide these based on the display logic. As a result, form submissions will only display for the forms that were actually submitted.

For example – Let’s say you have three forms all named “Child Form”, but you use form filtering to divide this for children <1 year, 1-2 years, and 2-3 years. Although on the mobile it may appear as only on form, using form exports, this will display as 3 unique forms, and the form submission will display for its respective forms. 

Other Helpful Notes:

• If working with a J2ME/Java/feature phone and are in Sense Mode, the numbering will automatically update. For example, if you have 5 forms in your app, but one has a display condition such that it is not relevant to the selected case, CommCare will re-number the forms as 1-4.