Question Types

ODK Collect supports forms with a wide variety of question types. The exact functionality and display style of each question are specified in your XLSForm definition using the type and appearance columns.

Helpful terminology

question
A prompt to the user, usually requesting a response. Questions are written as a single line in an XLSForm, and usually appear on a single screen in Collect.
widget
A rendered question screen in Collect. The type and appearance of a question determine the widget that is displayed.

Note

This document covers the full range of question types and options available when creating forms using XLSForm.

For simpler forms you can use ODK Build, which provides a visual, drag-and-drop interface.

Text widgets

All of the text widgets share the text type, and the inputs from them are saved as literal strings.

Warning

If you are using Aggregate and expect answers to be more than 255 characters, you should increase the database field length to over 255 characters.

Default text widget

type
text
appearance
none

A simple text input.

The text entry field expands as the user types, and line breaks can be included. The keyboard displayed depends on the Android device and user settings.

Text form widget, displayed in ODK Collect on an Android phone. The label is "What is your name?"

XLSForm

survey
type name label appearance
text name What is your name?  

Number text widget

type
text
appearance
numbers

A numerical input that treats the input as a string, rather than a number.

The number input accepts numerals (0123456789), hyphens (-), and decimal points (.). These are the only characters available on the number keypad displayed with this widget.

This is useful for phone numbers, ID numbers, IP addresses, and similar data. It can also be used in place of the Integer widget or Decimal widget if large numbers are needed. (The integer widget has a limit of nine digits, and the decimal widget has a limit of 15 characters.)

The text widget, with numerical entry, as displayed in the ODK Collect app on an Android phone. The question text is "String number widget." The hint text is, "text type with numbers appearance." Below that is a simple input. Above the question text is the form group name "Text Widget." The Android onscreen keyboard displays a number pad.

XLSForm

survey
type name label appearance hint
text string_number_widget String number widget numbers text type with numbers appearance

Note

This appearance can be combined with the thousands-sep appearance.

External app widget

type
text
appearance
ex.*

Launches an external app and receives a string input back from the external app. If the specified external app is not available, a manual input is prompted.

The external app widget is displayed when the appearance attribute begins with ex:. The rest of the appearance string specifies the application to launch.

The External App form widget, as displayed in the ODK Collect App on an Android phone. The question text is "Ex string widget." The hint text is, "text type with ex:change.uw.android.BREATHCOUNT appearance (can use other external apps)." Below that is a button labeled "Launch." Above the question text is the form group name "Text widgets." The External App widget as displayed earlier. The Launch button has now been disabled. Below it is a simple input. A help message displays the text, "The requested application is missing. Please manually enter the reading."

XLSForm

survey
type name label appearance hint
text ex_string_widget Ex string widget ex:change.uw.android.BREATHCOUNT text type with ex:change.uw.android.BREATHCOUNT appearance (can use other external apps)

Number widgets

Number widgets collect and store number inputs — either integers or floating-point decimals.

Number values can also be captured by the Range widgets.

Integer widget

type
integer
appearance
none

A whole number entry input.

Integer widgets will not accept decimal points, and the entry field has a limit of nine digits. If you need numbers larger than nine digits, see the Number text widget.

The integer widget supports:

An integer form widget displayed in ODK Collect on an Android phone. The question is "What is your age in years?" A numerical keyboard is displayed.

XLSForm

survey
type name label
integer age What is your age in years?

Decimal widget

type
decimal
appearance
none

A numeric input that will accept decimal points.

Decimal number entry is capped at 15 characters (14 digits and a decimal point). If you need numbers larger than 15 digits, see the Number text widget.

The decimal widget supports:

An integer form widget displayed in ODK Collect on an Android phone. The question is "Weight in kilograms." A numerical keyboard is displayed.

XLSForm

survey
type name label
decimal weight Weight in kilograms.

Number widget appearance options

Thousands separator

type
integer, decimal, (text)
appearance
thousands-sep, (numbers)

If thousands-sep is added to appearance, integer, decimal, and number text widgets will display their values using locale-specific thousands separators.

Note

For locales that use the point separator (.), a space is used instead.

An integer widget as displayed in the Collect app. The question text is "Integer widget with thousands separators". The answer value is "1,000,000". The number keyboard is active.

The comma separator, used in English/U.S. (and others).

