Question Types¶
text¶
Use for questions that require a text response. It can also be used with the numbers appearance to get integer responses that are longer than the 9 character limit of the integer type.
- Type
- text
Parameters:
- rows: Set the number of rows of text shown in the form
Appearances:
- numbers: Shows the numeric keyboard
- thousands-sep: Inserts a separator between thousands when “numbers” is also used
- url: Allows the user to open a URL. Specify the url in the default column
- hidden: Hide the widget in fieldTask
Availability:
- FieldTask: yes
- Webforms: yes
Example
type | name | label | parameters |
---|---|---|---|
text | comment | Any comments? | rows=5 |

Text widget in webforms with 5 rows
Note
There is a limit of 4,000 characters on the amount of text that can be entered into a text question in webforms. However there is no corresponding limit in fieldTask.
note¶
- Type
- note
A read only note to the user.
Notes can be used to provide guidance to the user. This could some simple text that is specified in the survey template. For example:
The following questions are about health
However they can also be dynamically constructed to provide context sensitive help. To do this use the ${question_name} syntax within the label of the note. The question referred to can be a calculate that creates the text by combining answers from multiple questions.
type | name | label | calculation |
---|---|---|---|
text | name | What is your name? | |
calculate | calculate_guidance | concat(‘Tell ‘, ${name}, ‘ that they are doing well’) | |
note | guidance | ${calculate_guidance} |
integer¶
Number questions that don’t allow a decimal point and are not longer than 9 digits.
- Type
- integer
Appearances:
- thousands-sep: Inserts a separator between thousands
- hidden: Hide the widget in fieldTask
Availability:
- FieldTask: yes
- Webforms: yes
Example
type | name | label |
---|---|---|
integer | age | What is your age? |
decimal¶
Number question with a decimal point. Decimal questions are limited to 14 digits plus the decimal point. You can use a text question with the numbers appearance if you need more.
- Type
- decimal
Appearances:
- thousands-sep: (Optional) Inserts a separator between thousands
Availability:
- FieldTask: yes
- Webforms: yes
Example
type | name | label |
---|---|---|
decimal | cost | How much did it cost? |
bearing¶
A bearing widget captures the compass reading and stores it as a decimal type.
- Type
- decimal
Required Appearance:
- bearing
Availability:
- FieldTask: yes
- Webforms: no
Example
type | name | label | appearance |
---|---|---|---|
decimal | orientation | Record the orientation | bearing |
barcode¶
- Type
- barcode
Appearances:
- front: (Optional) Use the front facing camera
Reads a barcode using the camera.
The following barcode formats are supported:
- UPC-A
- UPC-E
- EAN-8
- EAN-13
- Code 39
- Code 93
- Code 128
- Codabar
- ITF
- RSS-14
- RSS-Expanded
- QR Code
- Data Matrix
- Aztec (beta)
- PDF 417 (beta)
- MaxiCode
The flash can be used as a light source when scanning barcodes in a poorly lit environment.
type | name | label |
---|---|---|
barcode | product | Scan the products barcode |
nfc¶
- Type
- barcode
Required Appearances: nfc
Reads the id on an NFC chip
type | name | label | appearance |
---|---|---|---|
barcode | product | Scan the products NFC chip | nfc |
date, time and datetime¶
default date type¶
- Type
- date
- Availability:
- FieldTask: yes Webforms: yes
Example
type | name | label |
---|---|---|
date | birthdate | When were you born? |
date widget with spinner input¶
A more compact date widget that makes it easy to select dates that are far from the current (or default) date.
- Type
- date
- Appearance:
- no-calendar
type | name | label | appearance |
---|---|---|---|
date | birthdate | When were you born? | no-calendar |
month and year only¶
Only records the month and the year.
- Type
- date
- Appearance:
- month-year
type | name | label | appearance |
---|---|---|---|
date | birth_month | What month were you born? | month-year |
year only¶
Only records the year.
- Type
- date
- Appearance:
- year
type | name | label | appearance |
---|---|---|---|
date | birth_year | What year were you born? | year |
date widgets with non-Gregorian calendars¶
Note
The non-Gregorian calendar is used only on input. The dates are then converted and stored as standard Gregorian dates
Availability:
- FieldTask: yes
- Webforms: no
time¶
Records the time of day.
Note
The time is stored along with the time zone. Hence a point in time is recorded. If you record a time of 10:00 am in London then the value is the same as 8pm in Sydney. If someone in Sydney generates a report using their local timezone then they will see the result as 8pm.
If you want to record a local time then you can use an integer type or decimal type or a select_one type that has a list of valid times. A question like “What time did the parcel arrive?” could be recorded with or without timezone depending on how you want to analyse the data.
- Type
- time
type | name | label |
---|---|---|
time | arrived | What time did the parcel arrive? |
select¶
single select¶
- Type
- select_one
Appearance:
- minimal: Shows a modal dropdown that expands when selected by the user. Useful when showing multiple questions on one page.
- autoadvance: Immediately go to the next page after a choice is selected. Only use this appearance if it is immediately obvious to the user that the correct selection was made
- autocomplete: Adds a text box above the choices. If you type into this text box the choices are filtered. Use with large lists.
- likert: Show the choices in a likert scale
- compact: shows the choices in a compact grid. This is particularly useful when you have only images for the choices rather than text labels.
- compact-{x}: As per compact however replace {x} with the number of columns that you want.
- quickcompact: Combines compact and auto advance
- quickcompact-{x}: Combines compact with columns and auto advance
Parameters:
- randomize=true (Will randomly sort the choices each time the question is shown)
- seed={an integer} (Use this with random so that the same initially random order will be shown each time the question is shown in a given form)
type | name | label |
---|---|---|
select_one countries | country | Select a country |
list_name | name | label |
---|---|---|
countries | mali | Mali |
countries | png | Papua New Guinea |
countries | australia | Australia |
countries | vanuatu | Vanuatu |
multi select¶
Allows the user to select multiple answers from a choice list.
- Type
- select
Appearance:
- minimal: Shows a modal dropdown that expands when selected by the user. Useful when showing multiple questions on one page.
- autocomplete: Adds a text box above the choices. If you type into this text box the choices are filtered. Use with large lists.
- compact: shows the choices in a compact grid. This is particularly useful when you have only images for the choices rather than text labels.
- compact-{x}: As per compact however replace {x} with the number of columns that you want.
Parameters:
- randomize=true (Will randomly sort the choices each time the question is shown)
- seed={an integer} (Use this with random so that the same initially random order will be shown each time the question is shown in a given form)
type | name | label |
---|---|---|
select countries | country | Select some countries |
list_name | name | label |
---|---|---|
countries | mali | Mali |
countries | png | Papua New Guinea |
countries | australia | Australia |
countries | vanuatu | Vanuatu |
rank¶
This widget allows you to rank choices in order.
- Type
- rank
Parameters:
- randomize=true (Will randomly sort the choices each time the question is shown)
- seed={an integer} (Use this with random so that the same initially random order will be shown each time the question is shown in a given form)
type | name | label |
---|---|---|
rank importance | importance | Rank the issues in order of importance |
list_name | name | label |
---|---|---|
importance | food | Food |
importance | shelter | Shelter |
importance | water | Water |
importance | security | Security |
Viewing Recorded Rankings¶
When results are exported in the default spreadsheet format they will be shown in multiple columns. One for each choice. The column headings will be take from the question name with the addition of “1”, “2”, “3” etc. The first column will contain the choice that was ranked first and so on.
In other view of the collected data, such as in the console, the rankings will be shown in compressed format where they are all placed in a single column, in rank order, with a space between each value.
image¶
Taking a Picture¶
- Type
- image
Captures an image either using the camera or by selecting from the device gallery.
type | name | label |
---|---|---|
image | picture_of_tree | Take a picture of the tree |
image with annotation¶
Draw on an image after it has been captured. An additional button labelled “Markup Image” is shown that is enabled after the image is captured.
- Type
- image
- Appearance:
- annotate
type | name | label |
---|---|---|
image | damage | Take a photo and circle the damage |
image as a drawing¶
- Type
- image
- Appearance:
- draw
This is similar to annotate except the user draws on a blank canvas.
type | name | label | appearance |
---|---|---|---|
image | draw_farm_layout | Draw a plan of the farm |
image as a signature¶
- Type
- image
- Appearance:
- signature
Allows the user to draw a signature of their name.
type | name | label | appearance |
---|---|---|---|
image | hh_signature | Ask houeholder to sign the screen | signature |
Other Image appearances and parameters¶
Require a new image¶
The default behavour is to include a button that allows the user to select an existing image rather than taking a new one. However by adding the appearance “new” the user is requried to capture a new image.
Self portrait (selfie) image¶
The back camera on the phone is used by default (although the user can change this). However by setting the appearance “new-front” the front camera is used by default to capture a selfie.
Note
selfie can also be used as the appearance.
Reducing the size of images¶
The size can be reduced by specifying the maximum length of the longest side of the image using max-pixels. For example if the default picture size is 1,000 by 500 and you specify the max-pixels to be 200, then the image will be resized to 200 by 100 pixels.
In the parameters column add max-pixels=
followed by the maximum length of the long edge in pixels.
Note
The proportions of the image are maintained and if the length of the longest side was less than max-pixels the image will not be changed.
Acknowledge / Trigger¶
- Type
- trigger or acknowledge
You can use a type of either trigger or acknowlwdge, they work the same way. A single checkbox is shwown which the user can “acknowledge” by checking it. If they do this then the answer stored for the question is “OK”.
You can use the above answer in relevance for following questions. For example:
${ack} = 'OK'
Commonly select_one questions with yes/no choices are used instead of Acknowledge
type | name | label | relevance |
---|---|---|---|
acknowledge | ack | Select to confirm participation | |
text | name | What is your name? | ${ack} = ‘OK’ |
In WebForms a radio button is used instead of a checkbox.

