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
email 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())