Skip to end of metadata
Go to start of metadata

You are viewing an old version of this page. View the current version.

Compare with Current View Page History

« Previous Version 24 Next »

WARNING: These are advanced configurations

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!

Application Preview

Please note that these configurations apply to Web Apps. To see comparable formatting options for CommCare Mobile go to Advanced CommCare Android Formatting. If you would like to confirm 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.


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 Form Builder 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. 

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. Utilize multiple appearance attributes simultaneously by entering them separated by spaces.

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


Collapsible Groups

In Web Apps, groups can be configured to show a bordered box with a header. Clicking on the header will then show or hide the questions inside the group:

Collapsible groups can be nested inside each other:

If a closed collapsible group contains a required question, the group header will be marked with an asterisk:

When the group is opened, the asterisk will disappear from the header since it's now visible on the question:

If a closed group contains a question with a validation error, the group header will be marked with a warning icon:

When the group is opened, the warning icon will disappear from the header and be visible on the question with the error, along with the error message:

How to do it

In the Advanced section of the Question Properties section, you'll mark the group as collapsible and whether you want it to be open or closed when the form loads.

If you wish to have the group open when the form is first opened, set the Appearance Attribute to: group-collapse collapse-open

If you wish to have the group closed when the form is first opened, set the Appearance Attribute to: group-collapse collapse-closed

Collapsibility is only supported for Group questions, not for Question List questions or Repeat Group questions. However, you can nest a question list or repeat group inside of a collapsible group.

Collapsible group headers do not support markdown. Any markdown that you use in the Group question's Display Text will be displayed as plain text.

Collapsible groups are available only on web apps, not on mobile devices or in App Preview.



Single Select Button - Appearance Attribute

With the "button-select" appearance attribute, a multi-select question can be formatted as simple buttons, displaying a single-select to the user. With this feature, the user can toggle different questions within the multi-select as a single select question.

We are also able to use alignment values to align the button toggle. When using alignment appearance attributes text-align-center and text-align-right, the element position will adjust based on the screen width or other entry fields, except for labels, for better custom positioning.



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

This structure can also work for multi-select checkbox questions.


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:


 View Example XML

Below is an example of the xml.

For the first question:

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

For the subsequent questions:

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




Single Select "Dropdown" or "Combo Box"

This dropdown also allows you to filter the 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

In the Advanced section of the Question Properties, set the field  Appearance Attribute to:  minimal

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


 View Example XML

Here is an example of the xml:

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





Multiple Select Dropdown

This is similar the the single select dropdown above, but for a multiple select (checkbox) question type.


How to do it

In the Advanced section of the Question Properties, set the field  Appearance Attribute to: minimal



12-Hour Time

Time questions display in 24-hour format by default, but they can be change to a 12-hour format with an AM/PM option:

How to do it

In the Advanced section of the Question Properties, set the field  Appearance Attribute to: 12-hour



Question Tiles ("n"-per-row / “n”-per-row-repeat)

In Web Apps, questions can be configured as a Tiled Question, which will take up a different amount of space on the screen, with the ability to be "tiled" horizontally with other questions. Normally, all questions are tiled vertically, but Tiled Questions may be tiled horizontally.

How to do it

For all questions that are not Repeat Groups:

In the Advanced section of the Question Properties, set the field Appearance Attribute to:  "n"-per-row where "n" is any integer (i.e. 3-per-row). This needs to be updated for each question you wish to include in a row with a "tiled" format. 

For Repeat Groups:
Place the Repeat Groups within a Group. In the Advanced section of the question Group’s Properties, set the field Appearance Attribute to:  "n"-per-row-repeat where "n" is any integer (i.e. 3-per-row). This will apply the “n”-per-row attribute to each Repeat Group within that Group.

For example:

image-20240226-184737.png
  • “3-per-row-repeat” appearance attribute is configured on Group3

  • repeat_count of 2 is applied for each subrepeat group

image-20240226-184730.png

  • The left form builder configuration results in the above layout

This appearance attribute can be used in combination with others; these just need to be space-separated.

An example implementation of this feature can be found in the ush-feature-training template app.


Question Text Alignment

In Web Apps, questions and labels are left-aligned by default. But, they can be configured as center or right-aligned as well. The question text alignment is compatible with several other advanced Web App formatting options listed on this page.

How to do it

In the Advanced section of the Question Properties, set the field Appearance Attribute to:
text-align-right: If you wish to have the question text right-aligned.
text-align-center: If you wish to have the question text center-aligned. 

The alignment attributes can be appended to the existing appearance attributes of a question. e.g., ‘3-per-row text-align-center’ can be used to create a question tile with center alignment.

 

Limitation

Text alignment can be used for questions within "Groups" but is not compatible with "Groups" question types. It is also incompatible with "Collapsible Groups". 



Question input size

The default width for question inputs is the full width of the page, but input widths can be adjusted to be smaller.

How to do it

In the Advanced section of the Question Properties, set the field Appearance Attribute to:
short: In order to set the width of the input to ~20% of the width of the page in which it is housed.
medium: In order to set the width of the input to ~30% of the width of the page in which it is housed.

In the examples below see that the Name question has the appearance attributes set, while the phone question maintains the default width.



Single-Select Button

Displays a single-select multiple choice question as a simple button. No question label, help message, or hint text is shown in Web Apps. 

The button shows display text for the next choice, which will be selected when it is clicked. Clicking the button cycles through choices in order.

How to do it

In the Advanced section of the Question Properties for a single-select multiple choice (not checkbox) question, set the field Appearance Attribute to: button-select



Striped Repeat Groups

Applies subtle row shading and a highlight effect to alternating questions within a group or repeats in a repeat group.

How to do it

Nest a repeat group under a group. The group will be used for styling and can have its Display Text left blank.

In the Advanced section of the group's Question Properties, set the field Appearance Attribute to: stripe-repeats. Note that this is on the outer question group, not the repeat group itself (example configuration here)


If this appearance attribute is applied to a group without a nested repeat group, the questions within the group will be highlighted with alternating stripes. 


Hint as Placeholder

Set input placeholder text as hint text. This will also hide the hint text to eliminate redundancy and clutter.

How to do it

Set hint message as described below.

Then in the Advanced section of the Question Properties, set the field Appearance Attribute to:
hint-as-placeholder


Border Outline

Create a black border outline around a group of content in the form

How to do it

Create a question group that holds the content you want to enclose in the border. In the Advanced section of the group's Question Properties, set the field Appearance Attribute to: group-border (example configuration here)


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:

 


Text Formatting

You can make text on CommCare Web Apps display in bold, italics, strikethrough, and various sizes. For more information see our guide on Text Formatting (Markdown).

  • No labels