Examples

This page is a reference guide for users who edit the raw XML in ODK forms. If you use the XLSForm form designer, see http://xlsform.org for form design help.

Here are examples of each prompt type supported by ODK Collect and how each is shown to the user. Click on the "Show Snippet" button to reveal the XML snippet that generates the prompt. For full forms, see the sample forms repository.

Naming your Submission

You can now automatically name each filled-in form in a way that utilizes the data entered into the form. For example, you might use a concatenation of a unique household ID with the respondent name as the name of the filled-in form.

To do this, in the XLS file, add a new instance_name column to your form's settings worksheet. Below that column heading, define the expression that will be used to form the name of the filled-in form.

I.e., in this case, you might define:

concat(${hhid},' - ', ${respondent_name})

Note that whatever you put in the instance_name column should evaluate to a string; so, for example, "today()" alone won't work to name forms using the current date, but "string(today())" will work.

This is implemented within the XML as an instanceName field within the meta block. If this value is present and not an empty string (""), it will be used as the name of the filled-in form. Otherwise, the current default naming, based upon the date the form was first saved, will be used.

Grouping Questions together on One Screen

To group questions together on one screen, wrap the questions in a group with an appearance of "field-list".

Show Snippet

Data Entry Widgets

These provide the various prompts for data entry.

Populate a Group of Fields from a 3rd party app

Beginning with ODK Collect 1.4.3, you can invoke a 3rd party app to populate a group of fields within your form. See External Apps

String Prompts

These prompts allow a user to type in an arbitrary string. To restrict the size or content of that string, use constraints. Note that ODK Aggregate truncates string values to 256 characters; see Datastore string length for how to alter that behavior.

Use the Select One and Select Multiple Prompts to present a list of fixed choices to the user.

String


Show Snippet

String from a 3rd party app


Show Snippet

String with numeric keypad entry


Show Snippet

Integer Prompts

Integers cannot be greater than 2,147,483,648 or less than 2,147,483,647. If you need to capture a longer integer value, use the String with numeric keypad entry prompt type.

Integer


Show Snippet

Integer from a 3rd party app


Show Snippet

Decimal Prompts

Decimal prompts can represent decimal numbers to about 15 digits of accuracy. If you need to capture a decimal value with higher accuracy, use the String with numeric keypad entry prompt type.

Decimal


Show Snippet

Decimal from a 3rd party app


Show Snippet

Bearing (in degrees)


Show Snippet

Date and DateTime Prompts

Year-only, Year-and-month and full date prompt widgets are available. If a Year-and-month widget is used, the recorded date will the be first of the selected month. If a Year-only widget is used, the recorded date will be January 1st of that year.

Date

On newer Android 4.x devices, this appears as:


Show Snippet

Date without Calendar

To suppress the calendar on newer Android 4.x devices, use the no-calendar appearance.


Show Snippet

Date displaying only month and year spinner


Show Snippet

Date displaying only year spinner


Show Snippet

Date, time


Show Snippet

Time


Show Snippet

Geo-location Prompts

NOTE: Device bearing is a decimal prompt type. See here

Your Android device can be configured to use either GPS satellites or wireless networks, or both, to determine your location. This configuration is available under Settings / Location and Security / My Location.

ODK Collect uses the selected geo-location method(s) to obtain a location. Users can either immediately accept a lower-accuracy location or wait until the accuracy drops below 5 meters, at which point ODK Collect will automatically accept the location value. See the snippet for how to change this 5m accuracy threshold.

After ODK Collect 1.4.3 (when this functionality was added), when referenced in formulas, the following conversions apply:

  • boolean(.) - Not functional. There is an underlying library issue that prevents this from working; you must parse the string value and calculate this value. returns true if the geo-location has been captured.
  • number(.) - Not functional. There is an underlying library issue that prevents this from working; you must parse the string value and calculate this value. returns the accuracy of the geo-location in meters. If the geoPoint has not been captured, this conversion returns 9999999.0 meters (bigger than the radius of the earth).
  • string(.) - returns the space-separated geo-location or "" if no geo-location has been captured. The values in this string are the latitude, longitude, altitude and accuracy.

