docs.healthdata.beHD DCD XLSForm Overview
Dernière mise à jour: 2025-10-07 15:06
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 below. | |||
| 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. | |||
| appearance | Includes variable specifics. | |||
| Supported question types | ||||
| select_one [choices] [or_other] | User can choose one of several choices | |||
| select_multiple [choices] [or_other] | User can choose one or more of several choices | |||
| select_one_from_file [file] | User can choose one of several choices from an external file | |||
| select_multiple_from_file [file] | User can choose one or more of several choices from an external file | |||
| 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 | |||
| note | User is shown a note (no response possible) | |||
| Groups | Groups contain one or more questions, or other nested groups, which may loop (repeat) | |||
| begin_group | Sets the beginning of a group | |||
| end_group | Ends the 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 |
choices
The choices sheet is optional and only required if there are any select_one or select_multiple questions in the file.
| Item | Description | 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 | 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()) |