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 the Building a Simple Form Tutorial.

To open the form builder:

  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 a form name 

 

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.

  • Time: collects time 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 about Using Repeat Groups in the Form Builder.

  • 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 in the Hidden Value Calculations Tutorial.

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 about a Lookup Table.

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 about Integrating Android applications with CommCare.

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

Note: If the form will be deployed in more than one language, a field is displayed for each language.

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

Note: Responses to form questions are reported in relation to question IDs.

  • 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.

Copy: copies a question or group of questions.

Note: This tool can be used to move single or multiple (CTRL +SHIFT) questions to a different portion of a form or into a separate form. If a question is copied into a group where a question ID is already in use, "copy-1-of-" will be prefixed to the Question ID, while the Labels and Choice Values/Labels will remain the same.

Display: changes the question tree to display by question id rather than language (default)
Expand All: opens all groups and choices for multiple choice and checkbox questions
Collapse All: hides all groups and choices for multiple choice and checkbox questions
Display: language of the Question Tree
Expand Editor: opens the editor in full screen mode
Export Form Contents: exports questions and properties to Microsoft Excel
📖Learn more about Export Form Contents.

Edit Source XML: opens form XML code for editing

Note: This is feature is recommended for advanced users only.

Form Properties: displays properties of forms such as Form ID
📖Learn more about Form Properties.

Find usages: searches question or case property references within a form by question ID
Edit Bulk Translations: opens form translations in a new window that can be copied and edited in Microsoft Excel
📖Learn more about Edit Bulk Translations.

Question Property Tools


• Question Type menu: changes a question type

Note: All choices in a multiple-choice question should be removed prior to changing a question type.

Delete: deletes a question or group of questions

Note: This change cannot be undone.

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

📖Learn more about Common Logic and Calculations.

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

📖Learn more in the Display Conditions Overview.
Note: The expression editor can be used to aide in adding conditions.
📖Learn more in the Tutorial section on the Expression Editor.

  • Validation Condition: ensures responses meet specified constraints

Note: Does not apply to all question types.
📖Learn more about Basic Validation Conditions.

    • Default value: displays a value upon accessing a form question which can be changed by the user
    • Media: add audio, image, and video files to questions

📖Learn more about Multimedia in CommCare.

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 about Advanced CommCare Android Formatting.

  • 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

Note: This is especially useful for us on devices that Java chat applications.

▫   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 Use Excel to Build CommCare Forms.


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



  • No labels

3 Comments

  1. Anonymous

    Regarding how to use Multiple Choice responses in skip logic:  Though the system will automatically convert the MC to 1, 2, etc. when putting the question out via SMS, to use the question in skip logic later on the form you need to test not for whether it equals 1,2, etc., but rather for whether it equals the Item Value name.  Note this needs to be treated as a text string, not a variable name, so use quotes and note also that it's case sensitive.

    1. All display conditions and validation conditions refer to question IDs and item values, not to Display Text. As such, you do need to capitalize appropriately. Also, in the Advanced Expression Editor in Display and Validation Conditions you can just drag questions from the Question Tree, which minimizes errors.

  2. Hello - below are some resources that might help you:

    1. Beginner Tutorial - goes over basic form building and use of skip logic
    2. Common Logic and Calculations - has detail on how to use skip logic in more advanced ways.