Acknowledge widget in WebForms
Printer widget¶
- Type
- text
- Required appearance
- printer:org.opendatakit.sensors.ZebraPrinter
Connects to an external label printer, and prints labels that can contain a barcode, a QR code, or text.
type | name | label | appearance | calculation |
---|---|---|---|---|
text | printer_widget | Printer widget | printer:org.opendatakit.sensors.ZebraPrinter | concat(‘123456789’,’<br>’,’QR CODE’,’<br>’,’Text’) |
range¶
These widgets allow the user to select a numeric value within a range of numbers shown on a line.
- Type
- range
Parameters
start: The starting number end: The last number step: The increment between numbers
Range widget with integers¶
If all three parameter values are integers then input will also be stored as an integer.
type | name | label | parameters | |
---|---|---|---|---|
range | eggs | number_of_eggs | How many eggs are there? | start=0;end=48;step=12 |
Range widget with decimals¶
If one or more of the 3 parameters (start, end, step) are decimal then the answer will also be recorded as a decimal value.
Vertical range widget¶
- Appearance
- vertical
Range widget with picker¶
- Appearance
- picker
Availability:
- FieldTask: yes
- Webforms: no
When picker is added as an appearance the answer can be selected from a spinner rather than by clicking at a point on a line.
Range widget with rating¶
- Appearance
- rating
When rating is specified as the appearance then the range is shown as stars which the user can select. The number of stars is equal to the value of the end parameter. The start and step parameters are ignored. Hence the value set is equal to the number of the start selected counting from the left.
type | name | label | appearance | parameters |
---|---|---|---|---|
range | rating | Rate your experience | rating | end=5 |
Chart¶
- Type
- chart
Shows a chart in the survey. Chart settings are specified in the question parameters. More details are available in Charts
Availability:
- FieldTask: yes
- Webforms: no
Child Form / Parent Form¶
- Type
- child_form, parent_form
Launches another survey from within the current survey. The difference between these is in how the data from the two surveys are linked in the results database. If you don’t care about linking the data between the two surveys then either type will do. Detailed information on using these question types is available in Launch a Survey from inside a Survey.
Availability:
- FieldTask: yes
- Webforms: no
Locations¶
Location widgets capture one or more points as latitude, longitude, altitude in meters, and accuracy radius in meters. These data items are space separated. For example the following reading represents a lattitude of -18.27, a longitude of 27.32, an altitude of 25 meters and an accuracy of 5.6 meters: -18.27 27.32 25 5.6
Multiple points that form lines or shapes are separated by semicolons.
Availability:
- FieldTask: yes
- Webforms: yes
Multiple Locations in one Form¶
Prior to Smap server version 20.10 you could only put one location widget in each form of a survey. The reasoning behind this was that in GIS shape files the same restriction applies where each shape file consists of a single location and all the attributes associated with that location. Also the name of each location question was automatically set to “the_geom”. I’m afraid to say this was just done to make the coding easier!
In version 20.10 this restriction has been lifted:
- You can add multiple location questions in any form as well as the location preload in the top level form.
- Location questions keep the name that you give them.
- When you export a survey as a shape file you can select the location to use. All other questions are assumed to be attributes of that location.
- When viewing a map of a survey on the analysis page you can select the question to use as the location.
- When creating a task from existing data the location of the task is determined automatically. Firstly it tries to get the first geopoint question in the source survey. If that does not exist it tries to use the location preload that might have been collected automatically. If that is not set then it will use the first geotrace or geoshape question that it finds.
- The map in the console currently uses the first location it finds in the survey. This will be fixed in a later release.
Warning
You may have an existing survey that you created using a spreadsheet and perhaps you have a geopoint question in that survey which you called “pump_location”. Once your server is updated to 20.10 and you use the “replace” button to update the existing survey then a new column will be created in the database called “pump_location” to hold that location data. However any previously collected data will be stored in a column called “the_geom” and will no longer be accessible. You will see a warning in red if this happens when you do the replace.
In this circumstance, if you still need to access the old location data, then edit your survey in excel and change the name of the geopoint to “the_geom” Then replace the survey on you can redo the replace action.
geopoint¶
records a single point
- Type
- geopoint
type | name | label |
---|---|---|
geopoint | the_geom | Record Location |
Geopoint with a background map¶
- Type
- geopoint
- Appearance
- maps
Geopoint with a user selected location¶
- Type
- geopoint
- Appearance
- placement-map
Matrix¶
The begin matrix type is a convenient way to show questions in a matrix structure using webforms.