Location


Show Snippet

Location with map


Show Snippet

Place and Move Location with map

This widget is only available on Android 2.2 and higher. It requires Google Services (installable via Google Play) and an active internet connection (to access map tiles).


Show Snippet

Barcode Reader Prompt

Barcode detection relies on a 3rd party app to detect the barcode. Some newer phones provide this capability as part of the camera app. The Zxing Barcode Scanner is free and works well.

The capabilities of the 3rd party app determine what barcodes or QRCodes can be detected. The Zxing Barcode Scanner will detect both.


Show Snippet

OpenStreetMap (OSM) OpenMapKit Prompt

Available beginning with ODK Collect 1.4.6

As an alternative to GPS points for location in your survey, you can select an OpenStreetMap feature and associate it with your form instance. This capability is provided through the third-party app OpenMapKit.

This prompt uses the OSM Upload Media Type. With OpenMapKit installed, the Launch OpenMapKit button will launch OpenMapKit where the user selects and tags an OSM feature. That OSM data, with the OSM ID in the file name, is sent back to ODK Collect as a media attachment.


Show Snippet

Image Capture, Sketching and Signature Capture Prompts

Image capture, select Prompts

Image capture relies on the configuration and capabilities of the device's camera app.


Show Snippet

Image capture, select with annotations

Available beginning with ODK Collect 1.2.1

The dimensions of the captured image will be reduced to fit the device screen prior to annotation. The annotation widget does not support panning or zooming.


Show Snippet

Freeform drawing

Available beginning with ODK Collect 1.2.1


Show Snippet

Capture Signature

Available beginning with ODK Collect 1.2.1


Show Snippet

Audio capture, select

Audio capture relies on the configuration and capabilities of the device's audio recorder app. On newer 4.x devices and tablets, the supplied audio recorder app may not provide a good user experience when launched from ODK Collect. The RecForge Lite audio record app is free and may provide a better user experience. If you require longer recordings, a Pro version available.


Show Snippet

Video capture, select

Video capture relies on the configuration and capabilities of the device's camera app.


Show Snippet

Acknowledge


Show Snippet

Output


Show Snippet

Select One and Select Multiple Prompts

Select prompts offer the user a selection from among a fixed set of values. For each entry in the list of choices, the designer must specify a string value and one or more translations of the display text to present to the user. ODK Collect records the string value in the field, not the display text. If a select-multiple prompt is used, the string values for the selected choices are stored as space-separated text in that field. Thus, to be interpretable during data analysis, when defining the string values of the choices for a select-multiple field, those string values should not contain any spaces.

There is no way directly within ODK Collect to provide a selection prompt for a changing or growing set of choices. If you need that functionality, you can use the String from 3rd party app widget to launch your own application that presents that list of choices to the user and returns the selected value(s) as a string.

Select one


Show Snippet

Select one with search


Show Snippet

Select one with auto-advance


Show Snippet

Select multi


Show Snippet

Select one spinner


Show Snippet

Select multi spinner


Show Snippet

Select one grid


Show Snippet

Select one grid with auto-advance


Show Snippet

Select multi grid


Show Snippet

Select one list


Show Snippet

Select multi list


Show Snippet

Printing Widget

Printing is only possible on devices running Android 3.1 or higher.

Printing is available beginning with ODK Collect 1.3; the supplied printing widget uses the ODK Sensors Framework and ODK Zebra Printer Driver to print on Zebra MZ Series printers. We have tested using MZ220 and MZ320 printers.

The printing widget emits a label with up to three parts, in order:

  • Numeric barcode
  • QRcode
  • Text output

The quantity of data that can be represented in the QRcode is dependent upon the width of the paper on which it is printed (these are the square barcodes that are often used to encode URLs). For the MZ220, the limit is probably around 240 characters.

