XLS Forms¶
XLS Form is a standard form created to simplify the authoring of forms in Excel in a readable format. They are simple to get started with but also allow for complex XForms by someone familiar with the syntax. You need to understand how XLS Forms work, in order to create a form that can be used by the form management module. This manual covers the very basics of XLS Forms, for further information, visit http://xlsform.org/.
Survey sheet¶
This worksheet gives the form its overall structure and contains most of the content of the form. It contains the full list of questions and information about how they should appear in the form. Each row usually represents one question; however, there are certain other features described below that one can add to the form which enables the user to incorporate complex questions (tables, ranking questions).
The survey worksheet has 3 mandatory columns: type, name, and label. The type column specifies the type of entry you are adding. The name column specifies the unique variable name for that entry. No two entries can have the same name. The label column contains the actual text you see in the XLSForm.
Choices sheet¶
This worksheet is used to specify the choices for multiple choice questions. Each row represents an answer choice. Answer choices with the same list name are considered part of a related set of choices and will appear together for a question. This also allows a set of choices to be reused for multiple questions (for example, yes/no questions).
The choices worksheet has 3 mandatory columns: list name, name, and label. The list name column lets you group together a set of related answer choices, i.e., answer choices that should appear together under a question. The name column specifies the unique variable name for that answer choice. The label column shows the answer choice exactly as one want it to appear on the form. This choices sheet corresponds to the survey sheet mentioned above.
Keep in mind that the syntax used must be precise. For example, if you write Choices or choice instead of choices, the form won’t work.
Setting sheet¶
This worksheet allows one to further customize the form. An example of settings worksheet is below. The column headings in this example settings worksheet do the following:
- form_title - the title of the form that is shown to users. The form title is pulled from form_id if form_title is blank or missing.
- form_id - the name used to identify the form submission. The form id is pulled from the XLS file name if form_id is blank or missing.
- is_moderated – if yes, submissions made on this form will undergo a review process (data handler) prior to being committed to the database. If no, submissions will bypass the review process and be directly loaded in the database.
- db_table_name – the name of the database table that will automatically be generated by the system when the form is published by the administrator for the first time.
- db_name – this is the name of the existing database in which the above table will be created. To be provided by the database administrator
- db_schema_name – only used for PostgresSQL database. Default must be set to data
- use_app_label – used in labelling of tables. Must always be set to no.
Question types¶
XLS Form supports different data types that can be used to to develop a form for capturing data. Below are a few simple question types. These questions are used in the survey sheet of the XLS Form.
| integer | Integer (i.e., whole number) input. |
|---|---|
| decimal | Decimal input. |
| text | Free text response. |
| string | Under this input words, numbers, decimals all are allowed. |
| select_one [options] | Multiple choice question; only one answer can be selected. |
| select_multiple [options] | Multiple choice question; multiple answers can be selected. |
| note | Display a note on the screen, takes no input. |
| date | Date input. |
| time | Time input. |
| today | Automatically captures date and time of the day of survey from android. |
Numbers¶
Use the “Integer” type when the response to the question is a whole number i.e. 1,2,3 etc. Use the “Decimal” type for decimal numbers like 1,2. Use the “String” type if the response is both decimal and integer.
Multiple choice questions¶
The following multiple-choice questions are supported:
- select_one – provide a list of choices but you can select only one answer
- select_multiple – provide a list of choices but you can select multiple answers
With this type of question you need to specify the available options for that particular multiple choice question in the choices worksheet.
Here is an example of a select_one question:
Notes that “culvert_defect” in the survey sheet must match the “culvert_defect” in the list name column of the choices worksheet i.e. options written after select_one under survey sheet and list name under choices sheet both must be same. This ensures that the form displays the correct list of answer choices for a particular question.
Display of a note¶
Use the “note” type if you would like to display text to the user and don’t need a response.
Grouping questions¶
If multiple questions are related to one particular category, then you can add them to a group, for example:
Make sure that each group has a “begin group” and “end group” statement.