XLSForm Reference Table
This page is a work-in-progress reference for all available functions in XLS Forms. It is divided into the three possible sheets: survey, choices, and settings.
survey
This sheet is mandatory in all XLSForms.
Category | Item | Description | Enketo? | Collect? | Synonyms | Notes |
---|---|---|---|---|---|---|
Column headers | ||||||
type | Sets the question type, see above | ✔ | ✔ | |||
name | Unique ID (name) of the question, is saved to XML | ✔ | ✔ | |||
label::[language] | Question or group label if using only one survey language, is displayed on screen | ✔ | ✔ | ::[language] is optional | ||
hint::[language] | Hint for a question if using only one language | ✔ | ✔ | ::[language] is optional | ||
guidance_hint::[language] | Special kind of hint that is normally not shown in the form, only in special views. | ✔ | ✔ | ::[language] is optional | ||
constraint | Define the allowed values to a response | ✔ | ✔ | |||
constraint_message::[language] | The message a user is shown if the response was not valid | ✔ | ✔ | constraint-msg | ::[language] is optional | |
required | Whether a question has to be answered in order for the form to continue/be saved | ✔ | ✔ | bind::required | Allowed values: yes, no, TRUE, FALSE, true(), false(); or a statement that evaluates as true or false | |
required_message::[language]] | Allows to customize the error message if required question is not answered | ✔ | ✔ | requiredMsg | ::[language] is optional | |
default | A default value that is pre-filled before the user gets to the question | ✔ | ✔ | |||
relevant | Skip logic condition (the relevant condition that needs to be fulfilled in order for the present question to be displayed) | ✔ | ✔ | |||
read_only | Whether a question response can be edited | ✔ | ✔ | Allowed values: yes, no, TRUE, FALSE, true(), false(); or a statement that evaluates as true or false | ||
calculation | Only relevant for calculate questions: a mathematical expression that can be referenced elsewhere | ✔ | ✔ | |||
repeat_count | Number of repeats for a repeat group | ✔ | ✔ | repeat-count | ||
image | An image to be shown with a question | ✔ | ✔ | |||
audio | Audio to be included with a question | ✔ | ✔ | |||
video | A video to be included with a question | ✔ | ✔ | |||
image::language | ✔ | ✔ | media::image::language | ::[language] is optional | ||
audio::language | ✔ | ✔ | media::audio::language | ::[language] is optional | ||
video::language | ✔ | ✔ | media::video::language | ::[language] is optional | ||
appearance | Defines the way questions are displayed (widgets), see below | ✔ | ✔ | |||
instance::attribute | include custom XML content for the data instance | depends | depends | |||
bind::attribute | include custom XML content for the bind attribute | depends | depends | |||
body::attribute | include custom XML content in the body | depends | depends | |||
body::accuracyThreshold | set the minimum GPS accuracy level before automatically registering the coordinates | ✕ | ✔ | |||
parameters | available settings for some question types | ✔ | ✔ | |||
Questions | These are put into the ‘type’ column | |||||
Meta questions | These are hidden to the user, but otherwise work like regular questions | |||||
start | Record when the form was loaded | ✔ | ✔ | |||
end | Record when the form was finished | ✔ | ✔ | |||
today | Record the date the form was loaded | ✔ | ✔ | |||
deviceid | Get the device ID (for Android devices) | ✔ | ✔ | imei | Enketo will generate a unique ID for a browser-device combo. | |
username | Get the user name (set in ODK settings) | ✔ | ✔ | |||
subscriberid | ✕ | ✔ | ||||
simserial | ✕ | ✔ | ||||
phonenumber | ✕ | ✔ | phone_number | TBC: phone_number | ||
Add user email to submission (if used) | ? | ? | ||||
audit | Record enumerator behavior | ✕ | ✔ | optional settings in parameters column to enable location tracking: location-priority, location-min-interval, location-max-age | ||
Regular questions | ||||||
select_one [choices] [or_other] | User can choose one of several choices | ✔ | ✔ | select one | ||
select_multiple [choices] [or_other] | User can choose one or more of several choices | ✔ | ✔ | select multiple | ||
select_one_from_file [file] | User can choose one of several choices from an external file | ✔ | ✔ | Optional settings in parameters column: 'value' (string, default = 'name') for the choice value column in the external file, 'label' (string, default = 'label') for the choice label column in the external file, 'randomize' (bool, default = 'false') to activate choice randomization, and 'seed' (number, default = none) to set the randomization seed value. | ||
select_multiple_from_file [file] | User can choose one or more of several choices from an external file | ✔ | ✔ | Optional settings in parameters column: 'value' (string, default = 'name') for the choice value column in the external file, 'label' (string, default = 'label') for the choice label column in the external file, 'randomize' (bool, default = 'false') to activate choice randomization, and 'seed' (number, default = none) to set the randomization seed value. | ||
select_one_external | ✕ | ✔ | ||||
rank [choices] | User can rank a list of choices | ✔ | ✔ | |||
text | User can enter a text response | ✔ | ✔ | |||
integer | User can enter an integer | ✔ | ✔ | |||
decimal | User can enter a decimal number | ✔ | ✔ | |||
date | User can enter a date | ✔ | ✔ | |||
time | User can enter a time of day | ✔ | ✔ | |||
datetime | User can enter date and time together | ✔ | ✔ | |||
geopoint | User can record a GPS location | ✔ | ✔ | location | ||
image | User can take or attach a picture | ✔ | ✔ | photo | ||
audio | User can record or attach audio | ✔ | ✔ | Collect accepts an optional quality parameter with possible values voice-only, low, normal and external | ||
background-audio | Audio is recorded in the background while filling the form | ✕ | ✔ | optional quality parameter with possible values voice-only, low and normal | ||
video | User can record or attach video | ✔ | ✔ | |||
file | User can attach file of any type | ✔ | ✔ | |||
note | User is shown a note (no response possible) | ✔ | ✔ | |||
barcode | User can enter a barcode by scanning it | ✕ | ✔ | |||
acknowledge | User is asked to confirm or acknowledge something | ✔ | ✔ | trigger | ||
calculate | A mathematical expression of existing values that can be used by other questions (no user input) | ✔ | ✔ | Calculate creates an instance variable with no body element that gets set by an xpath expression (specified in the calculation column) | ||
geotrace | User can record a line or polyline or multiple geo points | ✔ | ✔ | |||
geoshape | User can record a polygon of multiple geo points - the last point is the same as the first point | ✔ | ✔ | |||
Groups | Groups contain one or more questions, or other nested groups, which may loop (repeat) | |||||
begin_group | Sets the beginning of a group | ✔ | ✔ | begin group | ||
end_group | Ends the group | ✔ | ✔ | end group | ||
begin_repeat | Sets the beginning of a repeat group | ✔ | ✔ | |||
end_repeat | Ends the repeat group | ✔ | ✔ | |||
Form Variable References | ||||||
${variable_name} | Reference another question (can be used in skip logic condition [relevant], validation, inside another question or hint label | ✔ | ✔ | |||
. | Current question | ✔ | ✔ | |||
Appearance | (For more controlled views using widgets) | |||||
Groups | ||||||
field-list | Multiple questions of a group on a screen | ✔ | ✔ | Needs to be applied to a group | ||
table-list | Show multiple select1s with a shared label in a field list. | ✔ | ✔ | Needs to be applied to a group | ||
select_one / select_multiple | ||||||
minimal | Spinner widget - click button to provide a response | ✔ | ✔ | |||
label | Table of answers | ✔ | ✔ | |||
list-nolabel | Goes with label, no label on answer just radios | ✔ | ✔ | |||
autocomplete | Autocomplete widget | ✔ | ✔ | search | Not supported on select_multiple in Enketo | |
likert | Shows question as likert widget | ✔ | ✔ | |||
horizontal | Displays choices horizontally and automatically creates neat columns for multiple rows | ✔ | ✔ | |||
compact | Displays choices horizontally as compact as possible | ✔ | ✔ | horizontal-compact | ||
compact-n | Grid widget with max n columns where n is a number from 1 to 10, e.g. use compact-2 or compact-3 | ✔ | ✔ | |||
quick | Auto advance to next question upon selection | ✕ | ✔ | |||
quickcompact | Displays choices horizontally as compact as possible. Auto advance to next question upon selection | ✕ | ✔ | quick compact | ||
image-map | When used in conjunction with an SVG media label, the select question will be presented as a clickable image. | ✔ | ✔ | The choices with a value that have a matching id attribute value on a <path> or <g> element in the SVG image are selectable in the presented image | ||
map | Displays choices on map as locations | ✕ | ✔ | select_multiple not supported. | ||
text | numbers | Show the number keyboard on the device | ✔ | ✔ | Enketo: not all browsers provide support | |
multiline | Creates a larger text entry field | ✔ | ✕ | |||
url | Shows button to launch a website to stored URL | ✔ | ✔ | |||
printer | Interface with an external (Zebra barcode) printer | ✕ | ✔ | |||
thousands-sep | When used in conjunction with “numbers” this adds a localized thousands separator for numbers shown on screen (not in submission). | ✕ | ✔ | |||
integer | ||||||
decimal | ||||||
bearing | Shows compass/bearing widget | ✕ | ✔ | |||
integer and decimal | ||||||
thousands-sep | Adds a localized thousands separator on screen (not in submission). | ✕ | ✔ | |||
range | ||||||
vertical | Shows a vertical range slider instead of horizontal | ✔ | ✔ | |||
no-ticks | Hides the ticks in a range widget slider | ✔ | ✔ | |||
rating | Displays range as stars | ✕ | ✔ | |||
picker | Shows range options in a picker instead of a slider | ✕ | ✔ | |||
distress | Shows a thermometer surrounding a range slider | ✔ | ✕ | For backwards compatiblity this is also supported on integer types (with harcoded range of 0-10 with step 1). It is no longer recommend to use integer. | ||
date | ||||||
month-year | Together with ‘date’ question type, doesn’t display the day of the month. | ✔ | ✔ | Enketo: not all browsers provide support | ||
year | Together with ‘date’ question type, only displays the year. | ✔ | ✔ | On Enketo only works on desktop devices - mobile devices use native full date picker | ||
date and dateTime | ||||||
no-calendar | allows to force older spinner-only display on newer 4.x devices | ✕ | ✔ | |||
ethiopian | Displays pickers for the Ethiopian calendar. | ✕ | ✔ | |||
islamic | Displays pickers for the Ethiopian calendar. | ✕ | ✔ | |||
coptic | Displays pickers for the Ethiopian calendar. | ✕ | ✔ | |||
image | ||||||
new | Capture new photo with default camera. Can be combined with annotate. | ✔ | ✔ | Enketo: not all browsers provide support | ||
new-front | Capture new photo with font-camera (selfie). Can be combined with annotate. | ✔ | ✔ | Enketo: not all browsers provide support | ||
new-rear | Capture new photo with rear-camera. Can be combined with annotate. | ✔ | ✔ | Enketo: not all browsers provide support | ||
annotate | Draw on a captured Image | ✔ | ✔ | |||
draw | Draw something on the screen | ✔ | ✔ | |||
signature | Draw a signature on a line | ✔ | ✔ | |||
audio, video | ||||||
new | Capture new audio or video with the default camera/mic | ✔ | ✔ | Enketo: not all browsers provide support | ||
geopoint, geotrace, geoshape | ||||||
maps | Records the GPS coordinates of the current location while showing it also in Google Maps | ✔ | ✔ | Enketo: Adds a button on touch screens to see a map; for non-touch devices it’s the same as having no appearance. | ||
hide-input | Shows a larger map and hides the geo input fields by default. | ✔ | ✕ | |||
streets, terrain, satellite, [other] | Switches the default map layer to the one with the name of the appearance. | ✔ | ✕ | |||
placement-map | Allows user to point at a location on a map to record those GPS coordinates | ✔ | ✔ | Enketo: Same as maps |
choices
The choices sheet is optional and only required if there are any select_one or select_multiple questions in the file.
Item | Description | Enketo? | Collect? | Synonyms | Notes |
---|---|---|---|---|---|
list name | A unique name for each set of choices | ✔ | ✔ | list_name | |
name | ID (name) of the specific choice, will be saved to XML | ✔ | ✔ | ||
label::[language] | Choice label, will be displayed on screen. Allows adding a translation of choice labels, showing [language] in the interface | ✔ | ✔ | label::[language] | |
media | ✔ | ✔ | optional | ||
[filter_category_name] | Allows setting a specific parent category for choice filters (cascading questions) | ✔ | ✔ | Column name is specified by user, e.g. ‘country’ | |
geometry | Special column name used by the `map` appearance | ✕ | ✔ |
settings
The settings sheet and all of its items are optional.
Item | Description | Enketo? | Collect? | Synonyms | Notes |
---|---|---|---|---|---|
form_title | Title displayed at beginning of form, in form list | ✔ | ✔ | if missing assigned to form_id | |
form_id | ID used in the XML and often needs to be unique | ✔ | ✔ | If missing assigned to xls name | |
public_key | Key required for encrypted forms | ✔ | ✔ | ||
submission_url | Specific URL for uploading data, overrides default | ✕ | ✔ | ||
default_language | If form uses multiple languages, this one sets which to use by default | ✔ | ✔ | ||
style | Separate questions groups into pages (on Enketo). Switch to a different theme. | ✔ | ✕ | Allowed values: pages, theme-grid, theme-formhub | |
version | ✔ | ✔ | |||
instance_name | Allows user to create a dynamic naming convention for each submitted instance | ✔ | ✔ | for example, concat(${lname}, ‘-‘, ${fname}, ‘-‘, uuid()) |