The printer widget is used whenever a string field supplies 'printer' as the value for its appearance attribute. The value of the string field defines the label to be printed. This will typically be created using a calculate expression.

The label consists of zero or more parts separated by <br> (this exact 4-character string). The first part (everything before the first <br>) defines the numeric barcode to be printed; if blank, no barcode is printed. The second part defines the QRcode; if blank, no QRcode is printed. The remaining part(s) are the line(s) of text to be printed (if any). Note that the Zebra printer and the printer driver do not recognize or support HTML formatting tags other than this special interpretation of the 4-character <br> string.


Show Snippet

Presentation Options

Displaying multiple prompts on a single screen

Multiple prompts can be placed upon the same screen by enclosing them within a group with a "field-list" appearance.

ODK Collect does not recompute the relevance (visibility) of all the questions on a screen as data is entered into those questions. As a result, if you have Q2 relevance (visibility) depending upon an answer to Q1, and both are on the same screen, Q2 will be visible or hidden based upon the initial state of Q1 when the combined screen is shown, and it will never display until you leave and re-enter the screen, at which point the value of Q1 will be re-examined and Q2 will be made visible based upon Q1's (now potentially different) value.


Show Snippet

Autoplay Audio

Upon advancing to a question, the audio clip defined for that prompt can be automatically played by specifying an autoplay attribute with a value of "audio" on the prompt. This attribute can be applied to any widget, but is ignored if the widget is within a field-list (multi-question screen).

Show Snippet

Autoplay Video

Upon advancing to a question, the video clip defined for that prompt can be automatically played by specifying an autoplay attribute with a value of "video" on the prompt. This attribute can be applied to any widget, but is ignored if the widget is within a field-list (multi-question screen).

Show Snippet

Preloaded Fields

Start and End Timestamps

Form start and end timestamps can be loaded into data elements of your form. The snippet shows two fields receiving the start and end timestamp values, respectively.

Show Snippet

Property values

Information about the user and phone can be preloaded into data elements of your form. The snippet shows a field that is preloaded with the Google Account (e-mail) that was configured on ODK Collect's settings page. What value is preloaded is defined by the value of the jr:preloadParams attribute in the bind. The property values beginning with "uri:" prepend a namespace prefix to their values but otherwise return the same value as their non-uri-prefixed counterparts. This can be particularly useful for interpreting device IDs.

jr:preloadParams Example Notes
uri:deviceid imei:A0006F5E212
mac:01:23:45:67:89:ab
android_id:1401111
Unique identifier of phone. Guaranteed not to be blank. Either the cellular IMEI, WiFi mac address, or Android ID (a unique identifier assigned by the operating system).
deviceid A0006F5E212
01:23:45:67:89:ab
1401111
Unique identifier of phone. Guaranteed not to be blank. Either the cellular IMEI, WiFi mac address, or Android ID (a unique identifier assigned by the operating system).
uri:email mailto:user@your.org Google Account configured in ODK Collect settings page
email user@your.org Google Account configured in ODK Collect settings page
uri:username username:authuser Username configured in ODK Collect settings page. Will be blank if not set. Note that this is not necessarily the username used when submitting the form (since the user can manually specify a different username).
username authuser Username configured in ODK Collect settings page. Note that this is not necessarily the username used when submitting the form (since the user can manually specify a different username).
uri:phonenumber tel:12065551212 Phone number of phone. May be blank (e.g., tablets).
phonenumber 12065551212 Phone number of phone. May be blank (e.g., tablets).
uri:simserial simserial:SD655E212 SIM serial number of phone. May be blank (e.g., tablets).
simserial SD655E212 SIM serial number of phone. May be blank (e.g., tablets).
uri:subscriberid imsi:SD655E212 IMSI of phone. May be blank (e.g., tablets).
subscriberid SD655E212 IMSI of phone. May be blank (e.g., tablets).

Show Snippet