The Form Builder is a tool used to create and manage forms in CommCare applications. There are several features of the form builder and it is essential to understand their function prior to getting started.

📖 Before you begin, review https://dimagi.atlassian.net/wiki/x/bwrKfw.

To open the form builder:

1. Login to CommCare

2. Navigate to the Dashboard

3. From the Applications section, click an application name

Open

4. From the left navigation panel, click a form name 

Open

The question tree for the form is displayed.

Question Tree

The question tree displays all contents of a form and allows for editing and adding questions. It is structured in a branched view for ease of navigation.

To add questions to a form:

1. Navigate to an application of interest

2. Open the Form Builder

3. From the question tree, click the Add Question drop-down

4. Select the question type of interest

Note: The drag-and-drop method can be used to organize questions in the question tree after they are created. The question tree can be displayed by question ID rather than language by changing the Display setting in the Form Tools menu.

Question Types

There are several question types available for use in forms that capture data in multiple ways. Some require advanced formatting skills.

• Text: open question that allows users to type responses

• Multiple Choice

• Multiple Choice: a question with multiple choices that requires only one to be selected

• Checkbox: a question with multiple choices that allows more than one to be selected

• Number

• Integer: a whole number
  Note: Values must be greater than 1 but smaller than 2,147,483,647.

• Phone Number or Numeric ID: any identifiable telephone number including those beginning in zero (0)

• Decimal: an un-whole number (Ex: 0.25)

• Date

• Date: collects a date inputted by the user
  Note: On an Android device, the format of a date is determined by the language settings for the device. On WebApps, the accepted input formats are as follows (in order of preference, and note the delimiter matters as part of the format):

  • 'MM/DD/YYYY'

  • 'YYYY-MM-DD'

  • 'M/D/YYYY'

  • 'M/D/YY'

  • 'M-D-YYYY'

  • 'M-D-YY'

  • ISO8601 format

  • If you enter a date with a two digit year, the widget uses logic to figure out which year: currentYear - 90 <=  *inputYear* <= currentYear + 10

• Time: collects a time input from the user based on device time zone settings
  Note: If device time zone settings are unavailable, time is collected in UTC (Coordinated Universal Time).

• Date and Time: collects both date and time

• Groups

• Group: a container for questions
  Note: Questions within a group are displayed in the question tree under the group heading.

• Repeat Group: a container for questions relating to a named element (Ex: Child)

📖 Learn more at https://dimagi.atlassian.net/wiki/x/pC7Kfw.

• Question List: list of questions that will be grouped onscreen in a form
  Note: Applicable only to ODK code and Android devices. A question list does not require a label or display text.

• Media Capture

• Image Capture: captures an image
  Note: Images are stored in JPEG format.

• Audio Capture: captures an audio recording
  Note: Applies to Android devices that support 3GA file types. Consider downloading an audio recorder if needed such as RecForge Lite.RecForge Lite Audio Recorder

• Video Capture: captures a video recording
  Note: Applies to Android devices only.

• Signature Capture: captures a signature written with the user's finger on a mobile device.
  Note: Applies to Android devices only. The signature is saved as a PNG file available for download from CommCareHQ.

• Label: displays text only
• Hidden Value: used for calculations and referencing data points from other forms, modules, or applications within a project

📖 Learn more at https://dimagi.atlassian.net/wiki/spaces/commcarepublic/pages/2143954977.

• Lookup Tables

• Multiple Choice Lookup Table: a multiple-choice question that populates choices from a lookup table.

• Checkbox Lookup Table: a checkbox question where the choices are populated from a lookup table.

📖 Learn more at .

• Advanced

• GPS: enters a GPS reading from a user's device

• Barcode Scan: activates a barcode scanner to capture information
  Note: A barcode scanner must be separately installed.

• Password: user inputted text with characters displayed as an asterisk (*)

• Android App Callout: advanced feature that uses integrated information from an external application

📖 Learn more at .

Question Properties

After adding questions, the content, structure, and function of the questions are controlled with properties.

To access question properties:

1. Navigate to an application of interest
2. Open the Form Builder
3. From the question tree, click a question of interest

The question properties window is displayed.

Note: More than one user can make changes to a form simultaneously. CommCare will prompt users to overwrite current changes or revert to the last saved version of the form if this occurs. When managing form properties, it is recommended that changes are saved often. CommCare will prompt mobile users to save changes prior to exiting a form in an application.

• Display Text: text displayed to mobile users

• Question ID: unique ID for questions displayed in reporting features but not visible to mobile users

• Requirement: marks questions mandatory so they cannot be unanswered
  Note: Users receive an error message if a required question is skipped.

Form Tools

Once questions are added to a form and properties are set, form tools can be used to manage views, export data, edit source code, etc. Some functions in this menu are appropriate for use by advanced users only. 

To access form tools:

1. Navigate to an application of interest

2. Open the Form Builder

3. Click the menu icon next to the form name

The form tools menu will be displayed.

Question Property Tools

• Question Type menu: changes a question type

• Delete: deletes a question or group of questions

• Show menu: displays options for sections of form properties to be displayed or hidden

•  

  • Logic: controls when questions are asked and what questions are valid

• Display Condition: (also referred to as skip logic) determines conditions under which questions are displayed

