Advanced CommCare Android Formatting

Table of Contents:

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

1. Set an Audio question's Appearance Attribute to: acquire-or-upload

   1. This will allow the user to choose between selecting audio or recording it.

2. Set an Audio question's Appearance Attribute to: legacy
   

   1. 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:

1. Allow user to select their location on Google maps by clicking on "Record Location" button.

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

1. You need to put all of the questions in a Question List Group.
   

2. On each label, access the Advanced section of the Question Properties. Then set the field  Appearance Attribute to: 

   1. floating-good - for a green label message

   2. floating-caution - for a yellow/orange label message

   3. floating-bad - for a red  label message

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:

             <select1 ref="/data/test_combined_appearance/like_choices" appearance="label">
				<label ref="jr:itext('like_choices-label')" />
				<item>
					<label ref="jr:itext('like_choices-yes-label')" />
					<value>yes</value>
				</item>
				<item>
					<label ref="jr:itext('like_choices-no-label')" />
					<value>no</value>
				</item>
			</select1>

          <select1 ref="/data/test_combined_appearance/like_blue" appearance="list-nolabel">
				<label ref="jr:itext('like_blue-label')" />
				<item>
					<label ref="jr:itext('like_blue-yes-label')" />
					<value>yes</value>
				</item>
				<item>
					<label ref="jr:itext('like_blue-no-label')" />
					<value>no</value>
				</item>
			</select1>

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

<select1 ref="/data/spinner_test" appearance="minimal">
			<label ref="jr:itext('spinner_test-label')" />
			<item>
				<label ref="jr:itext('spinner_test-1-label')" />
				<value>1</value>
			</item>
			<item>
				<label ref="jr:itext('spinner_test-2-label')" />
				<value>2</value>
			</item>
			<item>
				<label ref="jr:itext('spinner_test-3-label')" />
				<value>3</value>
			</item>
			<item>
				<label ref="jr:itext('spinner_test-4-label')" />
				<value>4</value>
			</item>
		</select1>

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:

1. 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"

   1. In the Advanced section of the Question Properties, set the field Appearance Attribute to: combobox

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

   1. In the Advanced section of the Question Properties, set the field Appearance Attribute to:  combobox multiword

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

   1. In the Advanced section of the Question Properties, set the field Appearance Attribute to:  combobox fuzzy

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

1. Find the question/label with the place where you want the video to be.

2. Under Media click video-inline.

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

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

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