HD Data Collection Definition Creation Process
HD Data Collection Definition Creation ProcessThe service healthdata.be uses the XLSForm standard to help simplify the authoring of forms in Excel. Authoring is done in a human readable format using a familiar tool that almost everyone knows - Excel. XLSForms provide a practical standard for sharing and collaborating on authoring forms. They are simple to get started with but allow for the authoring of complex forms by someone familiar with the syntax described in the manual.
HD DCD XLSForm Manual
HD DCD XLSForm Manual- Basic format
- Question types
- Hints
- Formulas
- Constraints
- Relevant
- Calculation
- Trigger
- Required
- Randomize Choices
- Grouping questions
- Repeats
- Multiple language support
- Media
- Pre-loading CSV data
- Dynamic selects from pre-loaded data
- Cascading selects
- External selects
- Default
- Read only
- Appearance
- Settings worksheet
- Styling prompts
- Advanced use and extensibility
- Tools that support XLSForms
- More resources
- History
HD DCD XLSForm Reference Table
HD DCD XLSForm Reference TableThis 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 | ||
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()) |
HD DCD XLSForm Templates
HD DCD XLSForm Templates johanvanbussel Tue, 11/14/2023 - 13:16HD DCD XLSForm Validator
HD DCD XLSForm ValidatorAn online validator is available : ODK - XLSForm Online v2.x
HD DCD XLSForm Resources
HD DCD XLSForm Resourcespyxform
pyxform is a Python library that makes writing forms for EDC applications like ODK Collect and Enketo easy by converting XLSForms (Excel spreadsheets) into ODK XForms. The XLSForms format is used in a number of tools.
XLS(X) documents used as input must follow to the XLSForm standard and the resulting output follows the ODK XForms standard. pyxform is a major rewrite of xls2xform.
HD DCD XLSForm Video Tutorials
HD DCD XLSForm Video TutorialsIntroduction to XLSForms - Form Structure (By Open Data Kit - ODK)
Introduction to XLSForms - XLSForms Question Types (By Open Data Kit - ODK)
Introduction to XLSForms - Examples of XLSForm Question Types (By Open Data Kit - ODK)
Introduction to XLSForms - XLSForms Form Logic (By Open Data Kit - ODK)
Introduction to XLSForms - Examples of XLSForm Form Logic (By Open Data Kit - ODK)
How to Use the Search Function in XLSForm (By Humanitarian Data Solutions)
How to Create Repeating Questions in XLSFORM (By Humanitarian Data Solutions)
How to Use Groups & Skip-Logic in XLSForm (By Humanitarian Data Solutions)
Use Search and Autocomplete Together in XLSForm (By Humanitarian Data Solutions)
XLSForm Constraint to Prevent Selecting "None of the Above" and another option (By Humanitarian Data Solutions)
How to Set up a Cascade Select question in XLSForm (By Humanitarian Data Solutions)
XLSForm Tutorial on "Relevant": Ask a follow up question if number is too high (By Humanitarian Data Solutions)
Tutorial on "Relevant": Only show a question if previous answer is more than 0 (By Humanitarian Data Solutions)
XLSForm Tutorial on Constraints: Make sure answer is less than previous answer (By Humanitarian Data Solutions)
XLSForm Tutorial on Constraints: Make sure answer is greater than 0 (By Humanitarian Data Solutions)
4 AWESOME Ways to Use Choice-Filter in your XLSForm (By Humanitarian Data Solutions)
HD DCD XLSForm Academic Courses
HD DCD XLSForm Academic Courses- Collecter des données d'enquête sur tablette et smartphone (l’Institut de statistique, l’UCLouvain)