Matrix Widget
To create the matrix, group the questions that will appear horizontally, however instead of using begin group/end group use begin matrix/end matrix. Because these questions are appearing horizontally there will be a limit to how many you can fit on the screen comfortably.
Then specify the rows of the matrix in a choice list in the choices worksheet. Put the name of the choice list used by the matrix in the “list name” column of the survey worsheet. As these choices create the rows of the matrix you can add as many as you like and the matrix will simply extend down the page.
Finally in the settings sheet, under “style” add “theme-grid”.
When you load the survey onto the server additional questions will be created in groups. One group for each of the choices and a group for the header. Hence the matrix type is not a real type as it is converted into multiple other questions on upload.
- Type
- begin matrix, end matrix
Example
type | name | label | list name |
---|---|---|---|
begin matrix | nutrition | items | food_groups |
select_one yn | available | Available | |
integer | quantity | Quantity | |
text | comment | Comment | |
end matrix |
list_name | name | label |
---|---|---|
food_groups | vegetables | Vegetables |
food_groups | protein | Protein |
food_groups | fruit | Fruit |
food_groups | dairy | Dairy |
food_groups | sugar | Fats and sugar |
yn | yes | yes |
yn | no | no |
Availability:
- FieldTask: no
- Webforms: yes
- XLSForm: yes
- Online Editor: no
Literacy Test¶
- Type
- select
Appearance:
- literacy
body::kb:flash
- Set to the interval between the Start button being pressed and the screen flashing to indicate that reading progress (word reached) should be recorded.
Availability:
- FieldTask: no
- Webforms: yes
- XLSForm: yes
- Online Editor: no
- When the widget is first shown it appears with a list of the words to be read and a Start button. It is assumed that the interviewee has a list of the words to be read as well and the enumerator will be recording their reading performance in webForms.
- After the enumerator presses the Start button, the timer is started. This will cause the screen to flash after the specified number of seconds or 60 seconds if no number is specified in body::kb:flash. During this period the enumerator can select words that the reader finds difficult.
- After the screen flashes the enumerator will be able to select the word that the reader had reached. They can then continue to select words that the reader is having trouble with.
- After starting a Finish button is shown. When the enumerator presses Finish the timer stops. They can then record the final word read.
Viewing Literacy Results¶
When you view the output in the console it appears in its raw format. That is a number of values spearated by spaces including:
- The index of the word being read when the screen flashed
- The time in seconds elapsed before the Finish button is pressed
- The index of the word being read when the Finish button was pressed
- The text “null null null null null null null”
- A space separated list of the words that were marked as being wrong or difficult for the reader.
Support for literacy widgets has been added to the default Excel export from the analysis page. This formats the output to make it easier to analyse. Four additional columns are automatically added to the export for each literacy widget. These record:
- The total time elapsed between pressing Start and Finish
- The index of the word being read when the screen flashed
- The index of the word being read when the finish button was pressed
- The count of words that were marked as being difficult or in error
The recording of which words the reader had trouble with then behaves like any other select question. If you specify “Compress select multiples” for the export then they will be shown as a comma separated list of choice values. Otherwise a column in the export will be added for each word choice and the value will be set to “1” if the word was a problem or “0” if it was not. This allows you to easily add up the number of times each word was marked as a problem.