HD DCD Reference Table

Last updated: 2023-02-24 06:50

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