Skip to content

Commit 485fe4f

Browse files
salomegarnierAmandaJ-W
salomegarnier
and
AmandaJ-W
authored
Publish XLSForm support articles (#467)
Co-authored-by: Amanda <[email protected]>
1 parent 02e0f3c commit 485fe4f

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

48 files changed

+3090
-829
lines changed

‎source/_static/files/getting_started_xlsform/sample_xlsform.xlsx‎

10.7 KB
Binary file not shown.

‎source/_static/files/select_from_map_xls/Placeholder.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
Placeholder

‎source/_static/files/select_from_map_xls/SelectFromMap.xlsx‎

16.4 KB
Binary file not shown.

‎source/_static/files/select_from_map_xls/cities1.csv‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
name,label,geometry,info,marker-color,marker-symbol
2+
1,Warsaw,52.2297 21.0122 0 0,Capital city of Poland,#FF0000,W
3+
2,Berlin,52.5200 13.4050 0 0,Capital city of Germany,,
4+
3,Paris,48.8566 2.3522 0 0,Capital city of France,#FFFFFF,P
5+
4,Kyiv,50.4501 30.5234 0 0,Capital city of Ukraine,#7d3f00,🙂
6+
5,Prague,50.0755 14.4378 0 0,Capital city of the Czech Republic,#00ff00,

‎source/_static/files/select_from_map_xls/cities2.geojson‎

Lines changed: 87 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,87 @@
1+
{
2+
"type": "FeatureCollection",
3+
"features": [
4+
{
5+
"type": "Feature",
6+
"properties": {
7+
"title": "Warsaw",
8+
"info": "Capital city of Poland",
9+
"id": "1",
10+
"marker-color": "#FF0000",
11+
"marker-symbol": "W"
12+
},
13+
"geometry": {
14+
"type": "Point",
15+
"coordinates": [
16+
21.0122,
17+
52.2297
18+
]
19+
}
20+
},
21+
{
22+
"type": "Feature",
23+
"properties": {
24+
"title": "Berlin",
25+
"info": "Capital city of Germany",
26+
"id": "2"
27+
},
28+
"geometry": {
29+
"type": "Point",
30+
"coordinates": [
31+
13.4050,
32+
52.5200
33+
]
34+
}
35+
},
36+
{
37+
"type": "Feature",
38+
"properties": {
39+
"title": "Paris",
40+
"info": "Capital city of France",
41+
"id": "3",
42+
"marker-color": "#FFFFFF",
43+
"marker-symbol": "P"
44+
},
45+
"geometry": {
46+
"type": "Point",
47+
"coordinates": [
48+
2.3522,
49+
48.8566
50+
]
51+
}
52+
},
53+
{
54+
"type": "Feature",
55+
"properties": {
56+
"title": "Kyiv",
57+
"info": "Capital city of Ukraine",
58+
"id": "4",
59+
"marker-color": "#7d3f00",
60+
"marker-symbol": "🙂"
61+
},
62+
"geometry": {
63+
"type": "Point",
64+
"coordinates": [
65+
30.5234,
66+
50.4501
67+
]
68+
}
69+
},
70+
{
71+
"type": "Feature",
72+
"properties": {
73+
"title": "Prague",
74+
"info": "Capital city of the Czech Republic",
75+
"id": "5",
76+
"marker-color": "#00ff00"
77+
},
78+
"geometry": {
79+
"type": "Point",
80+
"coordinates": [
81+
14.4378,
82+
50.0755
83+
]
84+
}
85+
}
86+
]
87+
}

‎source/_static/files/select_from_map_xls/cities3.xml‎

Lines changed: 39 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,39 @@
1+
<root>
2+
<item>
3+
<name>1</name>
4+
<label>Warsaw</label>
5+
<geometry>52.2297 21.0122 0 0</geometry>
6+
<info>Capital city of Poland</info>
7+
<marker-color>#FF0000</marker-color>
8+
<marker-symbol>W</marker-symbol>
9+
</item>
10+
<item>
11+
<name>2</name>
12+
<label>Berlin</label>
13+
<geometry>52.5200 13.4050 0 0</geometry>
14+
<info>Capital city of Germany</info>
15+
</item>
16+
<item>
17+
<name>3</name>
18+
<label>Paris</label>
19+
<geometry>48.8566 2.3522 0 0</geometry>
20+
<info>Capital city of France</info>
21+
<marker-color>#FFFFFF</marker-color>
22+
<marker-symbol>P</marker-symbol>
23+
</item>
24+
<item>
25+
<name>4</name>
26+
<label>Kyiv</label>
27+
<geometry>50.4501 30.5234 0 0</geometry>
28+
<info>Capital city of Ukraine</info>
29+
<marker-color>#7d3f00</marker-color>
30+
<marker-symbol>🙂</marker-symbol>
31+
</item>
32+
<item>
33+
<name>5</name>
34+
<label>Prague</label>
35+
<geometry>50.0755 14.4378 0 0</geometry>
36+
<info>Capital city of the Czech Republic</info>
37+
<marker-color>#00ff00</marker-color>
38+
</item>
39+
</root>

‎source/appearances_xls.md‎

Lines changed: 134 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,134 @@
1+
# Question appearances in XLSForm
2+
**Last updated:** <a href="https://github.com/kobotoolbox/docs/blob/2afa3a0c670fe98b296a79b798f33abf248d0273/source/appearances_xls.md" class="reference">Oct 31, 2025</a>
3+
4+
Question appearances allow you to customize how questions are displayed in the form and the type of responses they collect. This article explains how to add question appearances in XLSForm and lists common appearances by question type.
5+
6+
It is important to note that some appearances only work in [Enketo web forms](https://support.kobotoolbox.org/enketo.html), while others are supported only in [KoboCollect](https://support.kobotoolbox.org/kobocollect_on_android_latest.html). Consider your data collection method when selecting appearances.
7+
8+
<p class="note">
9+
<b>Note:</b> This article focuses on setting question appearances in <a href="https://support.kobotoolbox.org/getting_started_xlsform.html">XLSForm</a>. To learn about setting appearances in the KoboToolbox Formbuilder, see <a href="https://support.kobotoolbox.org/using-formbuilder.html">Using the Formbuilder</a> documentation.
10+
<br><br>
11+
For hands-on practice with question appearances in XLSForm, see KoboToolbox Academy's <a href="https://academy.kobotoolbox.org/courses/xlsform-fundamentals">XLSForm Fundamentals Course</a>.
12+
</p>
13+
14+
## Adding question appearances
15+
16+
To add question appearances in XLSForm:
17+
1. In the `survey` worksheet, add an **appearance** column.
18+
2. Enter the name of the appearance in the `appearance` column. Ensure you use the exact spelling and punctuation of the appearance name.
19+
3. Some appearances can be combined and applied to the same question. Combine appearances by entering them in the same cell and separating them with a space.
20+
21+
**survey worksheet**
22+
23+
| type | name | label | appearance |
24+
| :--- | :--- | :--- | :--- |
25+
| text | description | Describe the project. | multiline |
26+
| select_one country_list | country | Which country is this project taking place in? | autocomplete minimal |
27+
| survey |
28+
29+
30+
## Available question appearances in XLSForm
31+
The tables below list common question appearances by question type and shows which are supported in Enketo web forms and KoboCollect.
32+
33+
### Select question types
34+
Select questions allow respondents to [choose from predefined options](https://support.kobotoolbox.org/question_types_xls.html#select-question-types).
35+
36+
| Appearance | Description | Compatibility |
37+
| :--- | :--- | :--- |
38+
| `minimal` | Displays choices in a drop-down menu. | Enketo and KoboCollect |
39+
| `compact` | Displays choices side-by-side with minimal padding and without choice boxes. | Enketo and KoboCollect |
40+
| `label` | Displays choice labels without the choice boxes. | Enketo and KoboCollect |
41+
| `list-nolabel` | Displays the answer choice boxes without the labels. | Enketo and KoboCollect |
42+
| `autocomplete` | Adds a search bar at the top of the option list. | Enketo and KoboCollect (combine with minimal appearance) |
43+
| `horizontal` | Displays the answer choices horizontally in columns. | Enketo only |
44+
| `horizontal-compact` | Displays the answer choices horizontally, with minimal padding and without choice boxes. | Enketo only |
45+
| `likert` | Displays answer choices as a Likert scale (`select_one` only). | Enketo and KoboCollect |
46+
| `quick` | Auto-advances the form to the next question after an answer is selected (`select_one` only). | KoboCollect only |
47+
| `quickcompact` | Displays choices side-by-side with minimal padding and without choice boxes, and auto-advances to the next question after an answer is selected (`select_one` only). | KoboCollect only |
48+
| `columns` | Displays available choices in 2, 3, 4 or 5 columns depending on screen size. | Enketo and KoboCollect |
49+
| `columns-pack` | Displays available choices with as many as possible on one line. | Enketo and KoboCollect |
50+
| `columns-n` | Displays available choices in the specified number (n) of columns. | Enketo and KoboCollect |
51+
| `map` | Displays a map to select options from. Requires <a href="https://support.kobotoolbox.org/select_from_map_xls.html">defining GPS coordinates</a> in the `choices` sheet (`select_one` only). | KoboCollect only |
52+
| `quick map` | Displays a map to select options from, automatically recording the first selected location without displaying additional information. Requires <a href="https://support.kobotoolbox.org/select_from_map_xls.html">defining GPS coordinates</a> in the `choices` sheet (`select_one` only). | KoboCollect only |
53+
54+
<p class="note">
55+
<b>Note:</b> Appearances for <code>select_one</code> and <code>select_multiple</code> questions can also be used for <a href="https://support.kobotoolbox.org/select_from_file_xls.html">select from file</a> questions.
56+
</p>
57+
58+
### Integer and decimal question types
59+
Numeric questions are used to [collect whole numbers or decimal numbers](https://support.kobotoolbox.org/question_types_xls.html#numeric-question-types).
60+
61+
| Appearance | Description | Compatibility |
62+
| :--- | :--- | :--- |
63+
| `thousands-sep` | Formats large numbers using a comma separator for thousands. | Enketo and KoboCollect |
64+
| `bearing` | Records a compass reading in degrees (`decimal` only). | KoboCollect only |
65+
| `counter` | Displays buttons for increasing and decreasing digits (`integer` only). | KoboCollect only |
66+
67+
68+
### Range question type
69+
Range questions are used to [select values within a specified range](https://support.kobotoolbox.org/question_types_xls.html#numeric-question-types).
70+
71+
| Appearance | Description | Compatibility |
72+
| :--- | :--- | :--- |
73+
| `vertical` | Changes the orientation of the number line to a vertical line. | Enketo and KoboCollect |
74+
| `picker` | In KoboCollect, displays a pop-up spinner for selecting values. In Enketo, displays a drop-down menu. | Enketo and KoboCollect |
75+
| `rating` | Displays stars instead of a number line. | Enketo and KoboCollect |
76+
| `distress` | Displays a thermometer instead of a number line. | Enketo and KoboCollect |
77+
78+
79+
### Text question type
80+
Text questions allow users to [collect open-ended responses](https://support.kobotoolbox.org/question_types_xls.html#text-and-note-question-types).
81+
82+
| Appearance | Description | Compatibility |
83+
| :--- | :--- | :--- |
84+
| `numbers` | Displays a numeric keyboard instead of a text keyboard (e.g., to collect phone numbers). | KoboCollect only |
85+
| `multiline` | Displays a multiline text box for longer text responses. | Enketo and KoboCollect |
86+
| `url` | Displays a clickable URL under the question text and makes the question read-only. Requires entering a URL in the question's `default` column. Also works with `note` questions. | Enketo and KoboCollect |
87+
| `masked` | Masks text entered by the respondent (e.g., a password or confidential information). | KoboCollect only |
88+
89+
90+
### Date question type
91+
Date questions are used to [capture specific calendar dates](https://support.kobotoolbox.org/question_types_xls.html#date-and-time-question-types).
92+
93+
| Appearance | Description | Compatibility |
94+
| :--- | :--- | :--- |
95+
| `month-year` | Captures a month and a year. | Enketo and KoboCollect |
96+
| `year` | Captures only a year. | Enketo and KoboCollect |
97+
| `no-calendar` | Displays a spinner to select the day, month, and year, instead of the default calendar-style picker. | KoboCollect only |
98+
| `coptic` | Displays the Coptic calendar. | KoboCollect only |
99+
| `ethiopian` | Displays the Ethiopian calendar. | KoboCollect only |
100+
| `islamic` | Displays the Islamic calendar. | KoboCollect only |
101+
| `bikram-sambat` | Displays the Bikram Sambat calendar. | KoboCollect only |
102+
| `myanmar` | Displays the Myanmar calendar. | KoboCollect only |
103+
| `persian` | Displays the Persian calendar. | KoboCollect only |
104+
| `buddhist` | Displays the Buddhist calendar. | KoboCollect only |
105+
106+
107+
### GPS question types
108+
GPS questions are used to [capture the geographic coordinates](https://support.kobotoolbox.org/question_types_xls.html#gps-question-types) of a location, path, or area directly within your forms.
109+
110+
| Appearance | Description | Compatibility |
111+
| :--- | :--- | :--- |
112+
| `maps` | Displays a map for users to visualize the location that is being automatically recorded (`geopoint` only). | KoboCollect only (included in default Enketo appearance) |
113+
| `placement-map` | Allows for manual selection of a location on a map (`geopoint` only). | KoboCollect only (included in default Enketo appearance) |
114+
| `hide-input` | Shows a larger map and hides other input fields (latitude, longitude, altitude, accuracy). | Enketo only |
115+
116+
117+
### Image questions
118+
Image questions allow users to [upload or record images](https://support.kobotoolbox.org/question_types_xls.html#media-question-types) directly into their forms.
119+
120+
| Appearance | Description | Compatibility |
121+
| :--- | :--- | :--- |
122+
| `signature` | Allows users to draw their signature. | Enketo and KoboCollect |
123+
| `draw` | Allows users to sketch or create drawings. | Enketo and KoboCollect |
124+
| `annotate` | Allows users to annotate an image by drawing or writing on it. | Enketo and KoboCollect |
125+
| `new` | Prompts users to take a new picture using the device camera (no file upload). | KoboCollect only |
126+
| `new-front` | Prompts users to take a new picture using the device's front-facing camera. | KoboCollect only |
127+
128+
129+
### Barcode questions
130+
Barcode questions allow users to [scan a QR code](https://support.kobotoolbox.org/question_types_xls.html#media-question-types) using the device's camera in KoboCollect.
131+
132+
| Appearance | Description | Compatibility |
133+
| :--- | :--- | :--- |
134+
| `hidden-answer` | Hides the scanned barcode value. | KoboCollect only |

0 commit comments

Comments
 (0)