HD DCD XLSForm Reference Table

Last updated: 2025-10-07 14:44

This page is a work-in-progress reference for all available functions in XLS Forms used by healthdata.be to create Data Collection Definitions. It is divided into the three possible sheets: survey, choices, and settings.

survey

This sheet is mandatory in all XLSForms.

Category	Item	Description	Synonyms	Notes

Column headers
	type	Sets the question type, see manual.
	name	Unique variable name
	label::[language]	Label visible in the form. Currently English, French and Dutch are supported.
	hint::[language]	Providing a help text description.
	guidance_hint::[language]	Providing a help text tooltip.
	constraint	Specifying additional validations on the provided data.
	constraint_message::[language]	The message a user is shown if the response was not valid
	required	Whether a variable is mandatory to be provided.
	required_message::[language]]	Allows to customize the error message if required question is not answered
	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
	calculation	For specific calculations.
	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
	bind::attribute	include custom XML content for the bind attribute
	body::attribute	include custom XML content in the body
	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?	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())