The same image as previously, but the answer value is "1 000 000". (That is, it uses spaces instead of commas as thousand separators.

The space separator, used in Français/France (and others).

Number from an external app

type
integer, decimal
appearance
ex:*

By specifying an external app in the appearance, your form can launches an external app and receive a number (integer or decimal) from the external app as input. If the specified external app is not available, a manual input is prompted.

The External Integer form widget, as displayed in the ODK Collect app on an Android phone. The question text is, "Ex integer widget." The hint text is, "integer type with ex:change.uw.android.BREATHCOUNT appearance (can use other external apps)." Below that is a button labeled "Launch." Above the question text is the form name "Numerical widgets." The External Integer widget as displayed previously. The Launch button is now disabled and below it is a simple input. A help text reads, "The requested application is missing. Please manually enter the reading."

XLSForm

survey
type name label appearance hint
integer ex_integer_widget Ex integer widget ex:change.uw.android.BREATHCOUNT integer type with ex:change.uw.android.BREATHCOUNT appearance (can use other external apps)

Date and time widgets

Default date widget

type
date
appearance
none
The default Date form widget, as displayed in the ODK Collect app on an Android phone. The question text is, "Date widget." The hint text is "date type with no appearance." Below that is a button labeled "Select date." Below that is the text, "No date selected." Above the question text is the form group name "Date and time widgets." The date widget shown in the previous image, with a modal popup showing a monthly calendar. A date is selected. At the bottom of the modal are Cancel and OK buttons. The date widget shown previously. Below the button is a date: Aug 11, 2017.

XLSForm

survey
type name label hint
date date_widget Date widget date type with no appearance

Date widget with spinner input

type
date
appearance
no-calendar

The no-calendar appearance displays a spinner-style date selection. This is especially appropriate for selecting dates more than one year in the past or future.

The no-calendar Date form widget, as displayed in the ODK Collect app on an Android phone. The question text is, "Date Widget." The hint text is "date type with no-calendar appearance." Below that is a button labeled "Select date." Below the button is the text, "No date selected." Above the question text is the form group name "Date and time widgets." The date widget shown previously, with a pop modal. The headline of the modal is "Select date." There are individual "spinner" style selectors for month, day, and year. At the bottom of the modal are OK and Cancel buttons.

XLSForm

survey
type name label appearance hint
date date_widget_nocalendar Date Widget no-calendar date type with no-calendar appearance

Month and year only

type
date
appearance
month-year

Collects only a month and year.

The date widget, with a modal popup labeled "Select date." There are individual "Spinner" type selectors for month and year, but not for date. At the bottom are Cancel and OK buttons.

XLSForm

survey
type name label appearance hint
date date_widget_month_year Date widget month-year date type with month-year appearance

Year only

Collects only a year.

The Year form widget, with a model popup labeled "Select date." There is a single "spinner" type selector for year. At the bottom are Cancel and OK buttons.

XLSForm

survey
type name label appearance hint
date date_widget_year Date widget year date type with year appearance

Date widgets with non-Gregorian calendars

Collect supports several non-Gregorian calendars.

Note

The non-Gregorian calendar is used only on input. The dates are converted and stored as standard Gregorian dates

Coptic calendar

type
date
appearance
coptic

Ethiopian calendar

type
date
appearance
ethiopian

Islamic calendar

type
date
appearance
islamic

Time widget

type
time
appearance
none

A time selector. Captures only a specific time-of-day, not a date and time. For date and time, see the Datetime widget.

The time widget does not accept any appearance attributes.

Note

The time widget stores the time along with a time zone. This can cause unexpected behavior around Daylight saving time.

For example, if you record a time before the clock change, and then view the time after the clock change, it will appear to be an hour off. This happens because the recorded time data is understood as a specific moment in time that is being "translated" into your current, local time zone.

A similar problem occurs when moving between geographic time zones.

This makes the time widget unsuitable for abstract time-of-day questions such as What time do you usually wake up? For questions like this, you may want to use a Select widget with modal menu. You can set the options at whatever level of accuracy you need — for example, 15 or 30 minute increments. Alternatively, you could use the select widget for hours, and an Integer widget for minutes.

The Time form widget as displayed in the ODK Collect App on an Android phone. The question text is "What time do you usually wake up?" The button label is "Select time." Below the button is the message "No time selected." The Time widget as displayed previously, with a modal popup. The modal headline is "Select time." The body of the modal contains scrollers for Hour, Minute, and AM/PM. At the bottom of the modal are Cancel and OK buttons. The Time form widget as displayed previously. Below the "Select time" button is "06:30".

XLSForm

survey
type name label
time wakeup What time do you usually wakeup?

Datetime widget

A date and time selector.

For date only, see Default date widget. For time only, see Time widget.

The Datetime form widget as displayed in the ODK Collect App on an Android phone. The question text is "When was the last time you ate?" Below the question are two buttons. The first button is labeled "Select date" and below it is the message "No date selected." The second button is labeled "Select time" and below it is the message "No time select." The same form widget screen as previously, overlaid with a modal popup calendar. The headline is a date: 2017 Tue, Aug 8. The main body shows a monthly calendar with selectable days and arrows for scrolling month-to-month. In the bottom-right are Cancel and OK buttons. The Datetime form widget as displayed previously. The question text is "When was the last time you ate?" Below the question are two buttons. The first button is labeled "Select date" and below it is the date "Aug 08, 2017" The second button is labeled "Select time" and below it is the message "No time select." The Datetime widget as displayed previously, with a modal popup. The modal headline is "Select time." The body of the modal contains scrollers for Hour, Minute, and AM/PM. At the bottom of the modal are Cancel and OK buttons. The Datetime form widget as displayed previously. The question text is "When was the last time you ate?" Below the question are two buttons. The first button is labeled "Select date" and below it is the date "Aug 08, 2017" The second button is labeled "Select time" and below it is the time "06:45"

XLSForm

survey
type name label
dateTime previous_meal When was the last time you ate?

Note

The Datetime widget supports the no-calendar spinner-style appearance.

Select widgets

Select widgets offer the participant options to pick from. You can offer the participant a single choice, or the ability to choose multiple answers. The order of the choices can be randomized for any of the select types described below.

The options for a select question are listed on a sheet named choices, in your XLSForm file. The choices sheet has at least three columns:

list_name
A set of choices for a single question share a common list_name. The value of list_name is included in the type column on the survey sheet.
name

The canonical identifier for a specific choice. This value is what is stored on the completed form. If you refer to a select response using a variable, the name string is returned.

As with the survey sheet, name must not include spaces.

label
The user-facing text displayed for the choice.

Select widgets can include images as choices.

Single select widget

type
select_one {list_name}
The default Single Select form widget, as displayed in the ODK Collect app on an Android phone. The question text is, "Select one widget." The hint text is "select_one type with no appearance, 4 text choices." Below that is a set of radio button selectors labeled A, B, C, and D. Above the question text is form group name "Select one widgets."

XLSForm

survey
type name label hint
select_one opt_abcd select_one_widget Select one widget select_one type with no appearance, 4 text choices
choices
list_name name label
opt_abcd a A
opt_abcd b B
opt_abcd c C
opt_abcd d D

Select widget with modal menu

type
select_one {list_name}
appearance
minimal

Adding the minimal appearance attribute places the choices into a modal overlay menu.

The Single Select form widget, with minimal appearance, as displayed in the ODK Collect app on an Android phone. The question text is "Spinner widget." The hint text is "select_one type with minimal appearance, 4 text choices." Below that is a drop-down style select menu with the prompt "Select One Answer." Above the question text is the form group name "Select one widgets." The Single Select form widget, with minimal appearance, as displayed in the previously image. The select menu has expanded to show choices: A, B, C, D, and Remove Response.

XLSForm

survey
type name label appearance hint
select_one opt_abcd spinner_widget Spinner widget minimal select_one type with minimal appearance, 4 text choices
choices
list_name name label
opt_abcd a A
opt_abcd b B
opt_abcd c C
opt_abcd d D

Note

In web rendered form views (such as Enketo form viewer) a select widget with minimal appearance will appear in a drop-down (select) menu.

Select widget with autoadvance

type
select_one {list_name}
appearance
autoadvance

When the autoadvance appearance is added, the form advances immediately to the next question once a selection is made.

XLSForm

survey
type name label appearance hint
select_one opt_abcd select_one_autoadvance_widget Select one autoadvance widget quick select_one type with quick appearance, 4 text choices
choices
list_name name label
opt_abcd a A
opt_abcd b B
opt_abcd c C
opt_abcd d D

Select widget with autocomplete

type
select_one {list_name}
appearance
autocomplete

The autocomplete appearance adds autocomplete to the search and filter feature. This is especially helpful for questions with a large number of choices.

The Select One form widget with autocomplete, as displayed in the ODK Collect app on an Android phone. The question text is "Select one search widget." The hint text is, "select one type with autocomplete appearance, 4 text choices." Below that is a text input followed by four radio buttons labeled A, B, C, and D. Above the question text is the form group name "Select one widgets." The device keyboard is active. The Select One form widget as displayed previously. The text input contains a lowercase 'b'. There is a single radio button: B. The other three radio buttons are no longer displayed.

XLSForm

survey
type name label appearance hint
select_one opt_abcd select_one_autocomplete_widget Select one search widget autocomplete select_one type with autocomplete appearance, 4 text choices
choices
list_name name label
opt_abcd a A
opt_abcd b B
opt_abcd c C
opt_abcd d D

Select widget with image choices

type
select_one {list_name}
appearance
none

Select widgets support image choices. The images are referenced in the choices sheet, and the image files need to be included in the media folder.

See Including images as choices to learn more about including images in surveys.

The Single Select form widget with images, as displayed in the ODK Collect app on an Android phone. The question text is, "Grid select one widget." The hint text is, "select_one type with no appearance, 4 image choices (a.jpg, b.jpg, c.jpg, d.jpg)." Below that is a set of radio buttons labeled A, B, C, and D. Below each radio button is a small icon of an animal: A - whale, B - frog, C - alligator, D - eagle. Above the question text is the form group name "Select one widgets."

XLSForm

survey
type name label appearance hint
select_one abcd_icon grid_widget Grid select one widget   select_one type with no appearance, 4 image choices (a.jpg, b.jpg, c.jpg, d.jpg)
choices
list_name name label media::image
abcd_icon a A a.jpg
abcd_icon b B b.jpg
abcd_icon c C c.jpg
abcd_icon d D d.jpg

Select widget with compact image options

type
select_one {list_name}
appearance
compact

When the compact appearance is added, the answer choices display in a single line.

The compact Single Select form widget with images, as displayed in the ODK Collect app on an Android phone. The question text is "Grid select one widget." The hint text is, "select_one with compact appearance, 4 image choices (a.jpg, b.jpg, c.jpg, d.jpg)." Below that are four small animal icons arranged on a single line. Above the question text is the form group name "Select one widgets."

XLSForm

survey
type name label appearance hint
select_one abcd_icon grid_widget_compact Grid select one widget compact select_one type with compact appearance, 4 image choices (a.jpg, b.jpg, c.jpg, d.jpg)
choices
list_name name label media::image
abcd_icon a A a.jpg
abcd_icon b B b.jpg
abcd_icon c C c.jpg
abcd_icon d D d.jpg

Select widget with width-specified images

type
select_one {list_name}
appearance
compact-{x}

With the compact-{x} appearance, you can specify the number of images to display on each row.

For example, to display two images on each row, specify an appearance of compact-2.

The single select form widget with images and appearance of 'compact-2,' as displayed in the ODK Collect app on an Android phone. The question text is, "Grid select one widget." The hint text is "select_one type with compact-2 appearance, 4 image choices (a.jpg, b.jpg, c.jpg, d.jpg)." Below that are four animal icons arranged in a two-by-two grid. Above the question text is the form group name "Select one widgets."

XLSForm

survey
type name label appearance hint
select_one abcd_icon grid_widget_compact2 Grid select one widget compact-2 select_one type with compact-2 appearance, 4 image choices (a.jpg, b.jpg, c.jpg, d.jpg)
choices
list_name name label media::image
abcd_icon a A a.jpg
abcd_icon b B b.jpg
abcd_icon c C c.jpg
abcd_icon d D d.jpg

Compact select widget with autoadvance

type
select_one {list_name}
appearance
quickcompact

The quickcompact appearance adds autoadvance functionality to the design of the Select widget with compact image options.

XLSForm

survey
type name label appearance hint
select_one abcd_icon grid_widget_quickcompact Grid select one widget quickcompact select_one type with quickcompact appearance, 4 image choices (a.jpg, b.jpg, c.jpg, d.jpg)
choices
list_name name label media::image
abcd_icon a A a.jpg
abcd_icon b B b.jpg
abcd_icon c C c.jpg
abcd_icon d D d.jpg

Compact select widget with specified width and autoadvance

type
select_one {list_name}
appearance
quickcompact-{x}

As with compact, you can specify a width when using quickcompact.

For example, to display two images on each row, set the appearance attribute to quickcompact-2.

XLSForm

survey
type name label appearance hint
select_one abcd_icon grid_widget_quickcompact2 Grid select one widget quickcompact-2 select_one type with quickcompact-2 appearance, 4 image choices (a.jpg, b.jpg, c.jpg, d.jpg)
choices
list_name name label media::image
abcd_icon a A a.jpg
abcd_icon b B b.jpg
abcd_icon c C c.jpg
abcd_icon d D d.jpg

Multi select widget

type
select_multiple {list_name}
appearance
none

Multi select questions support multiple answers.

Note

The multi select widget supports many of the same appearance attributes as the Single select widget:

The default multi select widget as displayed in the ODK Collect app on an Android phone. The question text is, "Multi select widget." The hint text is, "select_multiple widget with no appearance, 4 text choices." Below that are four checkbox options labeled A, B, C, and D. Above the question text is the form group label, "This section contains 'Select Multi Widgets'"

XLSForm

survey
type name label hint
select_multiple opt_abcd select_multi_widget Multi select widget select_multiple type with no appearance, 4 text choices
choices
list_name name label media::image
opt_abcd a A  
opt_abcd b B  
opt_abcd c C  
opt_abcd d D  

Warning

If you are using Aggregate and expect users to select many options, you may need to increase the database field length to over 255 characters.

Image map select widget

New in version 1.13.

type
select_one {list_name}, select_multiple {list-name}
appearance
image-map

The image map widget displays an SVG image with selectable regions.

To make an image with selectable regions:

  1. Create or edit an .svg source file. Include id attributes on any elements you want to be selectable.
  2. In the choices tab of your XLSForm, put the value of the id attributes in the name column. Add an appropriate human-friendly label to each choice.
  3. In the survey tab of your XLSForm, put the .svg file name in the image column.
  4. Include the .svg file in your form's media folder.

See also

Inkscape
An open source vector graphics editor.
SVG Documentation
From Mozilla Developer Network.
Free SVG Files
From Wikimedia Commons.

SVG

<svg width="640" height="480" xmlns="http://www.w3.org/2000/svg" xmlns:svg="http://www.w3.org/2000/svg">
  <title>shapes</title>
  <g>
    <title>Layer 1</title>
    <path id="path" fill="#000080" stroke="#000000" stroke-width="5" d="m125,382c33,56 -193,97 48,55c241,-42 279,-15 241,-62c-38,-47 -13,-42 -106,-40c-93,2 -183,47 -183,47z"/>
    <rect id="rect" fill="#FF0000" stroke="#000000" stroke-width="5" x="52" y="53" width="176" height="149"/>
    <ellipse id="ellipse" fill="#41A317" stroke="#000000" stroke-width="5" cx="423" cy="143" rx="107" ry="78"/>
  </g>
</svg>

XLSForm

survey
type name label appearance image
select_one shapes choose-shape Choose a shape image-map shapes.svg
select_multiple shapes choose-shapes Choose multiple shapes image-map shapes.svg
choices
list_name name label
shapes path blob
shapes rect rectangle
shapes ellipse ellipse

Including images as choices

To include images as choices for select questions:

  1. Specify the file name in the choices worksheet, in a column labeled media::image.
  2. Add the images to a folder named form-name-media.
  3. Upload the media folder with your form.
    • If you are hosting your form in ODK Aggregate, you will have the option to upload the media file with your form, and it will be automatically downloaded to your device when you pull down the blank form.
    • If you are adding the form to your device directly, make sure the media folder is placed in /sdcard/odk/forms/.

Randomizing choice order

To reduce bias, choice order can be randomized for any of the select question types described above. To display the choices in a different order each time the question is displayed, set randomize to true in the parameters column of the XLSForm survey sheet:

XLSForm

survey
type parameters name label hint
select_one opt_abcd randomize=true select_one_random_widget Select one widget Select one with random choice order set on each display
choices
list_name name label
opt_abcd a A
opt_abcd b B
opt_abcd c C
opt_abcd d D

In the example above, each time the question is displayed, the choices will be in a different order. It is often preferable to pick one order that the choices will always be displayed in for a given filled form. This can be accomplished by setting a seed for the randomization:

XLSForm

survey
type parameters name label hint calculation
calculate   my_seed     once(decimal-date-time(now()))
select_one opt_abcd randomize=true,seed=${my_seed} select_one_widget Select one with random choice order set once per filled form    
choices
list_name name label
opt_abcd a A
opt_abcd b B
opt_abcd c C
opt_abcd d D

This seed can also be used to recreate the order choices were displayed in. See the XForms spec for a description of the randomization algorithm used.

Note

In the seed expression, once() is important because it makes sure the seed is not changed if the same filled form is opened more than once.

Including "other" as a choice

On the survey sheet, in the type column, after the type and the list_name, you can add or_other. This will add "Other" as an additional option to your choice list. The name value of the choice when selected will be other.

Rank widget

The rank widget allows the user to order options from a list. The value saved in the form and sent to the server is a space-separated ordered list of the options.

Like with Select widgets, the options are listed on a sheet named choices in an XLSForm.

To change the order of the options in the list, tap the Rank items button. In the resulting dialog, long press on an item and once it gets a border around it, drag it up or down to change the order. If no default is provided, the value for the question is blank until the user taps OK in the ranking dialog.

type
rank {list_name}
The rank widget, as displayed in the ODK Collect app on an Android phone. The question text is "Rank widget." The hint text is "rank type with no appearance, 4 text choices. Long press on a choice and drag it to change its position." Below that is a button with label "Rank items." The rank widget, as displayed in the ODK Collect app on an Android phone. The question text is "Rank widget." The hint text is "rank type with no appearance, 4 text choices. Long press on a choice and drag it to change its position." A dialog is open showing the options to rank. The B option has a border around it and is being moved into position 4. The rank widget, as displayed in the ODK Collect app on an Android phone. The question text is "Rank widget." The hint text is "rank type with no appearance, 4 text choices. Long press on a choice and drag it to change its position." Below that is a button with label "Rank items." Below the button is the current order of the options.

XLSForm

survey
type name label hint
rank opt_abcd rank_widget Rank widget rank type with no appearance, 4 text choices
choices
list_name name label
opt_abcd a A
opt_abcd b B
opt_abcd c C
opt_abcd d D

Location widgets

Geopoint widget

type
geopoint
appearance
none

Captures the current location from the device.

For a geopoint with a user-selected location, see Geopoint with user-selected location

Tip

New in version 1.15.

While determining the current coordinates, you will see a dialog box displaying:

  • Number of satellites found
  • Elapsed time

To get an accurate fix on your location, the device must find at least four (4) satellites. If the device can not find at least four satellites, make sure there is nothing obstructing the device's view of the sky.

If you have problems with the geopoint widget, be sure to note the elapsed time and accuracy (if applicable), so that you can share it with your support staff or with the ODK Forum.

The default Geopoint form widget, as displayed in the ODK Collect app on an Android phone. The question text is, "Geopoint widget." The hint text is "geopoint type with no appearance." Below that is a button labeled "Start Geopoint." Below the button are completed fields for Latitude, Longitude, Altitude, and Accuracy.

XLSForm

survey
type name label hint
geopoint geopoint_widget Geopoint widget geopoint type with no appearance

Geopoint with map display

type
geopoint
appearance
maps

The default Geopoint widget does not display a map to the user. With the maps appearance attribute, a map of the recorded location is shown to the user.

The user cannot select a different location on the map. For a geopoint with a user-selected location, see Geopoint with user-selected location.

XLSForm

survey
type name label appearance hint
geopoint geopoint_widget_maps Geopoint widget maps geopoint type with maps appearance

Geopoint with user-selected location

type
geopoint
appearance
placement-map

The default Geopoint widget does not allow the user to select a location.

A geopoint with the appearance attribute placement-map allows the user to select a geopoint from a map.

A map app opens on an Android phone. Above the map is the message: "Long press to place mark or tap add marker button." Along the right side of the map are buttons: Add Marker, Zoom to point, Layers, Trash, Save.

XLSForm

survey
type name label appearance hint
geopoint geopoint_widget_placementmap Geopoint widget placement-map geopoint type with placement-map appearance

Geotrace widget

type
geotrace
appearance
none

A line or polygon of coordinates tracking actual device movement. The user can specify one of two location-recording modes:

Manual Mode
The user taps the device to place a marker as desired while moving.
Automatic Mode
The app creates a marker on a regular time interval (default: 20 seconds) as the user moves.
A geotrace form widget displayed in the ODK Collect app on an Android phone. The question text is "Where have you been?" and below that is a button with the label "Start GeoTrace." A modal popup over a map. The modal headline is "Zoom to..." Below that are two options: "Zoom to current location" (selected) and "Zoom to saved feature". In the bottom-right of the modal is a Cancel button. A map displayed in the ODK Collect App on an Android phone. Above the map is the instruction: Wait for lock, then tap add marker button start. On the right side are five icon buttons stacked vertically: Add marker, Zoom, Layers, Trash, Save. The same map as displayed in the previous image. Over the map is a modal popup. The modal headline is "Select GeoTrace Mode," followed by two radio-button (single select) options: Manual Mode (selected) and Automatic Mode. In the bottom-right are buttons for Cancel and Start. The same modal popup as in the previous image, but the Automatic Mode radio button is not selected. Below it are two drop-down select boxes. Their values are "20" and "seconds." The same map as displayed previously, but now a series of red markers form a line across the map. The same map as previously, with a new modal popup. The headline of the modal is "Save GeoTrace as" followed by two options: Save as Polygon and Save as Polyline. In the bottom-right is a Cancel button. The Geotrace form widget, as shown previously. The question text is "Where have you been?" and the button label is "View or Change GeoTrace." Below that is a list of lat/long coordinates.

XLSForm

survey
type name label
geotrace trace_example Where have you been?

Warning

If you are using Aggregate and you would like to collect more than 5 points at a time, you should increase the database field length to over 255 characters. Otherwise, additional points will be lost.

Geoshape

type
geoshape
appearance
none

Captures a user-entered series of location coordinates, forming a polygon.

The GeoShape form widget, as displayed in the ODK Collect app on an Android phone. The question text is "Select an Area." Below that is a button labeled "Start GeoShape." A modal popup over a map. The modal headline is "Zoom to..." Below that are two options: "Zoom to current location" (selected) and "Zoom to saved feature". In the bottom-right of the modal is a Cancel button. A map displayed in the ODK Collect App on an Android phone. Above the map is the instruction: "Long press to place marks." On the right side are five icon buttons stacked vertically: Add marker, Zoom, Layers, Trash, Save. The same map as displayed previously, but now a series of red markers form a polygon across the map. The GeoShape form widget shown previously. The question text is "Select an Area." The button label is now "View or Change GeoShape." Below the button is a list of lat/long coordinates.

XLSForm

survey
type name label
geoshape shape_example Select an area

Warning

If you are using Aggregate and you would like to collect more than 5 points at a time, you should increase the database field length to over 255 characters. Otherwise, additional points will be lost.

Calculating the area of a geoshape

type
calculate
calculation
area(${geoshape})

The area() function calculates the land area, in square meters, of a polygon defined in a Geoshape. The value will be included in your completed survey data, and can also be used in later widgets in the form.

The geoshape widget. The question label is "Record a geoshape". The button label is "Start GeoShape". A map with four pins defining an area around a city block. The geoshape widget with a series of lat/long coordinates. A note widget. "The area of the recorded geoshape is 19322 square meters."

XLSForm

type name label calculation
geoshape shape Record a Geoshape  
calculate shape_area   area(${shape})
calculate rounded_shape_area   round(${shape_area}, 2)
note shape_area_note
The area of the recorded geoshape is:
${rounded_shape_area} m²
 

Bearing widget

type
decimal
appearance
bearing

Captures a compass reading, which is stored as a decimal.

The Bearing form widget, as displayed in the ODK Collect app on an Android phone. The question text is, "Bearing widget." The hint text is, "decimal type with bearing appearance. Below that is a button labeled "Record Bearing." Above the question text is the form group name "Numeric widgets." The Bearing widget, overlaid with a model popup. The modal headline is "Loading Bearing." In the body of the modal are two fields: "Direction: W" and "Bearing: 273.001". At the bottom of the modal are Cancel and Record Bearing buttons. The Bearing widget, as displayed previously. The button's label is not "Replace bearing." Below the button is the decimal number 271.538 (the recorded bearing).

XLSForm

survey
type name label appearance hint
decimal bearing_widget Bearing widget bearing decimal type with bearing appearance

OpenMapKit widget

OpenMapKit allows you to add questions about OpenStreetMap features in a Collect-rendered form.

For more details, see the OpenMapKit documentation.

Image widgets

Default image widget

type
image
appearance
none

Captures an image from the device. The user can choose to take a new picture with the device camera, or select an image from the device photo gallery.

The default Image form widget, as displayed in the ODK Collect app on an Android phone. The question text is, "Image Widget." The hint text is, "image type with no appearance." Below that are two buttons: "Take Picture" and "Choose Image." Above the question text is the form group name "Image widgets."

XLSForm

survey
type name label hint
image image_widget Image widget image type with no appearance

Image widget with annotation

type
image
appearance
annotate

Adding the annotate appearance allows the user to draw on the image before submitting it.

The Annotate form widget, as displayed in the ODK Collect app on an Android phone. The question text is, "Annotate widget." The hint text is, "image type with annotate appearance." There are three buttons: "Take Picture," "Choose Image," and "Markup Image." The Markup Image button is disabled. Above the question text is the form group name "Image widgets." The camera view on an Android phone. In the viewer is a picture of a small saucer. Below the viewer is a blue checkmark button. The Annotate form widget displayed previously. The Markup Image button is now enabled. Below the buttons is the picture of a saucer shown previously. The image of a saucer on a drawing pad, with a poorly-drawn cup of tea drawn over it. In the lower right corner is a plus sign (+) in a circle. The same picture shown in the previous image. The menu in the bottom right corner has expanded to show the options: Reset, Save and Close, and Set Color. The Annotate form widget shown previously. The drawn-on picture is below the buttons.

XLSForm

survey
type name label appearance hint
image annotate_image_widget Annotate widget annotate image type with annotate appearance

Image widget with required new image

type
image
appearance
new

An image widget that does not include a Choose Image button. This requires the user to take a new picture.

The new image widget, as displayed in the ODK Collect app on Android. It is largely identical to the previous image widget, except that there is only a Take Picture button, and there is no Choose Image button.

XLSForm

type name label appearance hint
image image_widget_no_choose Image widget without Choose button new image type with new appearance (can also be added with annotate appearance and on audio and video types)

Self portrait (selfie) widget

type
image
appearance
new-front

Takes a picture using the front-facing ("selfie") camera. The Choose image button is not displayed.

Changed in version 1.15: Prior to v1.15, the appearance attribute for this was selfie. The old appearance attribute will continue to work on existing forms, but new forms should use the new-front appearance.

The self portrait widget in Collect. The label text is "Self portrait (selfie) widget)". The hint text is "Image type with new-front appearance". There is a button labeled "Take Picture". The camera screen on a device, taking a self-portrait of a person. The self portrait widget as described above. Below the button is the self-portrait image captured in the previous image.

XLSForm

survey
type name label hint appearance
image self-portrait Self portrait (selfie) widget image type with new-front appearance new-front

Draw widget

type
image
appearance
draw

Provides the user a drawing pad and collects the drawn image.

The Draw form widget, as displayed in the ODK Collect app on an Android phone. The question text is, "Draw widget." The hint text is "image type with draw appearance." Below that is a button labeled "Sketch Image." Above the question text is the form group name "Image widgets." A white "drawing pad" on an Android phone, horizontally oriented (landscape mode). A simple smiley face has been drawn. In the lower right corner of the drawing pad is a plus sign (+) in a circle. The drawing pad as displayed in the previous image. A menu has expanded from the lower right corner with the options: Reset, Save and Close, and Set Color. The Draw widget as displayed previously. Below the "Sketch Image" button is the smiley face from the drawing pad image shown previously.

XLSForm

survey
type name label appearance hint
image draw_image_widget Draw widget draw image type with draw appearance

Scaling down images

Images created with any of the image widgets described above can be automatically scaled down on save by using the max-pixels parameter. If the long edge of the image is larger than the maximum size specified, the image is resized proportionally so that the long edge matches the provided pixel value. This is useful to reduce the upload size when bandwidth is limited.

Available in Collect since v1.10.0 and in XLSForm since 7/2018.

XLSForm

In the parameters column, write max-pixels= followed by the desired maximum length of the long edge in pixels.

survey
type name label parameters hint
image my_scaled_image Scaled image max-pixels=1024 image scaled to a max long edge of 1024 pixels

Audio widget

Records audio from an external app.

Note

Some Android devices provide a default application for audio recording. Others do not, and the user will need to install an audio recording app.

There are many apps available for this, including:

Any app that responds to android.provider.MediaStore.Audio.Media.RECORD_SOUND_ACTION will be compatible.

The Audio form widget as displayed in the ODK Collect App on an Android phone. The question text is "Please record your name." There are three buttons: Record Sound, Choose Sound and Play Sound. The "Play Sound" button is disabled.

XLSForm Rows

survey
type name label
audio name_pronounce Please record your name.

Video widget

Records video, using the device camera.

The Video form widget as displayed in the ODK Collect App on an Android phone. The question text is "Please record a video of yourself blinking." The hint text is "Three times is probably sufficient." Below that are three buttons: Record Video, Choose Video, and Play Video. The Play Video button is disabled. The Android camera app, in video mode. A person's face is in the camera viewer. Below the camera viewer is a large, blue checkmark button. The Video form widget as displayed previously. The question text is "Please record a video of yourself blinking." The hint text is "Three times is probably sufficient." Below that are three buttons: Record Video, Choose Video, and Play Video. All three buttons are enabled.

XLSForm Rows

survey
type name label hint
video blinking Please record a video of yourself blinking. Three times is probably sufficient.

File upload widget

New in version 1.15: ODK Collect v1.15.0

Uploads any file from the device to the form.

Warning

Users can upload any file type, which includes potentially malicious files. You should not include this widget unless you trust the people using the form.

Even then, you should take precautions before downloading or opening files.

  • Run an antimalware scan.
  • Verify the file is a type you expect (such as a .pdf document), and not a potentially dangerous file (such as .exe or .ini).
The file upload widget in Collect. The question label is "Select a file to upload." Below that is a button labeled "Choose File". A  file selection screen on an Android device. A sidebar overlay is labeled "Open from". This sidebar has several file locations such as "Recent", "Google Drive", "Images", "Downloads".

XLSForm

survey
type name label
file some-file Select a file to upload.

Barcode widget

Scans, decodes, and captures the content of a barcode, using the device 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.

The Barcode form widget as displayed in the ODK Collect app on an Android phone. The headline text reads, "Scan any barcode." Below that is an image labeled "Get Barcode." A barcode scanner on an Android device. A barcode is in the viewfinder, with a thin blue line across the barcode. The Barcode form widget as displayed previously. The button label is now "Replace Barcode." Below the button is a string of numbers representing the decoded content of the scanned barcode.

XLSForm

survey
type name label
barcode barcode_example Scan any barcode.

Note

Barcode scanning is built into Collect versions 1.7.0 and greater.

Versions of Collect prior to 1.7.0 require the Barcode Scanner app to be installed.

Range widgets

Range widgets allow the user to select numbers from within a range that is visually represented as a number line. The parameters of the range widget are defined by start, end, and step values defined in the parameters column of your XLSForm. The parameter values can be integers or decimals.

Default range widget with integers

type
range
appearance
none

If all three parameter values are integers, the input will be stored as an integer.

The range widget, as displayed in the ODK Collect app on Android. The question text is "Range integer widget". The main part of the widget shows a horizontal line labeled "1" on the left end and "10" on the right. There are ten points on the line.

XLSForm

survey
type name label appearance hint parameters
range range_integer_widget Range integer widget   range integer widget with no appearance start=1;end=10;step=1

Default range widget with decimals

type
range
appearance
none

If any of the parameter values are decimals, the input will be stored as a decimal.

The range widget as displayed previously. The number selection choices range from 1.5 to 5.5, and the selection line is horizontal.

XLSForm

survey
type name label appearance hint parameters
range range_decimal_widget Range decimal widget   range decimal widget with no appearance start=1.5;end=5.5;step=0.5

Vertical range widget

type
range
appearance
vertical

To display the range widget's number line vertically, use the vertical appearance. Both integers and decimals are supported.

The range widget, as displayed in the previous image, but the range number line is vertical instead of horizontal.

XLSForm

survey
type name label appearance hint parameters
range range_integer_widget_vertical Range vertical integer widget vertical range integer widget with vertical appearance start=1;end=10;step=1

Range widget with picker

type
range
type
picker

When the picker appearance is added, the range widget is displayed with a spinner-style select menu in a dialog. The value between horizontal lines is the selected value. Users can scroll the spinner up and down or can tap on the value above to go up by one and on the value below to go down by one.

The range picker widget, as displayed in the ODK Collect app. The question label is "Range picker integer widget". There is a button labeled "Select Value". The range widget as shown in the previous image. Over it is a modal window labeled "Number Picker", with a spinner-style number select. Below are buttons for OK and CANCEL.

XLSForm

survey
type name label appearance hint parameters
range range_integer_widget_picker Range picker integer widget picker range integer widget with picker appearance start=1;end=10;step=1

Note widget

type
note
appearance
none

A note to the user, accepting no input. This example includes hint text.

The Note form widget as displayed in the ODK Collect App on an Android phone. The headline text is, "This is an example note." The hint text is, "The text displays, but there is no input."

XLSForm

type name label hint
note note_1 This is an example note. The text displays, but there is no input.

URL widget

type
text
appearance
url

Provides a link which the user can open from the survey. Takes no input.

The URL to open is specified with default.

The URL form widget, as displayed in the ODK Collect app on an Android phone. The question text is "URL Widget." The hint text is "text type with url appearance and default value of http://opendatakit.org/" Below that is a button labeled, "Open URL." Below the button is the URL, "http://opendatakit.org/" Above the question text is the form group name "Text widgets."

XLSForm

survey
type name label appearance hint default
text url_widget URL widget url text type with url appearance and default value of http://opendatakit.org/ http://opendatakit.org/

Printer widget

type
text
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.

See Printing Labels with the Printer Widget for complete details.

The external printer widget, as displayed in the ODK Collect app on an Android phone. The question text is "Ex printer widget." The hint text is "text type with printer:org.opendatakit.sensors.ZebraPrinter." Below that is a button labeled, "Initiate Printing." Above the question text is the form group name "Text widgets."

XLSForm

survey
type name label appearance calculation
text ex_printer_widget Ex printer widget printer:org.opendatakit.sensors.ZebraPrinter concat('123456789','<br>’,'QR CODE','<br>','Text')

Trigger/acknowledge widget

type
trigger, acknowledge
appearance
none

The trigger widget, also known as the acknowledge widget, presents a single checkbox.

A completed trigger response is stored as the string OK.

The example shown here includes the required attribute.

The Trigger (or "Acknowledge") form widget as displayed in the ODK Collect App on an Android phone. The question text is, "Trigger widget." The hint text is, "Prompts for confirmation. Useful to combine with required or relevant. (type=trigger)" Below that is a single checkbox labeled, "OK. Please continue." The checkbox is unchecked. The Trigger widget shown previously. An error text reads, "Sorry, this response is required." The Trigger widget shown previously. The checkbox is now checked.

XLSForm

survey
type name label hint required
trigger my_trigger Trigger widget Prompts for confirmation. Useful to combine with required or relevant. (type=trigger) true()

Signature widget

type
image
appearance
signature

Collects a signature from the user.

The Signature form widget, as displayed in the ODK Collect app on an Android phone. The question text is, "Signature widget." The hint text is "image type with signature appearance." Below that is a button labeled "Gather Signature." Above the question text is the form group name "Image widgets." A drawing pad with a signature line, displayed on an Android phone. A signature is drawn across it. In the lower right corner is circular button marked with a plus sign (+). The signature widget displayed previously. Below the button is the signature drawn in the previous image.

XLSForm

table
type name label appearance hint
image signature_widget Signature widget signature image type with signature appearance

Hidden questions

Not all question types render as visible widgets in Collect. These questions do collect and store values, which are accessible as variables and available in Aggregate and other data analysis tools.

Metadata

Metadata questions capture information about the device or the survey collection event and are not visible to the user. A more complete record of user behavior within a form can be generated by enabling form audit logging.

These items are dependent on the survey collection event:

  • start — The time the survey was started.
  • end — The last time the survey was saved.
  • today — The current date, according to the device, when the survey is collected.

These items are defined by the device and cannot be changed:

  • deviceid
  • subscriberid
  • simserial

These items are defined in Collect, and can be edited in Settings:

  • username
  • phonenumber

XLSForm

survey
type name
start start
end end
today today
deviceid deviceid
subscriberid subscriberid
simserial simserial
username username
phonenumber phonenumber

Calculate

type
calculate

Calculate questions let you evaluate complex expressions, storing the values for later use.

For more details, see Calculations.


Grouping multiple widgets on the same screen

type
begin_group
appearance
field-list

The field-list appearance attribute, applied to a group of widgets, displays them all on a single screen.

Warning

Do not include a question that depends on a previous answer in the same field list as the previous question it depends on.

Relevance and calculation values are determined when the screen advances, which does not happen between questions that are grouped on the same page. Therefore, including a question and its dependent together in a field list will not work as expected.

Select widgets included in a field-list group can have one of several appearance attributes:

label
Only the option labels are displayed, without checkboxes.
list
The labels are displayed along with checkboxes for multi-select questions and radio buttons for single-select questions.
list-nolabel
Only checkboxes or radio buttons are displayed, without their labels. This is often used for sets of questions with repeated answer choices.
A field-list group of questions, as displayed in the ODK Collect app on an Android phone. Six questions are displayed. Below each, the answer choices are arranged in a row. The continuation of the previous image.

XLSForm

survey
type name label appearance hint
begin_group table_list_test List group field-list  
select_one yes_no table_list_test_label Label widget label Show only the labels of these options and not the inputs (type=select_one yes_no, appearance=label)
select_multiple yes_no table_list_test_label_2 Label multi widget label Show only the labels of these options and not the inputs (type=select_multiple yes_no, appearance=label)
select_one yes_no table_list_1 List widget list-nolabel Show only the inputs of these options and not the labels (type=select_one yes_no, appearance=list-nolabel)
select_multiple yes_no table_list_2 List multi widget list-nolabel Show only the inputs of these options and not the labels (type=select_multiple yes_no, appearance=list-nolabel)
select_one yes_no list_widget List widget list This is a normal list widget with (type = select_one, appearance = list)
select_multiple yes_no list_multi_widget List multi widget list This is a normal list widget with (type = select_multiple, appearance = list)
end_group        
choices
list_name name label
yes_no yes Yes
yes_no no No
yes_no dk Don't Know
yes_no na Not Applicable