HD DCD XLSForm Reference Table

Last updated: 2023-02-24 06:56

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: surveychoices, and settings.

survey

This sheet is mandatory in all XLSForms.

CategoryItemDescriptionEnketo?Collect?SynonymsNotes
Column headers
typeSets the question type, see above
nameUnique 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
constraintDefine the allowed values to a response
constraint_message::[language]The message a user is shown if the response was not validconstraint-msg::[language] is optional
requiredWhether a question has to be answered in order for the form to continue/be savedbind::requiredAllowed 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 answeredrequiredMsg::[language] is optional
defaultA default value that is pre-filled before the user gets to the question
relevantSkip logic condition (the relevant condition that needs to be fulfilled in order for the present question to be displayed)
read_onlyWhether a question response can be editedAllowed values: yes, no, TRUE, FALSE, true(), false(); or a statement that evaluates as true or false
calculationOnly relevant for calculate questions: a mathematical expression that can be referenced elsewhere
repeat_countNumber of repeats for a repeat grouprepeat-count
imageAn image to be shown with a question
audioAudio to be included with a question
videoA video to be included with a question
image::languagemedia::image::language::[language] is optional
audio::languagemedia::audio::language::[language] is optional
video::languagemedia::video::language::[language] is optional
appearanceDefines the way questions are displayed (widgets), see below
instance::attributeinclude custom XML content for the data instancedependsdepends
bind::attributeinclude custom XML content for the bind attributedependsdepends
body::attributeinclude custom XML content in the bodydependsdepends
body::accuracyThresholdset the minimum GPS accuracy level before automatically registering the coordinates
parametersavailable settings for some question types
QuestionsThese are put into the ‘type’ column
Meta questionsThese are hidden to the user, but otherwise work like regular questions
startRecord when the form was loaded
endRecord when the form was finished
todayRecord the date the form was loaded
deviceidGet the device ID (for Android devices)imeiEnketo will generate a unique ID for a browser-device combo.
usernameGet the user name (set in ODK settings)
subscriberid
simserial
phonenumberphone_numberTBC: phone_number
emailAdd user email to submission (if used)??
auditRecord enumerator behavioroptional 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 choicesselect one
select_multiple [choices] [or_other]User can choose one or more of several choicesselect multiple
select_one_from_file [file]User can choose one of several choices from an external fileOptional 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 fileOptional 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
textUser can enter a text response
integerUser can enter an integer
decimalUser can enter a decimal number
dateUser can enter a date
timeUser can enter a time of day
datetimeUser can enter date and time together
geopointUser can record a GPS locationlocation
imageUser can take or attach a picturephoto
audioUser can record or attach audioCollect accepts an optional quality parameter with possible values voice-only, low, normal and external
background-audioAudio is recorded in the background while filling the formoptional quality parameter with possible values voice-only, low and normal
videoUser can record or attach video
fileUser can attach file of any type
noteUser is shown a note (no response possible)
barcodeUser can enter a barcode by scanning it
acknowledgeUser is asked to confirm or acknowledge somethingtrigger
calculateA 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)
geotraceUser can record a line or polyline or multiple geo points
geoshapeUser can record a polygon of multiple geo points - the last point is the same as the first point
GroupsGroups contain one or more questions, or other nested groups, which may loop (repeat)
begin_groupSets the beginning of a groupbegin group
end_groupEnds the groupend group
begin_repeatSets the beginning of a repeat group
end_repeatEnds 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-listMultiple questions of a group on a screenNeeds to be applied to a group
table-listShow multiple select1s with a shared label in a field list.Needs to be applied to a group
select_one / select_multiple
minimalSpinner widget - click button to provide a response
labelTable of answers
list-nolabelGoes with label, no label on answer just radios
autocompleteAutocomplete widgetsearchNot supported on select_multiple in Enketo
likertShows question as likert widget
horizontalDisplays choices horizontally and automatically creates neat columns for multiple rows
compactDisplays choices horizontally as compact as possiblehorizontal-compact
compact-nGrid widget with max n columns where n is a number from 1 to 10, e.g. use compact-2 or compact-3
quickAuto advance to next question upon selection
quickcompactDisplays choices horizontally as compact as possible. Auto advance to next question upon selectionquick compact
image-mapWhen 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
mapDisplays choices on map as locationsselect_multiple not supported.
textnumbersShow the number keyboard on the deviceEnketo: not all browsers provide support
multilineCreates a larger text entry field
urlShows button to launch a website to stored URL
printerInterface with an external (Zebra barcode) printer
thousands-sepWhen used in conjunction with “numbers” this adds a localized thousands separator for numbers shown on screen (not in submission).
integer
decimal
bearingShows compass/bearing widget
integer and decimal
thousands-sepAdds a localized thousands separator on screen (not in submission).
range
verticalShows a vertical range slider instead of horizontal
no-ticksHides the ticks in a range widget slider
ratingDisplays range as stars
pickerShows range options in a picker instead of a slider
distressShows a thermometer surrounding a range sliderFor 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-yearTogether with ‘date’ question type, doesn’t display the day of the month.Enketo: not all browsers provide support
yearTogether 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-calendarallows to force older spinner-only display on newer 4.x devices
ethiopianDisplays pickers for the Ethiopian calendar.
islamicDisplays pickers for the Ethiopian calendar.
copticDisplays pickers for the Ethiopian calendar.
image
newCapture new photo with default camera. Can be combined with annotate.Enketo: not all browsers provide support
new-frontCapture new photo with font-camera (selfie). Can be combined with annotate.Enketo: not all browsers provide support
new-rearCapture new photo with rear-camera. Can be combined with annotate.Enketo: not all browsers provide support
annotateDraw on a captured Image
drawDraw something on the screen
signatureDraw a signature on a line
audio, video
newCapture new audio or video with the default camera/micEnketo: not all browsers provide support
geopoint, geotrace, geoshape
mapsRecords the GPS coordinates of the current location while showing it also in Google MapsEnketo: Adds a button on touch screens to see a map; for non-touch devices it’s the same as having no appearance.
hide-inputShows 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-mapAllows user to point at a location on a map to record those GPS coordinatesEnketo: 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.

ItemDescriptionEnketo?Collect?SynonymsNotes
list nameA unique name for each set of choiceslist_name
nameID (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 interfacelabel::[language]
mediaoptional
[filter_category_name]Allows setting a specific parent category for choice filters (cascading questions)Column name is specified by user, e.g. ‘country’
geometrySpecial column name used by the `map` appearance

settings

The settings sheet and all of its items are optional.

ItemDescriptionEnketo?Collect?SynonymsNotes
form_titleTitle displayed at beginning of form, in form listif missing assigned to form_id
form_idID used in the XML and often needs to be uniqueIf missing assigned to xls name
public_keyKey required for encrypted forms
submission_urlSpecific URL for uploading data, overrides default
default_languageIf form uses multiple languages, this one sets which to use by default
styleSeparate questions groups into pages (on Enketo). Switch to a different theme.Allowed values: pages, theme-grid, theme-formhub
version
instance_nameAllows user to create a dynamic naming convention for each submitted instancefor example, concat(${lname}, ‘-‘, ${fname}, ‘-‘, uuid())