• Validation Condition: ensures responses meet specified constraints

  • Default value: displays a value upon accessing a form question which can be changed by the user

  • Required Condition: determines conditions under which questions are required. Only functional if the Required checkbox is enabled.

• Media: add audio, image, and video files to questions

Advanced: used for formatting applications using advanced features such as writing XML code for logic

• Validation Error Message: displays a message when a user response does not meet specified constraints
  Note: Messages are specific to the deployed language of the form.

• Data parent: links a form question as a child of another question

• Appearance Attribute: defines an appearance for questions
  Note: This is especially helpful for advanced formatting.

📖Learn more at .

• Comment: a field to add notes about application design choices (Example: question purpose, hidden value explanation)
  Note: Comments are only visible as a bubble above Question Properties in the Form Builder.

• Hint Message: displays a message below label text to provide clarification to a question
  Note: Messages over two lines of text are cut off after the character display limit is reached. Users can click a message to see full text.

• Help Text: provides additional information about questions
  Note: Users will click the information icon to see full text.

• Add Help Media:displays media to aid users in responding to questions

• Add Other Content: text displayed to users
  Note: Display text should be included for each language of application deployment.

▫   Short: abbreviated version of display text

▫   Long:  long version of display text

Frequently Asked Questions

Q: How do I edit the source code of a form?
A: To edit source XML:

1. Navigate to the Form Builder.

2. Click the Form Tools menu dropdown.

3. Select Edit Source XML.

4. Click Update Source when finished.

Q: Can I copy a form from one application to another?
A: Yes. Download the form locally from its original location and upload it to the new location.

To copy a form to a different application:

1. Login to CommCare

2. Navigate to the Dashboard

3. From the Applications section, click an application name

4. From the left navigation panel, click the gear icon next to title of the form of interest

5. Click the Actions tab.

6. In the XForm section, click Download.

7. Open the destination application.

8. Add a new form.

9. Repeat steps 4-5.

10. In the XForm section, click Upload.

11. Choose the form that was downloaded from the source application.

Note: Case save and load properties are preserved with this method. If only certain questions are needed from a particular form, the copy and paste method should be used to paste them into the new form.

Q: Can I use a different program to create my form?

Yes, please see .

For best practices for application creation and tips from our global Field Managers see .

Command Bar in Form Builder

To assist with application building efficiency, we created a feature for use in formbuilder that allows you to add questions via a command bar interface. You can now quickly add questions to your form without having to use your mouse!

How to Use

To open the command bar when in form builder, you can use the following shortcuts:

• For Mac: ⌘ + ;

• For Windows: Control + ; 

Once the command bar is open, you can enter a command and press <Enter> to execute it. Currently there are two command types: Add a New Question and Jump to Question.

Add a Question

To Add a New Question, there are three parts to the input:

1. Question Type

   1. This refers to the various question types used in CommCare (i.e. Text, Integer, Date, etc.).

2. Position (optional)

   1. This command will allow you to dictate where the question is placed in the form. There are currently 4 commands:

      1. Before: Used to put a question before another one

      2. After: Used to put a question after another one

      3. In: Used to place a choice in a Multiple Choice or Checkbox question or inside a Group based question (Groups, Repeats or Question list)

      4. First In: Used to place a choice in a Multiple Choice or Checkbox question or inside a Group based question (Groups, Repeats or Question list)

   2. If you do not specify a position the new question will be added after the currently selected question

3. Question ID (optional)

   1. This is the question you would like to place the question type near, relevant to the position you input in the second step.

   2. The currently selected question will be used if you do not specify a Question ID.

   3. This section will always start with #.

When entered in the command bar, the format will look like:

<Question Type> <position>  #form/<question_id>

Jump to Question

For the Jump to Question command, there is one part to the input: the question path. When entered in the command bar, the format will look like:

#form/<question_id>

Example: Add a New Question

We have a registration form in an application tracking the outcome of a woman’s pregnancy. We want to get information regarding the mother’s age, but forgot to add a question asking it. Let’s do that now.

Using the shortcut (Control + ;  for Windows or ⌘ + ; for Mac)  will open a command bar at the top of the question tree:

Selecting the bar that states “Enter Command” will open a drop-down window with the various question types you can add to a form:

 (Note: This field should be auto-selected after using the shortcut) 

Since we want to ask about the mother’s age, we will want to add an integer question. We’ll also want to place the question after the ‘Village Name’ question (question_id = village_name). So, we’ll want to enter the following into the command bar:

• Integer after #form/village_name

Once we input this text and hit enter, an Integer based question will be added to formbuilder. Since we used the after position, it will appear after the question, “Village Name”

After adding the question, you should automatically have the new question selected so that you can continue using your keyboard to fill out the Display Text.

Notes/Caveats

• Each command will auto-fill so you can use your arrow keys to move up and down the list to select the appropriate question type, position or #form/<question> that you want to select.

• Hitting <Tab> will auto-complete the current argument and move the cursor so you can start typing the next argument.

• When entering a command, it is not necessary to type out each argument entirely. For example, to add a new label after the current question one can simply type Ctrl+; to open the command bar, then L so Label is the top/selected option in the auto-complete list, then <Enter> to execute the command.

• In and First In are used for multiple choice, checkbox or group based questions.

• When using Jump to Question it is not necessary to type the exact question path. Instead you can type # followed by part of the question ID or path. For example:
  Ctrl+; #age <Enter>