Advanced CommCare Android Formatting
Table of Contents:
- 1 A few things to keep in mind
- 2 Appearance Attribute - Overview
- 3 Appearance Attribute Examples and Instructions
- 3.1 Audio Widgets
- 3.2 Automatic Advancing
- 3.3 Automatic Advancing with Images
- 3.4 Editable Barcode Scan Result
- 3.5 Force capture for audio/video/image widgets
- 3.6 GPS Capture using Google Map
- 3.7 Grid View
- 3.8 Notification Label
- 3.9 Radio Buttons Aligned with Label
- 3.10 Combined Multiple Choice Using a Question List Group
- 3.11 Selectable Label Text
- 3.12 Short Text Entry Widget
- 3.13 Single Line Numeric Entry
- 3.14 Single Select "Dropdown"
- 3.15 Single Select "Combo Box"
- 3.16 Multiple Select Dropdown
- 3.17 Date formatting option that enables adding a nullable date
- 4 Hint and Help Text
- 5 Media Options
- 5.1 In-line Video
- 6 Text Formatting
- 7 Text To Speech
Items on this page are useful for formatting in CommCare apps and are described below. Most of them require you to edit an "Advanced" field of your question. The Advanced section of the https://dimagi.atlassian.net/wiki/x/PDHKfw is by default collapsed/hidden since most fields are not relevant; however it can be displayed via the form builder by selecting Advanced from the drop down menu immediately to the right of the red Delete button.
A few things to keep in mind
Some of these appearances must be configured by advanced modification of forms. You can request better form builder support for these formatting options by reaching out to support@dimagi.com. All supported formatting options are listed on this page. If you use a formatting option found in XLSForms, we cannot guarantee compatibility with CommCare.
Please note that these configurations apply to CommCare mobile apps, and some do not work with https://dimagi.atlassian.net/wiki/x/sgHKfw or Web Applications. To see comparable formatting options for Web Apps, go to https://dimagi.atlassian.net/wiki/x/rQTKfw. In order to confirm that these advanced formatting attributes are working, you will need to test the application in the appropriate place for your project, whether that is a mobile device or Web Apps.
Appearance Attribute - Overview
By editing the appearance attribute��or making other advanced changes in the Form Builder, you can do some very nice things with your form structure while working in CommCare for Android and Web Apps. The options listed here are supported as of CommCare 2.9
In the form builder the Appearance Attribute field can be found near the bottom of the Advanced section of the Question Properties:
Appearance Attribute Examples and Instructions
Audio Widgets
Not supported on App Preview
Beginning in CommCare 2.50, a new audio widget is used. This widget does not standardly include the ability to upload audio; however, this can be accomplished in two ways.
Set an Audio question's Appearance Attribute to: acquire-or-upload
This will allow the user to choose between selecting audio or recording it.
Set an Audio question's Appearance Attribute to: legacy
This will use the previous audio widget and retain the old functionality
Automatic Advancing
Not supported on App Preview
You can have your form advanced to the next screen automatically upon choosing an answer. This works for single select multiple choice questions only (not for checkbox / multiple-select).
Be careful when deciding to use this because if the user accidentally chooses an answer they will be advanced to the next screen and will need to be comfortable swiping back to make the change/correction.
How to do it
In the Advanced section of the Question Properties, set the field Appearance Attribute to: quick
Note: As of CommCare 2.45, you cannot use the appearance attribute "quick" with the last question of a form to auto-submit a form.
Automatic Advancing with Images
Not supported on App Preview
You can have your form advanced to the next screen automatically upon choosing an answer. This works for single select multiple choice questions only (not for checkbox / multiple-select).
Consider making this a required question, so that a button must be selected to continue.
How to do it
In the Advanced section of the Question Properties, set the field Appearance Attribute to: quick compact
For a screen, two images wide use: compact-2.
For a screen. three images wide use: compact-3.
Editable Barcode Scan Result
Not supported on App Preview
The barcode question widget allows you to scan a barcode and store the result as a string. At times it is useful to be able to edit that string after scanning.
How to do it
In the Advanced section of the Question Properties section set the Appearance Attribute to: editable
Force capture for audio/video/image widgets
Not supported on App Preview
The audio/video/image capture widgets by default allow you to either capture new media or select a file from your device. In some situations one might want force the user to capture new media and not have the option to choose a media file. This is possible by following the directions below.
How to do it
In the Advanced section of the Question Properties section set the Appearance Attribute to: acquire
GPS Capture using Google Map
Not supported on App Preview
GPS question can be configured to:
Allow user to select their location on Google maps by clicking on "Record Location" button.
Allow user to see the recorded location on Google maps by clicking on "Show Location" button.
How to do it
In the Advanced section of the Question Properties section set the Appearance Attribute to: maps
Grid View
Not supported on App Preview
You can create a grid of possible answers using only images and have the user just click on the image. This works for multiple choice questions that are either single or multiple answer. You can see an example of this at the ODK website.
How to do it
In the Advanced section of the Question Properties, set the field Appearance Attribute to: compact
If, for example, you want the grid to be two items across you can add "-2" so it will look like: compact-2
Notification Label
Not supported on App Preview
Notification labels are a special type of label text which is displayed at the bottom of the screen.
It can appear in 3 different colors. It will appear based on what display condition you set in the label.
How to do it
You need to put all of the questions in a Question List Group.
On each label, access the Advanced section of the Question Properties. Then set the field Appearance Attribute to:
Radio Buttons Aligned with Label
Not supported on App Preview
This is a way of displaying the values of a select list of circular radio buttons horizontally instead of in a vertical list.
How to do it
Create a Single Select list question. In the Advanced section of the question properties set the Appearance Attribute to list.
Combined Multiple Choice Using a Question List Group
This is a way of combining questions that have the same answers. It requires creating a "throw-away" question that is used to set the header (i.e. in the example below, "Chose for each: Yes No" is a single select question for which data is not captured).
How to do it
You need to put all of the questions in a Question List Group.
The first question will define the headers (so you will not be able to actually record data for it). For that first question, in the Advanced section of the Question Properties, set the field Appearance Attribute to: label
The subsequent questions in the group should have appearance set to: list-nolabel
Below is an example of what this looks like in the form builder:
Selectable Label Text
Not supported on App Preview
By default, label text cannot be selected when filling out a form. This is to make the user interface simple and to avoid confusing mobile workers that unintentionally long-press during form entry. However, this also means that it is not possible to select and copy label text into another location.
It is possible to enable selectability of label text by changing the appearance attribute in the form builder.
How to do it
In the Advanced section of the Question Properties section set the Appearance Attribute to: selectable
Short Text Entry Widget
Not supported on App Preview
The text input widget, by default, would give users an option to enter new line in the soft keyboard. But in some situations like question list, you might wanna restrict the new line behaviour and configure the enter key of soft keyboard to either jump user to the next input question or simply close the keyboard if there aren't any more input questions.
.
How to do it
In the Advanced section of the Question Properties section set the Appearance Attribute to: short
Single Line Numeric Entry
Not supported on App Preview
CommCare by default displays the questions input box in the next line below the label. However, you can configure the questions input to be displayed inline with the question label as shown in the image below -
How to do it
This behavior is achieved by putting all the questions inside the Question List Group, then grouping the Question List inside a Group and setting its Appearance Attribute to: compact
Below is an example of what this looks like in the form builder:
Note: Make sure to add the appearance attribute minimal for all the label questions
Limitations
It only works for questions with numeric input i.e. either an Integer or Decimal. From CommCare 2.51 onwards, we'll also support text input questions.
All other question components apart from question label and input doesn't show up in single line data entry. Ex- Multimedia, help text, hint text etc.
Question label truncates itself if it doesn't fit in the available space and there is no way to see the whole text of the question currently.
Single Select "Dropdown"
How to do it
In the Advanced section of the Question Properties, set the field Appearance Attribute to: minimal
Notes
If the label text of a choice is very long it may be cut off in the dropdown view. The basic rule is that the text can only be as long as the width of your device. The text will not wrap onto a second line.
Single Select "Combo Box"
This is similar to the single select dropdown, but it also allows you to filter the dropdown list by typing in a text box. When possible, it will also try to prevent users from entering text that is not part of a valid answer.
How to do it
There are 3 different variations of a combo box available, which use different rules for how they filter answer choices in the dropdown menu based upon the text that the user has entered:
Standard - This option is recommended for if your question has simple, mostly one-word answer choices. The filter matches on prefixes, i.e. entering the text "ap" would show "Apple" and "Apply", but not "Cape"
Multiple Words - This option is recommended for if your question has more complicated, mostly multiple-word answer choices. The filter checks for matches on individual words that appear anywhere within the entered text. On Web Apps, the fuzzy matching approach typically yields better results than Multiple Words.
Fuzzy Matching - This option is recommended for if your question has more complicated answer choices that you expect users might misspell or mistype. The filter is more permissive and will show answer choices that are deemed similar to the entered text.
In the Advanced section of the Question Properties, set the field Appearance Attribute to: combobox fuzzy
Technical note: "fuzziness" is largely based on edit distance, which calculates how similar the search string is to the options. CommCare also does some special case handling, in particular to handle searches that match the beginning of one or more of the options (as when the user has started typing out a long option).
Multiple Select Dropdown
This is similar the the single select dropdown above, but for a multiple select question. In the example below you can see two multiple select dropdown questions that are in a question list group. The user pushes "select answer" and then chooses from the pop-up menu. The selected answers are then recorded on the question screen. This may work well to enable users to "confirm" the answers they have selected.
How to do it
In the Advanced section of the Question Properties, set the field Appearance Attribute to: minimal.
Date formatting option that enables adding a nullable date
You can use this functionality to have a nullable date in your form.
The date question appears as shown below. The User will have to click on for the date to be saved as null.
How to do it
In the Advanced section of the (Date) Question Properties, set the field Appearance Attribute to: gregorian_cancel. (Separately, for just using this UI for the date question, set the field Appearance Attribute to: gregorian)
Limitations
The name of the day will continue to show on the UI even after clicking on:
- although it won't be saved.
If the user does not wish to answer the question or misses the question, the default value of the question will be saved as today's date.
Hint and Help Text
Hint Message
Hint message is a special type of label text which is displayed below the label text. It appears slightly smaller and is meant to provide clarification to the question. Only the first 1-2 lines of a hint message is displayed by default, just click on the text once to see the full text.
Help Message
Help text is similar to Hint Text, exactly that you can view the text by clicking on a small information icon which appears next to the question:
Media Options
CommCare has some advanced options for how to display media that you include in your mobile app.
In-line Video
Not supported on App Preview
Generally when adding a video to a question in CommCare, a small play button is added to the upper right corner. Clicking on this play button opens the video in the device's media player:
However it is also possible to play a video in-line within CommCare. This means the user never leaves CommCare and switches to the media player. However it also means that the video may be smaller:
How to do it
Find the question/label with the place where you want the video to be.
Under Media click video-inline.
Upload the video using the pop up.
Text Formatting
You can make text on CommCare Android and Web Apps display in bold, italics, strikethrough, and various sizes. For more information see Text Formatting (Markdown).
Text To Speech
Not supported on App Preview
CommCare 2.51 introduces Text-To-Speech functionality. When used, CommCare will add a button next to each question (except for audio questions), tapping on which it'll convert that text to speech. This button is not shown by default, but can be shown in two ways.
Users can enable the Text To Speech settings from the CommCare Settings menu. In this case the text-to-speech engine will convert the question text to speech.
App Builders can add a tts field to the questions in the Add Other Content section in HQ. In this case the text-to-speech engine will convert the tts field value to speech.