+ Note: This article focuses on setting question appearances in XLSForm. To learn about setting appearances in the KoboToolbox Formbuilder, see Using the Formbuilder documentation.
+
+For hands-on practice with question appearances in XLSForm, see KoboToolbox Academy's XLSForm Fundamentals Course.
+
+ Note: Appearances for select_one and select_multiple questions can also be used for select from file questions.
+
+Note: This article focuses on adding calculations in XLSForm. To learn about adding calculations in the KoboToolbox Formbuilder, see Calculate question type.
+
+For hands-on practice with calculations in XLSForm, see KoboToolbox Academy’s XLSForm Fundamentals Course.
+
+ For a comprehensive list of functions available in XLSForm, see Using functions in XLSForm. To learn more about regular expressions, see Restricting text responses with regular expressions. +
+ +Examples of more advanced calculations include: + +| Calculation | Description | +|:-------------|:-------------| +| `int((today()-${DOB}) div 365.25)` | Calculate age from date of birth. | +| `int(today()-${date})` | Calculate days since a date. | +| `format-date(${date}, '%b')` | Return just the month from a date. | +| `concat(${first}, " ", ${middle}, " ", ${last})` | Create a single string with a respondent’s full name. | +| `jr:choice-name(${question1}, '${question1}')` | Return a choice’s label, in the current language, from the choice list. | +| `translate(${full_name}, "ABCDEFGHIJKLMNOPQRSTUVWXYZ ", "abcdefghijklmnopqrstuvwxyz_")` | Convert uppercase letters to lowercase and spaces to underscores. | +| `substr(${question}, 1, 2)` | Keep only the 1st letter or number in a string. | +| `int(random()*10)` | Generate a random number between 0 and 10. | +| `selected-at(${gps}, 0)` | Isolate latitude from GPS coordinates. | +| `selected-at(${gps}, 1)` | Isolate longitude from GPS coordinates. | +| `if(regex(${id}, '^ML-'), 'yes', 'no')` | Create a binary variable that takes `yes` if the respondent ID starts with “ML-”. | + +### Setting dynamic default responses + +The `calculation` field can also be used to set **dynamic default responses.** Dynamic default responses allow you to display a default response inside a question based on a previous response. + +To set a dynamic default response: +1. In the `calculation` column, enter the **reference to the question** that will dynamically populate the default response. +2. In the `trigger` column, enter the question that will activate the calculation. + - Typically, this would be the same question referenced in the `calculation` column, so that any change to the trigger question will also update the default response. + +**survey worksheet** + +| type | name | label | calculation | trigger | +|:------|:-----------|:--------------------------|:-------------|:-------------| +| text | hh_name | Name of the head of household | | | +| text | phone | Household phone number | | | +| text | phone_name | Name of the phone owner | ${hh_name} | ${hh_name} | +| survey | + +
+Note: If you want to prevent users from editing the field, set the read_only column to TRUE.
+
coalesce() or if() functions. For example:
+ coalesce(${potentially_empty_value}, 0)if(${potentially_empty_value}="", 0, ${potentially_empty_value})default column.
+random() or now(), as their values may change under these conditions.
+once() to ensure the expression is only evaluated once (e.g., once(random()) or once(today())).
+
+Note: This article focuses on adding choice filters in XLSForm. To learn about adding cascading select questions in the KoboToolbox Formbuilder, see Adding cascading select questions in the Formbuilder.
+
+For hands-on practice with choice filters in XLSForm, see KoboToolbox Academy’s XLSForm Fundamentals Course.
+
+For an example of an XLSForm using dynamic choice filters, see this sample form. +
+ +To add dynamic choice filters in XLSForm: +1. Add the **parent** and **child question** to your XLSForm and [define their option choices](https://support.kobotoolbox.org/option_choices_xls.html) in the `choices` worksheet. + - These must be `select_one` or `select_multiple` questions. +2. In the `choices` worksheet, add a filter column. + - It can be helpful to name this column the same as the **parent question.** +3. In the filter column, enter the **name of the choice** from the parent list that each option in the child list corresponds to. +4. In the `survey` worksheet, add a **choice_filter** column. This column will contain the **choice filter expression** used to filter the option choices. + - If the parent question is `select_one`, the choice filter expression will be `filter_column = ${question_name}`, where `question_name` refers to the parent question. + - If the parent question is `select_multiple`, the choice filter expression will be `selected(${question_name}, filter_column)`. + +When a respondent selects an option in the parent question, the choice list for the child question will be filtered to only include the corresponding choices. + +### Example + +In the example below, `continent` is the **parent question** and `country` is the **child question.** The choice list for the `country` question will be filtered based on the response to the `continent` question. + +**survey worksheet** + +| type | name | label | choice_filter | +|:------------------|:---------|:----------|:--------------------| +| select_one continent | continent | Continent | | +| select_one country | country | Country | **continent = ${continent}** | +| survey | + +**choices worksheet** + +| list_name | name | label | continent | +|:-----------|:---------|:--------|:----------| +| continent | africa | Africa | | +| continent | asia | Asia | | +| country | malawi | Malawi | africa | +| country | zambia | Zambia | africa | +| country | india | India | asia | +| country | pakistan | Pakistan| asia | +| choices | + +## Advanced choice filters in XLSForm + +You can create more advanced choice filters by using logical operators, mathematical operators, functions, and regex in your choice filter expressions. This allows for highly customized and precise filtering of options, tailoring the form to specific data collection requirements and respondent characteristics. + +
+Note: In advanced choice filter expressions, the name column of the choices worksheet can be used as a filter column.
+
+ To learn more about building form logic expressions in XLSForm, see Introduction to form logic in XLSForm. +
+ +### Example +In the example below, the underlying choice list for `Q1` and `Q2` is the same, but only the options selected in `Q1` will be displayed to respondents when answering `Q2`. + +**survey worksheet** + +| type | name | label | choice_filter | +|:------------------|:-----|:--------------------------------------------------|:-------------------------| +| select_multiple item | Q1 | Which household items do you currently own? | | +| select_multiple item | Q2 | Which of these items would you consider upgrading in the future? | selected(${Q1}, name) | +| survey | + +**choices worksheet** + +| list_name | name | label | +|:----------|:----------|:----------------| +| item | fridge | Refrigerator | +| item | tv | Television | +| item | fan | Ceiling fan | +| item | microwave | Microwave oven | +| item | radio | Radio | +| item | bike | Bicycle | +| item | phone | Mobile phone | +| item | laptop | Laptop computer | +| choices | + +In the resulting form, `Q2` will display only the options chosen in `Q1`, as shown below. + + + +## Troubleshooting + +settings worksheet by setting allow_choice_duplicates to yes.
++ To learn more about form logic in XLSForm, see Introduction to form logic in XLSForm. +
+ +This article covers the following topics: +- Adding constraints to questions in XLSForm +- Combining multiple constraint conditions +- Customizing constraint error messages +- Advanced constraints in XLSForm + +
+ Note: This article focuses on adding constraints in XLSForm. To learn about adding constraints in the KoboToolbox Formbuilder, see Adding validation criteria in the Formbuilder.
+
+For hands-on practice with adding constraints in XLSForm, see KoboToolbox Academy’s XLSForm Fundamentals Course.
+
+ To learn more about building form logic expressions in XLSForm, see Introduction to form logic in XLSForm. +
+ +## Combining multiple constraint conditions +Multiple constraint conditions can be combined into a single expression to determine whether a response is valid. Conditions can be combined using **and**, **or**, and **not** logical operators: + +- Use **and** when all conditions must be met for a response to be valid. + - For example:. > 18 and . < 65
+- Use **or** when at least one condition must be met for a response to be valid.
+ - For example: . < 18 or ${student} = 'yes'
+- Use **not** to indicate that a condition or set of conditions must not be met (e.g., when two conditions cannot be true together for a response to be valid).
+ - For example: not(. < 18 and ${household_head} = 'yes')
+
+**survey worksheet**
+
+| type | name | label | hint | constraint |
+|:---------|:-------|:------------------|:--------------------------------------------|:---------------------------------------------------------|
+| integer | age | What is your age? | Must be less than 18 or above 65 to participate | . < 18 or . > 65 |
+| integer | weight | How much do you weigh? | Must be between 30 and 200 kg | . >= 30 and . <= 200 |
+| survey |
+
+
+## Customizing constraint error messages
+
+By default, when a response value in the form does not meet the constraint condition, a “Value not allowed” error message appears. It is recommended to customize this message to inform users why the value is invalid, allowing them to correct their input.
+
+To customize the constraint error message:
+1. Add a **constraint_message** column to the `survey` worksheet.
+2. In the `constraint_message` column, enter the text you wish to display as the error message when the constraint conditions are not met.
+
+**survey worksheet**
+
+| type | name | label | constraint | constraint_message |
+|:--------|:-----|:----------------|:-----------|:----------------------|
+| integer | age | What is your age? | . >= 18 | Must be older than 18. |
+
+## Advanced constraints in XLSForm
+
+Beyond basic constraints, you can customize conditions to ensure data quality and adapt to many data collection scenarios. To build more advanced constraint conditions in XLSForm:
+
+- Use parentheses to combine more than two conditions
+- Use [functions](https://support.kobotoolbox.org/functions_xls.html) for increased flexibility
+- Use [regular expressions](https://support.kobotoolbox.org/restrict_responses.html) to restrict text responses
+
+Examples of more advanced validation criteria include:
+
+| Criteria | Description |
+|:---------|:------------|
+| (. >= 18 and . < 130) or (. = 999) | The response must be between 17 and 130 or be equal to 999 (often used for non-response) |
+| not(${in_university} = 'yes' and . < 16) | If the answer to `in_university` is ‘yes’, the current response must be greater than 16. |
+| not(selected(., 'none') and count-selected(.)>1) | The ‘none’ option cannot be selected if any other response in a `select_multiple` question is selected. |
+| . < today() | The date entered must be before today’s date. |
+| regex(., '^\d{2}$') | The input is restricted to two numbers (using regular expressions). |
+
+
diff --git a/source/edit_forms_excel.md b/source/edit_forms_excel.md
index f69d316d8..55babf666 100644
--- a/source/edit_forms_excel.md
+++ b/source/edit_forms_excel.md
@@ -1,19 +1,72 @@
-# Editing Forms in Excel using XLSForm
-**Last updated:** 15 Feb 2022
+# Introduction to XLSForm
+KoboToolbox relies on [XLSForm](http://xlsform.org/en/), a standard for designing electronic forms in Excel or other spreadsheet programs. XLSForm makes it easier to manage complex forms, such as those with long choice lists or multiple translations. While the [KoboToolbox Formbuilder](https://support.kobotoolbox.org/formbuilder.html) offers an intuitive, user-friendly interface, XLSForm is recommended when working with advanced functionalities or complex forms.
-KoboToolbox is building its forms using a widely shared standard called
-[XLSForm](http://xlsform.org/en/). XLSForm makes it possible to create very
-complex electronic forms in Excel (or any other spreadsheet program).
+All forms in KoboToolbox are fully compatible with XLSForm. This means you can easily import and export your forms across KoboToolbox and other data collection platforms. XLSForm provides a standardized format for form development using common spreadsheet software, making it a practical option for collaboration and sharing.
-All forms created with KoboToolbox can be imported from or exported to XLSForm
-files. This means they are fully compatible with other related tools such as
-[ODK](https://opendatakit.org) or [Formhub](https://formhub.org).
+This article covers the following topics:
-Editing a form in Excel can be an easy way to quickly make several changes to a
-form (for example for translating an entire form).
+- Benefits of using XLSForm for form development
+- Overview of using XLSForm with KoboToolbox
+- Additional resources for learning XLSForm
-The XLSForm format is wonderfully documented [here](http://xlsform.org/en/).
+
+
+
+ This article provides an introduction to XLSForm. To get started with building XLSForms, see Getting started with XLSForm.
+
+ For hands-on practice with form development using XLSForm, see KoboToolbox Academy’s online XLSForm Fundamentals Course.
+
+ For more information, see Using XLSForm with KoboToolbox. +
+ +## Additional XLSForm resources + +Numerous resources are available to help learn XLSForm and troubleshoot issues. + +KoboToolbox offers the following resources: + +- [KoboToolbox Help Center](https://support.kobotoolbox.org): An extensive documentation library with support articles about KoboToolbox and XLSForm. +- [KoboToolbox XLSForm Fundamentals Course](https://academy.kobotoolbox.org/courses/xlsform-fundamentals): An online course developed by our team of experts, which covers a range of skills including creating an XLSForm from scratch, using form logic and calculations, and testing and deploying forms for data collection with KoboToolbox. +- [KoboToolbox Community Forum](https://community.kobotoolbox.org): A space to connect with our global user community, to get help with custom form building or troubleshooting, and to share KoboToolbox resources. + +External resources include: + +- [XLSForm documentation](https://xlsform.org/en/): An extensive documentation website dedicated to XLSForm. +- [XLSForm Reference and Template](https://xlsform.org/en/ref-table/): A detailed resource for creating and styling forms, including question types, appearances, and optional columns. +- [ODK documentation](https://docs.getodk.org/form-reference/): Another extensive documentation website dedicated to XLSForm. -When using XLSForm, you can create complex questions and forms, which are -introduced in this site. diff --git a/source/form_logic_xls.md b/source/form_logic_xls.md new file mode 100644 index 000000000..affddfad9 --- /dev/null +++ b/source/form_logic_xls.md @@ -0,0 +1,101 @@ +# Introduction to form logic in XLSForm + +Form logic controls the flow and behavior of your form based on responses to previous questions. It allows you to create dynamic forms that adapt to user input. For example, you can use form logic to display specific questions only when relevant, validate responses, or perform calculations automatically. + +Key types of form logic include: +- **Skip logic:** Controls when questions are shown or hidden based on previous responses. +- **Constraints:** Validate responses to ensure they meet defined rules or criteria. +- **Choice filters:** Display only relevant answer options based on earlier responses. +- **Calculations:** Automatically generate values using mathematical or logical expressions. +- **Required logic:** Defines when a question must be answered. + +Form logic is built using **expressions**, which combine **question references**, **operators**, **functions**, and **constants**. The expression evaluates as TRUE or FALSE to control the form's behavior. + ++ This article introduces the basic components of form logic in XLSForm, including question referencing, operators, and functions. To learn more about each type of form logic, see support articles on skip logic, required logic, constraints, choice filters, and calculations in XLSForm. +
+ +## Question referencing + +Question referencing allows you to incorporate the answer to a previous question into the label or logic of a subsequent question. Question referencing is frequently used in advanced forms: + +- **In question labels or hints:** For example, you can include a respondent’s child’s name in later questions about their child. +- **In form logic:** For example, you can show or hide a question based on a previous response, or validate an answer by comparing it with an earlier one. + +Question referencing uses the format **${question_name}**, where `question_name` is replaced with the unique name of the referenced question. + +If a question reference includes a spelling error or is otherwise incorrect, an error message will appear when previewing or submitting the form. + +
+ Note: When referencing a question within its own logic (i.e., in its own row), a period . can be used as a shortcut.
+
+For a comprehensive list of functions in XLSForm, see Using functions in XLSForm. +
+ +## Regex + +A regular expression (regex) is a search pattern used to match specific characters within a string. It is widely used to validate, search, extract, and restrict text in most programming languages, including in KoboToolbox. + +Regex can be used in **constraints** to control the length and characters entered into a question (e.g., limiting phone number entry to exactly 10 digits, controlling the format of ID numbers, or verifying valid email entry). It can also be used in **calculations** and other form logic. + +In KoboToolbox, regular expressions are evaluated using the function `regex(., ' ')`, where the regex is entered between apostrophes and the period `.` represents the current question. `regex(., ' ')` returns TRUE if the regular expression is met, and FALSE otherwise. + ++ To learn more about using regex in KoboToolbox, see Restricting text responses with regular expressions. +
+ + + + diff --git a/source/form_settings_xls.md b/source/form_settings_xls.md new file mode 100644 index 000000000..dd7080ab1 --- /dev/null +++ b/source/form_settings_xls.md @@ -0,0 +1,38 @@ +# Form settings in XLSForm + +XLSForm allows you to configure settings for your forms using the `settings` worksheet. For example, you can specify a form title, set a default language, or track version numbers. + +This article covers how to add and utilize the available form settings in XLSForm. + ++Note: This article focuses on form settings forms in XLSForm. To learn about configuring form settings in the KoboToolbox Formbuilder, see Form settings and metadata. +
+ +## Adding form settings in XLSForm + +To add form settings in XLSForm: +1. Add a `settings` worksheet to your XLSForm. +2. Create a new column for each setting, using the exact column name shown [in the table below](https://support.kobotoolbox.org/form_settings_xls.html#available-form-settings-in-xlsform). +3. Under each setting, specify the relevant value (see example below). + +**settings worksheet** + +| form_title | version | default_language | style | +|:----------------------|:--------|:----------------|:------| +| Form settings in XLSForm | v3 | English (en) | pages | +| settings | + +## Available form settings in XLSForm + +Available form settings in XLSForm include: + +| Form setting | Description | +|:----------------------------|:------------| +|form_title | Specifies the title of the form that is shown to users. This can also be set and managed in KoboToolbox when the form is uploaded. |
+| version | Includes a string that represents the current version of the XLSForm (e.g., v1 or YYYYMMDD). Useful for tracking form versions for collaboration. |
+| instance_name | Specifies a unique name for each form submission using fields filled in by the user during the survey. Appears in the data table for each submission. Can be used to create custom participant or submission IDs.concat(${lname}, '-', ${fname}, '-', today()) returns lastname-firstname-date. |
+| default_language | Sets the default language in translated forms. The language (code) format is used, as defined in the IANA language registry website. |
+| style | Specifies an alternative theme for Enketo web forms. |
+| allow_choice_duplicates | Allows an XLSForm to reuse duplicated option names within a choice list (e.g., when using choice filters where choice names are duplicated). |
+| public_key | Specifies the public key for encryption-enabled forms. |
+
diff --git a/source/form_style_xls.md b/source/form_style_xls.md
new file mode 100644
index 000000000..08df77559
--- /dev/null
+++ b/source/form_style_xls.md
@@ -0,0 +1,91 @@
+# Styling your forms using XLSForm
+
+With KoboToolbox, you can customize the appearance of your forms and questions to highlight key information and adapt the layout to your data collection needs. This includes applying themes to Enketo web forms, adding headers and lists in note questions, and using color or bold formatting for emphasis.
+
+This article covers themes for Enketo web forms as well as styling options for notes and questions within a form.
+
++Note: This article focuses on styling forms in XLSForm. To learn about setting Enketo themes in the KoboToolbox Formbuilder, see Using alternative Enketo web form styles. +
+ +## Themes for Enketo web forms + +Enketo themes allow you to customize the appearance and layout of [Enketo web forms](https://support.kobotoolbox.org/enketo.html). Themes apply only to Enketo web forms and are not visible in KoboCollect. + +### Adding themes in XLSForm + +To add a theme in XLSForm: +1. Add a **style** column in your `settings` worksheet. +2. Specify the theme you want to use, using the exact name shown in the table below. + +**settings worksheet** + +| style | +|:------------| +| theme-grid | +| settings | + +
+Note: Themes can be combined by entering both themes in the same cell of the style column, separated by a space (e.g., theme-grid pages).
+
pages | Displays one question per screen or a group of questions together on the same screen, similar to the KoboCollect layout. |  |
+| theme-grid | An alternative display that is more compact, similar to paper forms, and efficiently uses space, arranging multiple questions per row. Questions are capitalized by default. Requires setting up your XLSForm. |  |
+| theme-grid no-text-transform | Same as theme-grid, but without automatic capitalization of questions. |  |
+
+### Setting up an XLSForm for theme_grid
+
+In Enketo web forms, the `theme_grid` layout allows you to display questions in multiple columns, making your form more compact and visually organized. The set-up of these columns, including how many there are and how wide each one should be, is controlled by assigning `w-values` to each question inside the **appearance** column of your XLSForm.
+
+
+ For a comprehensive overview of using theme_grid in XLSForm, see this Grid Theme Tutorial and sample XLSForm.
+
+Note: Apply w-values only to top-level groups or repeats. Although applying them to nested groups or repeats is supported, it may not display well.
+
+Note: Some styling features may not be supported in KoboCollect or Enketo. It is recommended to preview your forms in your chosen data collection method to confirm that all styling features are fully supported. +
+ +Text styling features in XLSForm include: +| Feature | Formatting | +|:---------------|:-----------| +| Italics | `*italics*` or `_italics_` | +| Bold | `**bold**` or `__bold__` | +| Hyperlink | `[name of link](url)` | +| Headers | `# Header 1` (biggest) to `###### Header 6` (smallest) | +| Bullet lists | - This is an unordered listCentered label
` centers the text on the screen | + +
+Note: Use the \ character before #, *, _, and \ to prevent special styling effects from being triggered by these characters.
+
+ To learn more about form logic in XLSForm, see Introduction to form logic in XLSForm. To learn about functions specifically used in repeat groups, see Repeat groups in XLSForm. +
+ +## Commonly used functions in XLSForm + +The following functions are some of the most frequently used in XLSForm. They help control form behavior, manage responses, and perform basic calculations or logical operations across questions. These functions can be applied in calculations, constraints, relevance conditions, and other expressions throughout your form. + +| Function | Description | +|:-----------|:-------------| +| `if(expression, then, else)` | If the expression is TRUE, returns `then`. If not, returns `else`. | +| `selected(${question_name}, option_name)` | Used to determine if a specific choice was selected in a `select_multiple` question. | +| `random()` | Returns a random number between 0.0 (inclusive) and 1.0 (exclusive). | +| `count-selected(${question_name})` | Returns the number of options selected in a `select_multiple` question. | +| `coalesce(${question1}, ${question2})` | Returns the first non-empty value of the two arguments. Returns an empty string if both are empty or non-existent. | +| `jr:choice-name(choice_name, '${question_name}')` | Returns the label value, in the active language, associated with the `choice_name` in the list of choices for a select type question. To retrieve the label of whichever response was selected, use `jr:choice-name(${question_name}, '${question_name}')`. | +| `selected-at(${question_name}, n)` | Returns a selected choice in a `select_multiple` question at the nth position. For example, `selected-at(${question_name}, 2)` returns the second choice selected in a `select_multiple` question. | +| `once(expression)` | Evaluates an expression only once (e.g., to ensure a random number is only generated once, or to store the first value entered for a question even if the response is changed later). | +| `instance('list_name')/root/item[name = ${question}]/column_name` | Retrieves a value from the choices sheet. Searches the choice list named `list_name`, finds the row where the choice `name` matches the response to `${question}`, and returns the value from the column specified as `column_name`. | + +## Functions to manipulate numbers + +The following functions are used to perform mathematical operations or transform numeric values in XLSForm. They can help you calculate, round, or convert numbers, as well as apply more advanced mathematical expressions when needed. + +| Function | Description | +|:---------|:------------| +| `int(number)` | Transforms a decimal number into an integer without rounding. | +| `round(number, places)` | Rounds a decimal value to a predetermined number of decimal places. | +| `pow(number, power)` | Calculates the power of a number. | +| `number(x)` | Converts x (a string or boolean expression) to a number value. | +| `log(number)`+ Note: Inside these functions, either constants or question references can be included. +
+ +## Functions to manipulate strings + +The following functions are used to create, modify, or analyze text strings in XLSForm. They are useful for combining text, checking for specific patterns or characters, and cleaning or formatting text inputs. + +| Function | Description | +|:---------|:------------| +| `concat()` | Concatenates one or more arguments (separated by commas) into a single string. | +| `regex(string, expression)` | Returns `True` if the string is an exact and complete match for a regular expression. | +| `contains(string, substring)` | Returns `True` if the string contains the substring. | +| `starts-with(string, substring)` | Returns `True` if the string begins with the substring. | +| `ends-with(string, substring)` | Returns `True` if the string ends with the substring. | +| `substr(string, start[, end])` | Returns the substring of `string` beginning at the index start and extending to (but not including) index end (or to the termination of `string`, if end is not provided). | +| `substring-before(string, target)` | Returns the substring of `string` before the first occurrence of the target substring. If the target is not found, or `string` begins with the target substring, then this will return an empty string. | +| `substring-after(string, target)` | Returns the substring of `string` after the first occurrence of the target substring. If the target is not found this will return an empty string. | +| `translate(string, fromchars, tochars)` | Returns a copy of string, where every occurrence of a character in `fromchars` is replaced by the corresponding character in `tochars` (e.g., replacing all lowercase letters with uppercase letters).format. Common formats include: %Y: 4-digit year%y: 2-digit year%m: 0-padded month%n: numeric month%b: short text month (Jan, Feb, Mar…)%d: 0-padded day of month%e: day of month%a: short text day (Sun, Mon, Tue…).format. Common formats include: %H: 0-padded hour (24-hr time)%h: hour (24-hr time)%M: 0-padded minute%S: 0-padded second%3: 0-padded millisecond ticks.- Note: Some XLSForm features are not currently available in the Formbuilder, but they can be used for form building in XLSForm and then uploaded to KoboToolbox. This can be especially useful for complex forms. + For more information about XLSForm, see Introduction to XLSForm. For a comprehensive introduction to form development using XLSForm, we recommend KoboToolbox Academy’s self-paced online XLSForm Fundamentals Course.
-## What is XLSForm - -XLSForm is a standard for developing forms using Microsoft Excel and other spreadsheet software. XLSForms can then be uploaded to KoboToolbox to generate a data collection form. +This article explains how to set up an XLSForm using Microsoft Excel or other spreadsheet programs, including: -There are many advantages to using XLSForm, especially for building complex forms with more advanced functionalities, including relevance conditions, calculations, and constraints. XLSForm also enables you to collaborate on form building using the same Excel file or in real time using Google Sheets. +- Setting up the basic structure of your XLSForm +- Adding questions and option choices +- Adding form settings and optional columns +- Uploading and previewing your XLSForm in KoboToolbox- Note: For a comprehensive introduction to form development using XLSForm, we recommend KoboToolbox Academy’s self-paced online XLSForm Fundamentals Course. + Note: Some XLSForm features are not currently available in the Formbuilder, but KoboToolbox forms can be downloaded, modified in XLSForm, and uploaded back to KoboToolbox.
+ ## Setting up an XLSForm To set up the basic structure of an XLSForm: -1. Create a workbook in Microsoft Excel or Google Sheets. +1. Create a workbook in your preferred spreadsheet software. 2. Create three worksheets: **survey**, **choices**, and **settings**. - Worksheet names must be all lowercase letters. -3. In the **survey** worksheet, create three columns with the headings: `type`, - `name`, and `label`. -4. In the **choices** worksheet, create three columns with the headings: - `list_name`, `name`, and `label`. +3. In the **survey** worksheet, create three columns with the headings: `type`, `name`, and `label`. +4. In the **choices** worksheet, create three columns with the headings: `list_name`, `name`, and `label`. 5. The **settings** worksheet is optional. It can be used to include additional form specifications and customizations. - For example: `form_title`, `style`, and `default_language`. ++To get started with XLSForm, download a sample XLSForm here. +
+ ### Mandatory columns in XLSForm -#### Survey worksheet +The following columns are mandatory in XLSForm: + +**survey worksheet** | Column name | Description | -| :--- | :--- | +| --- | --- | | type | Defines the question type (e.g., text, integer, select_one) | | name | Defines a short, unique name to refer to each question | | label | Defines the question text as it will be displayed in the form | -#### Choices worksheet +**choices worksheet** | Column name | Description | -| :--- | :--- | +| --- | --- | | list_name | Defines the unique identifier for a list of option choices | | name | Defines a short, unique name to refer to each option choice | | label | Defines the choice text as it will be displayed in the form | ## Adding questions -In XLSForm, questions are added in the **survey** worksheet. The step-by-step process below explains how to add the following example questions: **What is your name?**, **What is your baby’s sex?**, and **How old are you?** - -1. In the `type` column of the survey worksheet, type **text**. This is the question type for the first question, **What is your name?** -2. In the `name` column, type **yourname**. This will be the unique name used to identify the first question. Each question must have a unique name and cannot contain spaces or symbols (except the underscore). -3. In the `label` column, type **What is your name?**. This label will be displayed as the question text on the form during data collection. +In XLSForm, questions are added in the **survey** worksheet. To add questions in XLSForm: -| type | name | label | -| :--- | :------- | :----------------- | -| text | yourname | What is your name? | -| survey | +1. In the `type` column of the `survey` worksheet, enter the [question type](https://support.kobotoolbox.org/question_types_xls.html) of the question you want to add. +2. In the `name` column, enter a name used to identify the question. + - Each question must have a unique name and cannot contain spaces or symbols (except underscores). +3. In the `label` column, enter the question text as it should be displayed in the form during data collection. -4. For the second question, **What is your baby’s sex?**, enter **select_one sex** in the `type` column of the survey worksheet. - - **select_one** is the question type that allows users to select only one choice from a list of response choices. - - **sex** is the name of the list of response choices, which is defined in the choices worksheet (see [Adding response choices](https://support.kobotoolbox.org/getting_started_xlsform.html#adding-response-choices)). -5. In the `name` column, type **baby_sex**. -6. In the `label` column, type **What is your baby’s sex?** +**survey worksheet** -| type | name | label | -| :------------- | :------- | :----------------------- | -| select_one sex | baby_sex | What is your baby’s sex? | +| type | name | label | +| :--- | :--- | :--- | +| text | yourname | What is your name? | | survey | +4. If you are adding **select type questions** (`select_one`, `select_multiple`, or `rank`): in the `type` column, after the question type, add a space and enter the name of the list of choices. + - The name of the list of choices is later defined in the `choices` worksheet as the `list_name`. -7. For the question **How old are you?**, follow the same process using **integer** as the question type in the `type` column. +**survey worksheet** -| type | name | label | -| :------ | :--- | :--------------- | -| integer | age | How old are you? | +| type | name | label | +| :--- | :--- | :--- | +| select_one sex | baby_sex | What is your baby’s sex? | | survey |- Note: To learn more about question types in XLSForm, see Question types (XLSForm.org). +To learn more about question types in XLSForm, see Question types in XLSForm.
-## Adding response choices +## Adding option choices + +For select type questions, option choices are added in the **choices** worksheet. To add option choices in XLSForm: -For select type questions (**select_one** and **select_multiple**), response choice options are added in the **choices** worksheet. The step-by-step process below explains how to add the choices for the example question: **What is your baby’s sex?** +1. In the `list_name` column of the `choices` worksheet, enter the name of the **list of option choices**. + - The `list_name` is a unique identifier for a list of option choices. It must match the list name entered in the `type` column of the `survey` worksheet. +2. In the `name` column, add a short name for each option choice. + - Each choice within a list must have a unique `name`, which cannot contain spaces or symbols (except underscores). +3. In the `label` column, enter the choice text as it should be displayed in the form during data collection. -1. In the `list_name` column in the choices worksheet, enter the list_name **sex**. - - This is the list_name previously defined for the **baby_sex** question in the survey worksheet. - - The list_name is the unique identifier for the list of response choice options. -2. In the name column, add the choice name **male**. - - The choice name is the unique identifier for each choice option. -3. In the label column, enter the choice label **Male**. - - The choice label is displayed on the form during data collection. -4. To add the second choice option for the **baby_sex** question, enter **sex** in the `list_name` column. Enter **female** as the choice name and **Female** as the choice label. +**choices worksheet** -| list_name | name | label | -| :-------- | :----- | :----- | -| sex | male | Male | -| sex | female | Female | +| list_name | name | label | +| :--- | :--- | :--- | +| sex | male | Male | +| sex | female | Female | | choices | ++To learn more about managing option choices in XLSForm, see Managing option choices in XLSForm. +
+ ## Adding settings There are many optional settings that can be added to the **settings** worksheet in XLSForm. Common form settings include: -| Form setting | Description | -| :--------------- | :------------------------------------- | -| form_title | Title displayed at the top of the form | -| default_language | Default form language | -| style | Themes for Enketo web forms | -| version | Form version ID | -| settings | +| Setting | Description | +| --- | --- | +| form_title | Title displayed at the top of the form | +| default_language | Default form language | +| style | Themes for Enketo web forms | +| version | Form version ID | For example, to add a form title: 1. Add a column in the settings worksheet named `form_title`. 2. Enter the form title in the `form_title` column. - - If you do not define a form title in your XLSForm, by default the Excel file name will be used as the project name in KoboToolbox. This can be edited in KoboToolbox.- Note: To learn more about the settings worksheet in XLSForm, see Settings worksheet (XLSForm.org). +Note: All form settings are optional. If you do not define a form title in your XLSForm, the Excel file name will be used as the project name in KoboToolbox by default. This can be edited in KoboToolbox.
-## Adding optional columns to the survey worksheet +**settings worksheet** -To further customize your XLSForm, you can add optional columns that include form logic, question options, and advanced settings. - -| **Column name** | **Description** | -| :----------------- | :--------------------------------------------- | -| hint | Question hint | -| guidance_hint | Guidance hint | -| required | Option to make a question mandatory | -| relevant | Skip logic conditions for the question | -| constraint | Validation criteria for the question | -| constraint_message | Error message when validation criteria not met | -| appearance | Options for how questions are displayed | -| choice_filter | Criteria for cascading select | -| parameters | Settings for specific question types | -| calculation | Mathematical expression for calculate question | -| default | Default response for a question | - -## Uploading and previewing the XLSForm in KoboToolbox - -To upload and preview your XLSForm in KoboToolbox: - -1. Go to the **Project List** view in KoboToolbox and click **NEW**. -2. Select **Upload an XLSForm** and upload your **Excel** file. - - If you created your XLSForm in **Google Sheets**, you will need to download the file before uploading it to KoboToolbox. In the Google Sheets menu, click File > Download > Microsoft Excel. -3. Enter the project details and click **CREATE PROJECT**. -4. Click the **Preview** button. +| form_title | +| :--- | +| Getting started with- Note: To learn how to import your XLSForm via URL, see the support article Importing an XLSForm via URL. +To learn more about the settings worksheet in XLSForm, see Form settings in XLSForm.
-## Downloading an XLSForm from KoboToolbox - -Forms created using the KoboToolbox Formbuilder can be easily downloaded as an XLSForm file. +## Adding optional columns to the survey worksheet -1. Go to the **FORM** tab of your project in KoboToolbox. -2. Click the **More actions** icon. -3. Click **Download XLS**. +To further customize your XLSForm, you can add optional columns to configure form logic, question options, and advanced settings. Common optional columns include: -Downloading your KoboToolbox form as an XLSForm file can be very useful for many reasons, including: +| Column name | Description | +| --- | --- | +| hint | Question hint | +| guidance_hint | Guidance hint | +| required | Option to make a question mandatory | +| relevant | Skip logic conditions for the question | +| constraint | Validation criteria for the question | +| constraint_message | Error message when validation criteria are not met | +| appearance | Options for how questions are displayed | +| choice_filter | Criteria for cascading select | +| parameters | Settings for specific question types | +| calculation | Mathematical expression for calculate question | +| default | Default response for a question | -- Adding advanced features to your form that are not currently supported in the Formbuilder. -- Making changes to the form that are more efficient to do in XLSForm (e.g., duplicating a large number of questions or adding translations). -- Avoiding slow computer or internet speeds that can affect form building in the Formbuilder (e.g., limited RAM, poor internet connectivity). -- Sharing the form as an Excel file for collaboration with team members and managing form versions. -- Sharing the form to request assistance from the KoboToolbox support team or in the Community Forum. ++To learn more about optional columns in XLSForm, see Using question options in XLSForm, Question appearances in XLSForm, and Introduction to form logic in XLSForm. +
-## Replacing a form with an XLSForm file +## Uploading and previewing your XLSForm in KoboToolbox -You can replace an existing form in the Formbuilder with a new version using an XLSForm. For example, after editing the form in Excel, you must upload the updated file to KoboToolbox. +Once you have finished developing your XLSForm, you can upload and preview it in KoboToolbox: -1. Go to the **FORM** tab of your project in KoboToolbox. -2. Click the **More actions** icon. -3. Click **Replace form**. -4. Choose the file you wish to upload. +1. Go to the **Project** home page in KoboToolbox and click **NEW**. +2. Select **Upload an XLSForm** and upload your XLSForm file. +3. Enter the project details and click **CREATE PROJECT**. +4. Click the+To learn how to download an XLSForm from KoboToolbox, import your XLSForm via URL, and use KoboToolbox to validate and test your XLSForm, see Using XLSForm with KoboToolbox. +
-- [Official XLSForm documentation at XLSForm.org](https://xlsform.org) -- [Form building documentation from ODK](https://docs.getodk.org/) diff --git a/source/grouping_questions_xls.md b/source/grouping_questions_xls.md new file mode 100644 index 000000000..bff37efc4 --- /dev/null +++ b/source/grouping_questions_xls.md @@ -0,0 +1,139 @@ +# Grouping questions in XLSForm +**Last updated:** 15 May 2025 + +Grouping questions in XLSForm helps organize related content into clear, structured sections, improving form layout and navigation. For example, you can group all demographic questions into one section. + +XLSForm makes it easy to create groups and [nested groups](https://support.kobotoolbox.org/grouping_questions_xls.html#nested-groups), and to apply [skip logic](https://support.kobotoolbox.org/grouping_questions_xls.html#applying-skip-logic-to-question-groups) to entire question groups. Group-level skip logic streamlines the respondent's experience by showing only relevant sections based on previous answers. + +This article covers the following topics: + +- Creating question groups and nested groups in XLSForm +- Displaying all grouped questions on a single page +- Adding skip logic to question groups + ++Note: This article focuses on grouping questions in XLSForm. To learn about grouping questions in the KoboToolbox Formbuilder, see Grouping questions and repeating groups. +
+ +## Creating a question group + +To create a question group in XLSForm: + +1. In the `type` column of the `survey` worksheet, enter **begin_group** to indicate the start of the group. +2. In the `name` column of the **begin_group** row, enter the unique identifier for the group. +3. In the `label` column, enter the title of the group as you want it displayed in the form. The label is optional and can be left blank. +4. Enter each question of the group in its own row, as you normally would. +5. In a new row after the grouped questions, enter **end_group** in the `type` column to indicate the end of the group. + - In the **end_group** row, leave the `name` and `label` columns blank. + +**survey worksheet** + +| type | name | label | +| :--- | :--- | :--- | +| **begin_group** | personal_info | Section A: Personal Information | +| text | name | What is your name? | +| integer | age | How old are you? | +| select_one yn | married | Are you married? | +| **end_group** | | | +| survey | + +### Nested groups + +Nested groups are groups of questions inside another group of questions. Nested groups can be used to create a hierarchical structure within your XLSForm. For example, you can include a group of questions about a child inside a larger group of questions about the household. + +When creating multiple groups, ensure that each `begin_group` row has a corresponding `end_group` row. If the number of `begin_group` rows does not match the number of `end_group` rows, the form will generate an error, preventing it from functioning properly during preview or deployment. + +**survey worksheet** + +| type | name | label | +| :--- | :--- | :--- | +| **begin_group** | personal_info | Section A: Personal Information | +| text | name | What is your name? | +| integer | age | How old are you? | +| select_one yn | married | Are you married? | +| **begin_group** | education | Education | +| select_one yn | student | Are you currently a student? | +| select_one edu | education_level | What is the highest level of education you have completed? | +| **end_group** | | | +| **end_group** | | | +| survey | + +### Repeat groups + +In XLSForm, question groups can be repeated to collect the same set of responses multiple times within a form. This is useful when gathering similar information about multiple people, items, or events. Repeated groups are called **repeat groups**. + ++ To learn more about setting up repeating groups of questions in XLSForm, see Repeat groups in XLSForm. +
+ +## Appearance settings for question groups + +A common reason to group questions is to display them together on a single page. You can adjust the group's appearance settings to control how grouped questions are shown during data collection. The steps vary depending on whether you are using [KoboCollect](https://support.kobotoolbox.org/kobocollect_on_android_latest.html) or [Enketo](https://support.kobotoolbox.org/enketo.html). + ++Note: Appearance settings to display groups on a single page work both for question groups and repeat groups. +
+ +### Using KoboCollect to collect data + +By default, KoboCollect displays each question on a separate screen. Users must move manually from one question to the next. + +To **display all grouped questions on the same screen** in KoboCollect: +1. In the `survey` worksheet, add an **appearance** column. +2. In the `appearance` column, enter **field-list** in the `begin_group` row. + * Each question group will now appear on its own page. + +| type | name | label | appearance | +| :--- | :--- | :--- | :--- | +| begin_group | personal_info | Section A: Personal Information | **field-list** | +| text | name | What is your name? | | +| integer | age | How old are you? | | +| select_one yn | married | Are you married? | | +| end_group | | | | + +### Using Enketo web forms to collect data + +By default, Enketo web forms display all questions on a single page. + +To display each group of questions on its own page in Enketo web forms: +1. In the `settings` worksheet, add a **style** column. +2. In the second cell of the `style` column, enter **pages**. + * This applies the **pages** [theme](https://support.kobotoolbox.org/form_style_xls.html) to your Enketo web form, dividing it into separate pages similar to KoboCollect. + +**settings worksheet** + +| style | +| :--- | +| **pages** | +| settings | + +3. In the `survey` worksheet, add an **appearance** column. +4. In the `appearance` column, enter **field-list** in the `begin_group` row. + * Each question group will now appear on its own page. + +**survey worksheet** + +| type | name | label | appearance | +| :--- | :--- | :--- | :--- | +| begin_group | personal_info | Section A: Personal Information | **field-list** | +| text | name | What is your name? | | +| integer | age | How old are you? | | +| select_one yn | married | Are you married? | | +| end_group | | | | +| survey | + + +## Applying skip logic to question groups + +Applying skip logic to question groups ensures that only relevant sections appear based on earlier responses. For example, in a household survey, you can use skip logic to show a group of questions for the head of household only when a previous question identifies the respondent as such. This makes the form easier to navigate and more responsive to user input. + +To [apply skip logic](https://support.kobotoolbox.org/skip_logic_xls.html) to question groups in XLSForm, use the same approach as you would for individual questions: +1. Add a **relevant** column to your `survey` worksheet. +2. In the `relevant` column for the `begin_group` row, enter the condition that determines when the group should be shown. +3. If the condition is met, the entire group will be displayed. If not, the group will be hidden. + +This helps control the flow of your form so that only relevant sections appear based on earlier responses, making the form more streamlined and responsive to user input. + ++Note: Skip logic can be applied both for question groups and repeat groups. To learn more about skip logic in XLSForm, see Adding skip logic in XLSForm. +
diff --git a/source/images/choice_filters_xls/choice_filters.png b/source/images/choice_filters_xls/choice_filters.png new file mode 100644 index 000000000..52cabe05c Binary files /dev/null and b/source/images/choice_filters_xls/choice_filters.png differ diff --git a/source/images/edit_forms_excel/sample_xlsform.png b/source/images/edit_forms_excel/sample_xlsform.png new file mode 100644 index 000000000..22621206c Binary files /dev/null and b/source/images/edit_forms_excel/sample_xlsform.png differ diff --git a/source/images/form_style_xls/theme_default.png b/source/images/form_style_xls/theme_default.png new file mode 100644 index 000000000..49d65af7d Binary files /dev/null and b/source/images/form_style_xls/theme_default.png differ diff --git a/source/images/form_style_xls/theme_grid.png b/source/images/form_style_xls/theme_grid.png new file mode 100644 index 000000000..0f6eca40c Binary files /dev/null and b/source/images/form_style_xls/theme_grid.png differ diff --git a/source/images/form_style_xls/theme_grid_no_text_transform.png b/source/images/form_style_xls/theme_grid_no_text_transform.png new file mode 100644 index 000000000..8bce43ffc Binary files /dev/null and b/source/images/form_style_xls/theme_grid_no_text_transform.png differ diff --git a/source/images/form_style_xls/theme_pages.png b/source/images/form_style_xls/theme_pages.png new file mode 100644 index 000000000..ed79f3c88 Binary files /dev/null and b/source/images/form_style_xls/theme_pages.png differ diff --git a/source/images/library_locking/locked.png b/source/images/library_locking/locked.png new file mode 100644 index 000000000..57e05157e Binary files /dev/null and b/source/images/library_locking/locked.png differ diff --git a/source/images/library_locking/upload_template.png b/source/images/library_locking/upload_template.png new file mode 100644 index 000000000..ebc04a22e Binary files /dev/null and b/source/images/library_locking/upload_template.png differ diff --git a/source/images/library_locking/use_template.png b/source/images/library_locking/use_template.png new file mode 100644 index 000000000..a9ee86318 Binary files /dev/null and b/source/images/library_locking/use_template.png differ diff --git a/source/images/media/upload_media.png b/source/images/media/upload_media.png new file mode 100644 index 000000000..c6ba28128 Binary files /dev/null and b/source/images/media/upload_media.png differ diff --git a/source/images/pull_data_kobotoolbox/upload_media.png b/source/images/pull_data_kobotoolbox/upload_media.png new file mode 100644 index 000000000..c6ba28128 Binary files /dev/null and b/source/images/pull_data_kobotoolbox/upload_media.png differ diff --git a/source/images/select_from_file_xls/upload_media.png b/source/images/select_from_file_xls/upload_media.png new file mode 100644 index 000000000..c6ba28128 Binary files /dev/null and b/source/images/select_from_file_xls/upload_media.png differ diff --git a/source/images/xlsform_with_kobotoolbox/download_xls.png b/source/images/xlsform_with_kobotoolbox/download_xls.png new file mode 100644 index 000000000..0f347e25b Binary files /dev/null and b/source/images/xlsform_with_kobotoolbox/download_xls.png differ diff --git a/source/images/xlsform_with_kobotoolbox/import_via_url.png b/source/images/xlsform_with_kobotoolbox/import_via_url.png new file mode 100644 index 000000000..09469ad4e Binary files /dev/null and b/source/images/xlsform_with_kobotoolbox/import_via_url.png differ diff --git a/source/images/xlsform_with_kobotoolbox/replace_form.png b/source/images/xlsform_with_kobotoolbox/replace_form.png new file mode 100644 index 000000000..69b6745c8 Binary files /dev/null and b/source/images/xlsform_with_kobotoolbox/replace_form.png differ diff --git a/source/images/xlsform_with_kobotoolbox/upload_xls.png b/source/images/xlsform_with_kobotoolbox/upload_xls.png new file mode 100644 index 000000000..7014c51fd Binary files /dev/null and b/source/images/xlsform_with_kobotoolbox/upload_xls.png differ diff --git a/source/index.rst b/source/index.rst index a27df47f3..d8c20fffd 100644 --- a/source/index.rst +++ b/source/index.rst @@ -102,11 +102,29 @@ Search the knowledge base, browse our resources, and visit our forum for more de edit_forms_excel getting_started_xlsform - xls_url - media + xlsform_with_kobotoolbox + question_types_xls + option_choices_xls + grouping_questions_xls + repeat_groups_xls + question_options_xls + appearances_xls language_xls - dynamic_data_attachment + media + form_logic_xls + functions_xls + skip_logic_xls + constraints_xls + required_logic_xls + choice_filters_xls + calculations_xls + form_settings_xls + form_style_xls.md + metadata_xls pull_data_kobotoolbox + select_from_file_xls + select_from_map_xls + dynamic_data_attachment library_locking .. raw:: html diff --git a/source/language_xls.md b/source/language_xls.md index ea7ebd3fc..f01ebcef1 100644 --- a/source/language_xls.md +++ b/source/language_xls.md @@ -1,132 +1,144 @@ -# Adding Another Language to your XLSForm -**Last updated:** 29 Jul 2025 +# Adding translations in XLSForm +**Last updated:** Oct 26, 2025 +Adding translations to a form allows users to switch to their preferred language during data collection without creating separate forms. Any number of translations can be added. Both [KoboCollect](https://support.kobotoolbox.org/kobocollect_on_android_latest.html) and [Enketo web forms](https://support.kobotoolbox.org/enketo.html) support form translations. -There are two methods to adding multiple languages to your form. You can either -add and manage them directly through the online -[Project Dashboard](language_dashboard.md) or you can add them in an XLSForm and -upload it to Kobo. +Most elements displayed in the form can be translated, such as **question labels**, **hints**, **choice labels**, **constraint messages**, and **required messages**. Elements used for form structure, like question names, choice names, and list names, cannot be translated and should remain in the language used for form development and data analysis. -Here are detailed instructions on how you can add another language to your form: +When your form includes multiple translations, KoboCollect and Enketo will display a language selector in the **top right corner of the form**, allowing respondents to choose their preferred language. -- Create your form in the default language. This should be the language that - the person responsible for designing the questionnaire is most comfortable - with. When you are done, or when a portion of the form has been created, - save it. You'll be returned to the draft form's project dashboard. +
+ Note: Adding translations in XLSForm is faster and more efficient than using the Formbuilder, especially for longer forms. To learn how to download your form in XLSForm to add translations, see Using XLSForm with KoboToolbox.
+
+For hands-on practice with adding translations in XLSForm, see KoboToolbox Academy's XLSForm Fundamentals Course.
+
You can change the size of your columns, add colors or change the font size, none of these will affect your form.
-- Then, if you have hints in your form, the same needs to apply to the `hint` - column, for example `hint::Français (fr)` or `hint::English (en)`. +## Setting the default form language -**survey sheet** +To add translations to an XLSForm, first define the default language. This is the language the form will open to by default. -| type | name | label | relevant | -| :--------------- | :------------- | :----------------------------- | :------------------------ | -| text | full_name | What is your name? | | -| select_one yesno | children_yesno | Do you have any children? | | -| integer | children_count | How many children do you have? | ${children_yesno} = 'yes' | +To define the default language of your form: +1. In the `settings` worksheet, add a **default_language** column. +2. In the `default_language` column, enter the default language using the **language (code)** format. + - For example: `English (en)`. + +**settings worksheet** + +| default_language | +| :---------------- | +| English (en) | +| settings | + +To set up the `survey` worksheet: + +1. Rename the **label** column using the format **label::language (code)**. + - For example: `label::English (en)`. +2. If your form includes `hint`, `required_message`, `constraint_message`, or `media` columns in the `survey` worksheet, rename the existing columns using the format **column_name::language (code)**. + - For example: `hint::English (en)`. + +**survey worksheet** + +| type | name | label::English (en) | hint::English (en) | +| :--- | :--- | :------------------ | :----------------- | +| integer | age | How old are you? | In years | +| select_one yn | student | Are you currently a student? | | | survey | -- Now add your translations for every row inside the `label::language (code)` - column. When you are done, make sure you didn't skip any questions (for - every field that has text inside the label column there should be text - inside the `label::language (code)` column). You can find the official - 2-character language codes (subtags) - [here](https://www.iana.org/assignments/language-subtag-registry/language-subtag-registry). +Finally, to set up the `choices` worksheet, rename the **label** column using the format **label::language (code)**. + +**choices worksheet** + +| list_name | name | label::English (en) | +| :--------- | :--- | :------------------ | +| yn | yes | Yes | +| yn | no | No | +| choices | + +## Adding translations + +Once you have defined your default language, you can add translations for each visible element of your form. You can add as many translation columns as you like. + ++ Note: If you omit text for a translated element, it will appear as a blank field on the form. +
-Tip: Copy-paste the original label column and then make changes to the translations so you don't leave anything blank by accident: It's better to have something showing in the wrong language than not having a blank question in some language. You can repeat this step and add as many languages as you like, each in their separate columns and with a different name inside label::language (code).
+ To learn more about managing media files in translated forms, see Adding media to an XLSForm. +
-| type | name | label:English (en) | label::Français (fr) | relevant | -| :--------------- | :------------- | :----------------------------- | :----------------------------- | :------------------------ | -| text | full_name | What is your name? | Quel est votre nom? | | -| select_one yesno | children_yesno | Do you have any children? | Avez-vous des enfants? | | -| integer | children_count | How many children do you have? | Combien des enfants avez-vous? | ${children_yesno} = 'yes' | +**survey worksheet** + +| type | name | label::English (en) | label::Chichewa (ny) | hint::English (en) | hint::Chichewa (ny) | +| :--- | :--- | :------------------ | :------------------- | :----------------- | :------------------ | +| integer | age | How old are you? | Muli ndi zaka zingati? | In years | M'zaka | +| select_one yn | student | Are you currently a student? | Kodi panopa ndinu wophunzira? | | | | survey | -- Now switch to the **choices** sheet of your file, if you have one. +To add translations to the `choices` worksheet: +1. Add a new **label** column for each translation language using the format **label::language (code)**. + - For example: `label::Spanish (es)`. +2. Enter the translation for each choice label in the relevant translation column. +3. If your `choices` worksheet includes media columns, set up the corresponding translation columns using the **column_name::language (code)** format. -- In the **choices** sheet you have another column called `label`. Repeat - steps 5 and 6. Make sure that you use the exact same spelling for - `label::language (code)`. For example, `label::Francais (fr)` and - `label::Français (fr)` are not identical. ++ Note: To learn more about managing media files in translated forms, see Adding media to an XLSForm. +
-**choices sheet** +**choices worksheet** -| list_name | name | label::English (en) | label::Français (fr) | -| :-------- | :--- | :------------------ | :------------------- | -| yesno | yes | Yes | Oui | -| yesno | no | No | Non | +| list_name | name | label::English (en) | label::Chichewa (ny) | +| :--------- | :--- | :------------------ | :------------------- | +| yn | yes | Yes | Inde | +| yn | no | No | Ayi | | choices | -- In the **settings** sheet, underneath `form_title` edit the text of your - form's title to something like "My form (English and French)" so you can - easily identify it later. -**settings sheet** +## Guidelines for translations -| form_title | -| :--------------------------- | -| My form (English and French) | -| settings | +### Using spreadsheet features for bulk translations + +XLSForm makes it easy to translate form elements in bulk, instead of entering translations one by one. For example, you can copy an entire column into a translation system for bulk translation, and paste the column back into your XLSForm. If you are using Google Sheets to build your XLSForm, you can use the `GOOGLETRANSLATE()` formula to automate the translation process. + +Machine translations should always be reviewed and validated by a fluent speaker to ensure accuracy, cultural appropriateness, and proper context. This step helps maintain the quality and reliability of your translated content. + +### Translating to non-Latin scripts + +Non-Latin scripts such as Arabic, Cyrillic, Tamil, Nepali, or Hindi are fully supported in KoboToolbox and can be used for default languages or translations. -- Save your file and close Excel. - -- Return to KoboToolbox and click on **Replace with XLS**, then upload your - updated XLSForm. Choose the file you just finished editing and click **OK**. - -- Open the form you just uploaded and click on **Preview Form**. At the top - next to **Choose Language** click on the dropdown. It will have a default - (your original language) as well as the new languages you just added. - -## Translating to Tamil, Nepali, Hindi, etc. scripts - -When translating to non-Latin scripts, such as Tamil, Nepali, Hindi, etc, please -make sure you do not use a so-called pseudo font. When writing in these -languages make sure you only use the proper Unicode characters. To write proper -Unicode characters you don't have to install any particular fonts. Instead, you -(or your translator) need to set your keyboard to use the respective script -(Tamil, Nepali, etc.) and then write normally. The correct keyboard setting will -produce the actual script letters in Unicode instead of some Latin phonetic -equivalents. (This would also be the same way as writing these languages into an -email, KoboToolbox, or any other Web application. - -For help with adding the correct system keyboard, -[check this link](https://support.microsoft.com/en-us/help/17424/windows-change-keyboard-layout) -(Windows only). - -Pseudo fonts allow writing in these scripts and are commonly used in many -countries, particularly in South Asia. But while they work on the computer that -has a specific font installed, they will not work on any other computer that -doesn't use that particular font. That is because these fonts just disguise -regular Latin characters and symbols and make them appear in a different shape. -For example, when writing "Hello" with the Nepali pseudo font 'Preeti', it will -look like this: हेल्लो. But what is really written there remains the letters H e -l l o. For some people using these fonts which often use phonetic equivalents to -English, may be easier. Another reason they are being used widely is that many -computers used to not have support for these scripts and thus needed pseudo -fonts as a "hack". Either way, Unicode characters are the best way to go - and -the only way for use in KoboToolbox. ++ Note: It is recommended to use only Latin characters for question and choice names, because non-Latin scripts may cause errors or compatibility issues when exporting data or working with XLSForm, but question and choice labels can safely use any script. +
+ +When adding translations in non-Latin scripts, it is essential to **use proper Unicode characters**. Unicode ensures that text is correctly displayed and understood across all devices and platforms. + +To enter Unicode text, you do not need to install any special fonts. Instead, set your system keyboard to the appropriate language or script and type as you normally would. Avoid using pseudo fonts (i.e., special fonts that visually mimic non-Latin scripts by reassigning Latin characters), as these are not compatible with KoboToolbox and can cause serious display and data integrity issues. If you are using Windows and need help setting up your system keyboard, refer to [Microsoft documentation](https://support.microsoft.com/en-us/windows/manage-the-language-and-keyboard-input-layout-settings-in-windows-12a10cb4-8626-9b77-0ccb-5013e0c7c7a2). ## Translating right-to-left scripts -When adding a language that uses right-to-left script it is important to use the -correct language code, however even if the correct code is used, if the first -question, hint, or note is written in a left-to-right script the form will -automatically format the rest of the translation to a left-to-right format. +When adding a language that uses a right-to-left (RTL) script, such as Arabic, Hebrew, or Urdu, it is important to **use the correct language code** and to ensure the **first visible text in the translation** (e.g., a question label, hint, or note) is written in the RTL language. This will ensure that the form's layout does not default to left-to-right (LTR) formatting. + +Additionally, when incorporating question references within question labels using RTL scripts, please note that the question reference syntax is reversed (i.e., `{question_name}$`). + +**survey worksheet** + +| type | name | label::English (en) | label::Arabic (ar) | +| :--- | :--- | :------------------ | :----------------- | +| begin\_group | profile | Respondent profile | ملف المستجيب | +| text | name | Respondent's name | اسم المدعى عليه | +| integer | age | How old is ${name}? | ؟{name}$ كم عمرك | +| end\_group | | | | +| survey | diff --git a/source/library_locking.md b/source/library_locking.md index 05c748b61..ecca622ad 100644 --- a/source/library_locking.md +++ b/source/library_locking.md @@ -1,429 +1,217 @@ -# Library locking +# Library locking with XLSForm **Last updated:** 30 Sep 2025 +The [KoboToolbox Library](https://support.kobotoolbox.org/question_library.html) allows you to store and manage templates, questions, and blocks for reuse across multiple projects. Form templates in the **Library** can be shared with team members to ensure consistent form design and reduce duplication of effort. -"Library locking" refers to the feature enabling various aspects of a survey to -be "[locked](#locked)" when created from a template containing -[locking attributes](#restrictions). All aspects of a form's editing are -available to be locked through the assigning of "[locking profiles](#profile)" -at the form, question or group level. These locking profiles can be assigned -granular "[restrictions](#restriction)" that group together locking -functionalities. Alternatively, the form can be fully locked down, preventing -all aspects of editing. +**Library locking** expands on this by allowing you to control how templates can be edited once they are used to create new projects. With locking, you can specify which questions, groups, or form-level settings can be changed. This is especially useful for large teams working from a shared template, where certain elements need to remain fixed while others can be adapted to local needs. -- Currently, only locking set within the XLSForm itself is supported, but will - be incorporated into the formbuilder at some point in the future. -
- -This feature may be useful in a large, distributed team setting where a standard -template is used, with some locked features, and each team can make necessary -local adjustments for their needs. The creator of the template can continue to -make updates, but the locks will restrict changes to specified aspects of the -form for those who [create a project based on the template](quick_start.md). +This article explains how library locking works, the types of restrictions you can apply, how to configure them in XLSForm, and how to upload locked XLSForms to KoboToolbox.
- Locking aspects of a form is separate from
- managing project permissions.
+Note: Library locking is not currently supported in the KoboToolbox Formbuilder. To use this feature, you must implement it via XLSForm and then upload your XLSForm to KoboToolbox.
+
+To learn more about downloading and editing your form as XLSForm, see Using XLSForm with KoboToolbox.
+Note: Library locking restrictions apply only in the Formbuilder when a project is created from a locked template. If the XLSForm is downloaded and edited in a spreadsheet, the restrictions will not prevent changes. However, incorrect or invalid locking configurations may cause errors when the form is re-uploaded. +
-If `kobo--lock_all` is set to `True`, then all additional granular restrictions -are redundant as the form is _fully_ locked down. If it is set to `False` _or_ -omitted from the `settings` sheet, then defined locking profiles can be used to -control the locked behaviour: +Library locking is configured in three XLSForm worksheets: +- **survey worksheet:** To apply restrictions to specific questions and groups. +- **settings worksheet:** To apply form-level restrictions and set the `kobo--lock_all` option. +- **kobo--locking-profiles worksheet:** To define profiles that group related restrictions. -**settings sheet** +Together, these worksheets let you define which parts of a form remain fixed and which parts can be edited when the template is used to create new projects. -| kobo--lock_all | -| :------------- | -| true | -| settings | +## Types of restrictions -The accepted values for `kobo--lock_all` are the same as in the `survey` sheet -that -[pyxform supports](https://github.com/XLSForm/pyxform/blob/43ea039250f44cff23b3ad10740fca54dfa12383/pyxform/aliases.py#L127-L142). -No error will be thrown if an invalid value is used, only the form will not -function as intended from the user's perspective. +Library locking supports restrictions at three levels: **question**, **group**, and **form**. Restrictions define what can and cannot be edited when a project is created from a locked template. -
- Note that the restriction name, such as choice_add below, is
- predefined and only the restrictions listed below are valid
- options.
-
choice_add | Prevents adding new choices to a **select** question. |
+| choice_delete | Prevents deleting existing choices in a **select** question. |
+| choice_value_edit | Prevents editing a choice name (or XML value). |
+| choice_label_edit | Prevents editing a choice label. |
+| choice_order_edit | Prevents reordering choices in a **select** question. |
+| question_delete | Prevents deleting a question. |
+| question_label_edit | Prevents editing a question label or hint. |
+| question_settings_edit | Prevents editing question settings, including the question name. This does not include skip logic or validation criteria. |
+| question_skip_logic_edit | Prevents editing skip logic conditions. |
+| question_validation_edit | Prevents editing validation criteria. |
### Group-level restrictions
-| Name | Description |
-| :-------------------------- | :----------------------------------------------------------------------------------------------------- |
-| `group_delete` | Delete group modal **Delete everything** button (or delete group button if paired with `group_split`) |
-| `group_split` | Delete group modal **Ungroup questions** button (or delete group button if paired with `group_delete`) |
-| `group_label_edit` | Edit a group `label` |
-| `group_question_add` | Adding or cloning questions inside given group (children groups included) |
-| `group_question_delete` | Delete any question from given group (children groups questions included) |
-| `group_question_order_edit` | Changing order of questions inside given group (children groups included) |
-| `group_settings_edit` | Changing **All group settings** from given group **Settings** |
-| `group_skip_logic_edit` | Changing **Skip Logic** from given group **Settings** |
+Group-level restrictions apply to [question groups](https://support.kobotoolbox.org/grouping_questions_xls.html). You can apply the following restrictions to groups in your XLSForm:
+
+| Name | Description |
+|:------|:-------------|
+| group_delete | Prevents deleting a group. |
+| group_split | Prevents ungrouping questions. |
+| group_label_edit | Prevents editing the group label. |
+| group_question_add | Prevents adding or cloning questions inside a group. |
+| group_question_delete | Prevents deleting questions from within a group. |
+| group_question_order_edit | Prevents reordering questions inside a group. |
+| group_settings_edit | Prevents editing group settings, including the group name. This does not include skip logic. |
+| group_skip_logic_edit | Prevents editing skip logic for a group. |
### Form-level restrictions
-| Name | Description |
-| :-------------------- | :----------------------------------------------------------------------------------------------- |
-| `form_appearance` | Changing form appearance from **Layout & Settings** |
-| `form_replace` | Replacing form using **Replace Form** modal |
-| `group_add` | Button for grouping questions |
-| `question_add` | Using **Insert cascading select** option and each **Add Question** and **Clone Question** button |
-| `question_order_edit` | Changing any questions order |
-| `language_edit` | Edit languages in **Translations Modal** |
-| `form_meta_edit` | Edit meta questions from **Layout & Settings** |
-
-## XLSForm configuration
-
-There are three sheets where locking profiles are defined and set: `survey`,
-`settings` and `kobo--locking-profiles`. The sheet of `kobo--locking-profiles`
-is not officially supported by [pyxform](https://github.com/XLSForm/pyxform) and
-is KoboToolbox-specific.
-
-Form-level restrictions are defined in the `settings` sheet and question and
-group-level restrictions are defined in the `survey` sheet.
-
-From within the `kobo--locking-profiles` sheet, all the locking profiles are
-defined in a matrix structure, using the keyword "[locked](#locked)" to assign a
-"[restriction](#restriction)" to a specific "[profile](#profile)". For example:
-
-**kobo--locking-profiles**
-
-Define the profiles and assign them restrictions. There is no limit on the
-number of profiles that can be defined (`profile_1`, ..., `profile_n`) but there
-are **only three** colours that differentiate their locking appearance in the
-formbuilder.
-
-| restriction | profile_1 | profile_2 | profile_3 |
-| :---------------- | :-------- | :-------- | :-------- |
-| choice_add | locked | | |
-| choice_delete | | locked | |
-| choice_label_edit | locked | | |
-| choice_order_edit | locked | locked | |
-| form_appearance | | | locked |
-| kobo--locking-profiles |
+Form-level restrictions apply to the whole form. You can apply the following restrictions to your XLSForm:
+| Name | Description |
+|:------|:-------------|
+| form_appearance | Prevents changes to the form [theme](https://support.kobotoolbox.org/form_style_xls.html). |
+| form_replace | Prevents replacing the form in KoboToolbox using the **Replace Form** option. |
+| group_add | Prevents creating new groups. |
+| question_add | Prevents adding or cloning questions in a group. |
+| question_order_edit | Prevents reordering questions. |
+| language_edit | Prevents editing translations. |
+| form_meta_edit | Prevents editing [metadata](https://support.kobotoolbox.org/metadata_xls.html) questions. |
-
- Note that not all valid restrictions need to be included in the
- restriction column, but an error will be thrown if an invalid
- restriction is included.
-
- Note that omitting kobo--lock_all from the
- settings sheet is equivalent to setting it to False.
-
+Note: Restrictions cannot be applied in the choices worksheet. All choice-related restrictions are defined at the question or group level in the survey worksheet.
+
kobo--lock_all is set to true, the whole form will be locked.kobo--locking-profiles worksheet are valid. Only predefined restriction names are supported.kobo--locking-profile exists in the survey or settings worksheet and that the profile names match those defined in the kobo--locking-profiles worksheet.-- into a long dash (—). Always use two single dashes in names such as kobo--locking-profiles.- Validation of the XLSForm library locking features will be expanded in the - future. -
-### Caveats - -In some spreadsheet editors, two single dashes (`--`) are automatically -converted to an m-dash (—), therefore making it difficult to type `kobo--` into -a cell. We therefore convert all instances of n- and m-dashes into two single -dashes (when prefixed with `kobo`). An XLSForm with the sheet name of -"kobo—locking-profiles" will be converted to `kobo--locking-profiles` and -similarly for the column headers. - -## JSON representation - -There are two attributes of the asset where locking information can be accessed -and modified: `asset.summary` and `asset.content`. - -If `kobo--locking-profile` is a column name in the `survey` sheet, it will also -be listed in the `asset.summary.columns` array. - -In `asset.summary`, the following two Boolean attributes describe an overview of -the form's locking structure: - -- `lock_all`, and -- `lock_any` - -The logic by which each of those Booleans are set is as follows: - -- `lock_all` is `True` _only_ if `kobo--lock_all` is set to `True` in the - `settings` sheet, otherwise it's `False` -- `lock_any` is set to `True` if _any_ of the following cases are `True`: - - `lock_all` is `True`, - - A `kobo--locking-profile` is set in the `settings` sheet, or - - _At least one_ `kobo--locking-profile` is set in the `survey` sheet - -In the example above, the following will be present in the `asset.summary`: - -``` -{ - ..., - "columns": [ - ..., - "kobo--locking-profile" - ], - "lock_all": false, - "lock_any": true, - ... -} -``` - -In `asset.content`, an attribute of `content.kobo--locking-profiles` exists as -an array of JSON objects with the following structure: - -``` -[ - { - "name": "profile_1", - "restrictions": [ - "choice_add", - "choice_label_edit", - "choice_order_edit" - ] - }, - ... -] -``` - -In `content.settings`, the following will be present in a JSON object: - -``` -{ - "kobo--locking-profile": "profile_3", - "kobo--lock_all": false -} -``` - -And finally in `content.survey`, each question that has been assigned a locking -profile will have a `kobo--locking-profile` attribute as follows: - -``` -[ - { - "name": "country", - "type": "select_one", - ... - "kobo--locking-profile": "profile_1" - }, - { - "name": "city", - "type": "select_one", - ... - "kobo--locking-profile": "profile_2" - }, - ... -] -``` - -## Locking profiles and asset types - -Of the four asset types (`survey`, `template`, `question` and `block`), only -`template`s and `survey`s handle library locking features and the locks are -enforced _only_ on surveys. Practically, this means the following: - -Assume an XLSForm containing valid locking features is imported: - -- If imported as a `block`, then all traces of locking are excluded and/or - stripped from the asset. This results in a `block` asset that will be - equivalent to the same form uploaded without any locking features; -- If imported as a `survey` (imported through the **Projects** section) or - `template` then all locks are intact: - - If, from within the formbuilder: - - a question is added to the library, then all locks are stripped from - the new `question` asset - - a group of questions is added to the library as a `block`, then all - locks are stripped - - If a `template` is created _from_ the locked `survey` asset, then that - `template` will inherit all the locks the `survey` had (but since it is - a template, you are able to edit the contents in the formbuilder), - - If a `survey` is created _from_ a locked `template`, the survey will - inherit all the locks that the `template` had - -| Original Asset Type | Process/action | Resulting `asset`'s Status | -| :------------------ | :------------------------------------------------- | :------------------------- | -| `survey` | import XLSForm file of locked `survey` | locked | -| `survey` | create `template` from locked `survey` | locked | -| `survey` | create `question` from locked `survey`※ | not locked | -| `survey` | create `block` from locked `survey`※ | not locked | -| `template` | import XLSForm file of locked `template` | locked | -| `template` | create `survey` from locked `template` | locked | -| `template` | create `question` from locked `template`※ | not locked | -| `template` | create `block` from locked `template`※ | not locked | -| `block` | import XLSForm file of locked `block`※ | not locked | -| `block` | add locked `block` from Library into `survey` | not locked | -| `block` | add locked `block` from Library into `template` | not locked | -| `block` | create `question` from locked `block`※ | not locked | -| `question` | import XLSForm file of locked `block`※ | not locked | -| `question` | add locked `question` from Library into `survey` | not locked | -| `question` | add locked `question` from Library into `template` | not locked | -| `question` | create `block` from locked `question`※ | not locked | - -※ These actions are not possible in the UI. - -## Terminology - -### `kobo--lock_all` - -Attribute containing a Boolean value, set in the `settings` sheet and applies -all locking restrictions to the form and all questions and groups (rendering -granular locking profiles redundant). - -### `kobo--locking-profile` - -Column name in the `survey` and `settings` sheets where the locking profile is -assigned to a question or group (in `survey`) or to the form (in `settings`). - -### `kobo--locking-profiles` - -Sheet name where restrictions are assigned to profiles. - -### `locked` - -Keyword used to assign a restriction to a profile in the -`kobo--locking-profiles` sheet. - -### Profile - -The name assigned to a group of restrictions, defined in the -`kobo--locking-profiles` sheet. It is assigned to questions and groups in the -`survey` sheet and to the from in the `settings` sheet. - -### Restriction - -A granular locking attribute that can be assigned to a profile and control the -locking behaviour at the question, group or form level. - -### Unlocked - -A form containing no locking attributes. diff --git a/source/media.md b/source/media.md index ffce948d8..830e0d995 100644 --- a/source/media.md +++ b/source/media.md @@ -1,209 +1,190 @@ -# Adding Various Types of Media (image, audio, video) to a Form -**Last updated:** 15 Feb 2022 +# Adding media to an XLSForm +**Last updated:** Oct 26, 2025 -In addition to text questions and text choices, you can also add various types -of media (such as _image_, _audio_, and _video_) to your forms. Having media in -a form should sometimes be able to help you express your questions and choices -in a much better way. + -Media in a form works both on **Collect android app** and **Web forms -(Enketo)**. These are the media files that are currently supported: -| Media | Files | -| :---- | :------------------------------------------------------------ | -| Image | jpeg, png, svg | -| Audio | aac, aacp, flac, mp3, mp4, mpeg, ogg, wav, webm, x-m4a, x-wav | -| Video | 3gpp, avi, flv, mov, mp4, ogg, quicktime (qtff), webm, wmv | - -This support article aims to illustrate how forms with media can be created with -**KoboToolbox**. Follow the instructions outlined below to include media to your -survey project. - -## Step 1: Download Form as XLSForm - -Create a survey project in the formbuilder UI and then download your form as XLS -to add media settings to it. The formbuilder currently does not support adding -media to the form directly so you will need to edit the downloaded XLSForm to -complete this action. - - - -## Step 2: Add Media Columns to your XLSForm - -The file names added to the XLSForm must match the file names you -gave to your image, audio, and -video files.
- -### Adding Image Media Columns: - -If you wish to add an **image** to a question, then type `media::image` as a -column header in the **survey** tab of your XLSForm. Type the image file name -along with an extension to the appropriate question just under the -`media::image` column header. - -Similarly, if you wish to add an **image** to a choice, then type -`media::image` as a column header in the **choices** tab of your XLSForm. Once -again type the image file name along with an extension to the appropriate choice -just under the `media::image` column header. - - - -### Adding Audio Media Columns: - -If you wish to add **audio** to a question, then type `media::audio` as a column -header in the **survey** tab of your XLSForm. Type the audio file name along -with an extension to the appropriate question just under the -`media::audio` column header. - -Similarly, if you wish to add **audio** to a choice, then type `media::audio` as -a column header in the **choices** tab of your XLSForm. Once again type the -audio file name along with an extension to the appropriate choice just under the -`media::audio` column header. - - - -### Adding Video Media Columns: - -If you wish to add video to a question, then type `media::video` as a column -header in the **survey** tab of your XLSForm. Type the video file name along -with an extension to the appropriate question just under the -`media::video` column header. - -Similarly, if you wish to add video to a choice, then type `media::video` as a -column header in the **choices** tab of your XLSForm. Once again type the video -file name along with an extension to the appropriate choice just under the -`media::video` column header. - - - -## Step 3: Handling Media Columns for Multiple Languages +KoboToolbox allows you to add media, including **images**, **audio files**, and **videos**, to notes, questions, and choices in your form. Adding media can increase user engagement and make forms more accessible for users with visual impairments or literacy barriers. -This step is for those who have multiple languages in their survey -project.
+Form media works with both [KoboCollect](https://support.kobotoolbox.org/kobocollect_on_android_latest.html) and [Enketo web forms](https://support.kobotoolbox.org/enketo.html). The following types of media files are currently supported: -You may have a survey with multiple languages and want to add various types of -media relevant to specific languages. In such cases, you could follow the -illustrations provided below. - -### Handling Media Column for Image Media: - -If you wish to add image to a question, then type `media::image` as a column -header in the **survey** tab of your XLSForm. Type the image file name along -with an extension to the appropriate question just under the -`media::image::Language (language code)` column header. - -Similarly, if you wish to add image to a choice, then type -`media::image::Language (language code)` as a column header in the **choices** -tab of your XLSForm. Once again type the image file name along with an extension -to the appropriate choice just under the -`media::image::Language (language code)` column header. - - - -### Handling Media Column for Audio Media: - -If you wish to add audio to a question, then type -`media::audio::Language (language code)` as a column header in the **survey** -tab of your XLSForm. Type the audio file name along with an extension to the -appropriate question just under the -`media::audio::Language (language code)` column header. - -Similarly, if you wish to add audio to a choice, then type -`media::audio::Language (language code)` as a column header in the **choices** -tab of your XLSForm. Once again type the audio file name along with an extension -to the appropriate choice just under the -`media::audio::Language (language code)` column header. - - - -### Handling Media Column for Video Media: - -If you wish to add video to a question, then type -`media::video::Language (language code)` as a column header in the **survey** -tab of your XLSForm. Type the video file name along with an extension to the -appropriate question just under the -`media::video::Language (language code)` column header. - -Similarly, if you wish to add video to a choice, then type -`media::video::Language (language code)` as a column header in the **choices** -tab of your XLSForm. Once again type the video file name along with an extension -to the appropriate choice just under the -`media::video::Language (language code)` column header. - - - -## Step 4: Replace XLSForm - -Upload and replace your XLSForm into the existing project or create a new -project. - - - -## Step 5: Upload Media Files - -Go to **SETTINGS>Media**. Upload all media files that have been referenced in -your form. - - +| Media | Files | +| :--- | :--- | +| Image | jpeg, png, svg | +| Audio | aac, aacp, flac, mp3, mp4, mpeg, ogg, wav, webm, x-m4a, x-wav | +| Video | 3gpp, avi, flv, mov, mp4, ogg, quicktime (qtff), webm, wmv | -Tip: Collect all media files that you will include in your survey -project. Provide a short file name for each of the media. File names -with a space (e.g., "red book") is not supported by the system. Hence, -you will need to either remove the space in between the names (e.g., -"redbook") or use '_' for a space (e.g., "red_book").
+This article covers the following topics: +- Adding media to survey questions +- Adding media to options choices +- Adding media to form translations +- Uploading media files to KoboToolbox -## Step 6: Deploy Form +
+ Note: The KoboToolbox Formbuilder does not currently support adding media files inside your forms. To add media, you will need to use XLSForm and then upload your XLSForm to KoboToolbox. To learn more about downloading and editing your form as XLSForm, see Using XLSForm with KoboToolbox.
+
+For hands-on practice with adding media attachments in XLSForm, see KoboToolbox Academy’s XLSForm Fundamentals Course.
+
+ Note: Previously, the format media::file_type was used for media column names (e.g., media::image, media::video, media::audio). The simplified format using only the media type without the media:: prefix is now more commonly adopted (e.g., image, video, audio).
+
+ Note: If a media file is not listed in a translation column, it will not be displayed for that language. +
+ +**survey worksheet** + +| type | name | label | video::English (en) | video::Chichewa (ny) | +| :--- | :--- | :--- | :--- | :--- | +| note | intro | Before you answer the form, watch the video below: | intro.mp4 | intro_ny.mp4 | +| survey | + +### Uploading media files to KoboToolbox -Each time new media files are added or changed, you need to -redeploy your project for the change to take effect. -You can see your new media when previewing your form -before redeployment.
+To upload the translated media files to KoboToolbox: +1. Go to your [KoboToolbox account](https://www.kobotoolbox.org/sign-up/). +2. In your KoboToolbox project, navigate to **SETTINGS > Media**. +3. Upload the media files that you have added to your XLSForm, ensuring the file name is exactly the same. +4. Deploy or redeploy your form to see media changes. -## Step 7: Collect Data ++ Note: To learn more about managing translations in XLSForm, see Adding translations in XLSForm. +
+ +## Troubleshooting -You can now go back to **Form>Collect Data**, and then click **Open** to check -if the media are properly displayed. +Animated GIF files are currently not supported by Enketo or -Collect android app. Aligning media to a desired form location (left -alignment, center alignment or the right alignment) is also not -possible.
+The media in an Enketo form will take more time to load if you -have large files. Try reducing the image, video or audio file sizes -before uploading them to the server.
+You can access the XLSForm here and the media files here that were used -in this article.
diff --git a/source/metadata_xls.md b/source/metadata_xls.md new file mode 100644 index 000000000..d7ff17d0a --- /dev/null +++ b/source/metadata_xls.md @@ -0,0 +1,53 @@ +# Form metadata in XLSForm + +Metadata questions automatically gather information about the data collection process, such as the date, time, and device used, without requiring input from the respondent. + +Metadata questions are not visible to respondents. The information collected in the background can be used for auditing, to ensure data integrity, and to support data analysis. + ++Note: This article focuses on adding metadata questions in XLSForm. To learn about adding metadata questions in the KoboToolbox Formbuilder, see Form settings and metadata. +
+ +## Adding metadata questions in XLSForm + +Metadata questions are added to XLSForm in the same way as any other question types: + +1. Enter the metadata question **type** in a new row, using the exact name shown [in the table below](https://support.kobotoolbox.org/metadata_xls.html#available-metadata-questions-in-xlsform). +2. Include a question **name**. +3. Question **labels** are not required, as they are not displayed in the form. + +**survey worksheet** + +| type | name | label | +|:-----|:-----------|:-------------| +| start | start_time | | +| end | end_time | | +| survey | + +## Available metadata questions in XLSForm + +Available metadata questions in XLSForm include: + +| Type | Description | +|:--------------------|:-------------| +| `start` | Records the exact time and date when a submission is started. | +| `end` | Records the date and time when a submission is finalized. | +| `today` | Records the date of the submission. | +| `deviceid` | Records the unique identification of the device or browser used to collect data. Thedeviceid is automatically generated and cannot be modified by users.deviceid is updated whenever the app is reinstalled on a device. In Enketo, the deviceid resets any time a new browser window is used. |
+| `username` | In KoboCollect, records the username saved in the KoboCollect app settings. If no username is set, it records the one used to sign in to the server.trigger column of the background-geopoint question. |
+| `background-audio` | Records audio in the background while a form is open. To learn more about this feature, see Recording interviews with background audio recording. |
+| `audit` | Captures a detailed log of the interview process, including start time, end time, location, and user actions during the entire data collection process. This metadata question is not supported in Enketo.+To learn more about building forms in XLSForm, see Getting started with XLSForm. +
+ +## Defining option choices in XLSForm +Option choices are defined in the `choices` worksheet of your XLSForm. The `choices` worksheet includes three mandatory columns: + +| Column | Description | +| :--------- | :-------- | +| `list_name` | Unique identifier for a list of option choices, which links the question in the `survey` worksheet to its choice list in the `choices` worksheet. | +| `name` | Short, unique name used to refer to each option choice. | +| `label` | Choice text as it will be displayed in the form. | + +To define a list of option choices in XLSForm: + +1. In the `choices` worksheet, enter the **name of the list of choices** in the `list_name` column. +2. Enter a short `name` and a `label` for each option, using the same `list_name` for all options in the list. + +**choices worksheet** + +| list_name | name | label | +| :--------- | :--------- | :--------- | +| marital_options | single | Single | +| marital_options | married | Married | +| marital_options | separated_divorced | Separated/Divorced | +| marital_options | widowed | Widowed | +| choices | + +3. In the `survey` worksheet, add your survey question. In the `type` column, enter the question type followed by a single space and then the `list_name` for your list of choices. + - A list of choices can be reused across multiple questions in the `survey` worksheet. + +**survey worksheet** + +| type | name | label | +| :--------- | :--------- | :--------- | +| acknowledge | consent | Do you agree to proceed with the interview? | +| select_one marital_options | marital_status | What is your marital status? | +| survey | + + +## Best practices for defining choice names + +When data is downloaded in [XML values and headers format](https://support.kobotoolbox.org/export_download.html#value-and-header-format), each question appears as its own variable or column in the dataset. The values inside each column are the **choice names** defined in your `choices` worksheet, rather than the full labels shown to respondents. This format is recommended for analysis, since it provides short, consistent variable names and coded values that are easier to work with than full question or option labels. + +When defining choice names: +- Use only **letters, numbers, and underscores**. Spaces and special characters are not allowed. +- Avoid very long or complex strings of text, as these values will appear in your exported dataset and may be used in [form logic](https://support.kobotoolbox.org/form_logic_xls.html). +- Keep names **consistent** across lists to facilitate data analysis. + + +## Managing choice lists in XLSForm + +### Reusing choice lists +Using **`list_name`** in XLSForm allows you to easily **reuse choice lists** across multiple questions, eliminating the need for manual re-entry. For example, you can create a `yes_no` choice list and apply it to all your Yes/No questions. This helps build forms more efficiently and consistently. + +### Translating choice lists + +XLSForm simplifies the translation of choice lists. You can add multiple labels for different languages, with each translation in a separate **`label`** column. The underlying choice names remain the same, which ensures the exported dataset is consistent across translations and facilitates analysis. + ++To learn more about adding translations in XLSForm, see Adding translations in XLSForm. +
+ +### Media files as option choices + +In addition to text, option choices in XLSForm can also be **media files**, such as images, audio, or video. This enhances the survey experience by providing visual or auditory cues to respondents. + ++To learn more about using media files as option choices, see Adding media to an XLSForm. +
+ +### Filtering choice lists + +XLSForm allows you to filter option choice lists based on responses to previous questions. This feature, known as **choice filters**, can be used in various ways. For example, they can be used for **cascading select questions**, where the choice list for a child question (e.g., cities) is filtered based on the response to a parent question (e.g., country). They can also be used for filtering a multiple choice question to display only options selected in a previous question. + ++To learn more about filtering choice lists in XLSForm, see Adding choice filters in XLSForm. +
+ +### Duplicating choice names + +Within a given list of option choices, **choice names must be unique**. However, the same choice name can be reused across different lists. For instance, a `yes_no` choice list and a `yes_no_maybe` choice list can both include `yes` and `no` choice names. + +By default, deploying a form with repeated choice names in the same list will result in an error. However, when using choice filters, you may need to allow duplicate choice names within a list. To enable this, activate the `allow_choice_duplicates` setting in your `settings` worksheet. + ++For more information, see Form settings in XLSForm. +
+ +### Managing long choice lists + +For very large choice lists, containing hundreds or thousands of options, it is recommended to use `select_one_from_file` or `select_multiple_from_file` question types, which link a survey question to an **external file** containing the list of choices. This approach is more efficient than manually entering choices inside the XLSForm, helps avoid slow loading times and large XLSForms, and simplifies managing or editing extensive option sets. + ++To learn more about external choice lists in XLSForm, see Selecting options from an external file. +
diff --git a/source/pull_data_kobotoolbox.md b/source/pull_data_kobotoolbox.md index d3e40807f..a92c359cf 100644 --- a/source/pull_data_kobotoolbox.md +++ b/source/pull_data_kobotoolbox.md @@ -1,38 +1,110 @@ -# Pull Data Functionality in KoboToolbox +# Pulling data from an external CSV **Last updated:** 18 Aug 2025 +The `pulldata()` function in XLSForm lets you dynamically retrieve information from an external CSV file while completing a form. This allows you to reference existing datasets and automatically pull in related details, avoiding the need for enumerators to re-enter the same information. + +For example, you can use `pulldata()` to: +- **Auto-fill related information:** When an ID, code, or key is entered, automatically retrieve linked details such as a name, category, or description. +- **Preload background data:** Load information from external files so enumerators only need to collect new or updated data. + +Using `pulldata()` helps reduce errors, saves time during data collection, and ensures that forms remain consistent with external reference datasets. This function is supported in both the KoboCollect Android app and Enketo web forms. We recommend using XLSForm to set up the `pulldata()` function. + +This article covers the following steps for pulling data from an external CSV: +- Setting up your external CSV +- Setting up your XLSForm +- Uploading your external CSV to KoboToolbox + +## Setting up your external CSV + +To use `pulldata()`, first prepare an external CSV file containing the reference data you want to retrieve. Each row should represent a unique record (for example, a participant, location, or item) and the file should include at least two columns. One column must contain the **index variable** that matches the values entered in your form. + +The **index variable** acts as the [primary key](https://en.wikipedia.org/wiki/Primary_key) that links your XLSForm to the external CSV. It should be a unique identifier that exists in both files, such as a participant ID, a district name, or another matching code. + +The remaining columns can include any additional details you want to retrieve, such as names, categories, or descriptions. Ensure the CSV file is clean, consistently formatted, and saved with the `.csv` extension. + +## Setting up your XLSForm + +Once you have set up your external CSV, configure your XLSForm in the following way: + +1. Ensure your XLSForm includes a question that serves as the **index variable**. +2. Add a `calculate` field to your survey. Give the field a `name`. +3. In the `calculation` column, use the **pulldata()** function to specify which field in the CSV to pull from. Use the following syntax: `pulldata('csv','pull_from', 'csv_index', '${survey_index}')`. + - `csv` is the name of the CSV file, without the extension. + - `pull_from` refers to the column in your CSV file that contains the data you want to import into your form. + - `csv_index` is the column in your CSV file that contains the **index variable.** + - `survey_index` is the name of the question in your survey that contains the **index variable.** + + **survey worksheet** + + | type | name | label | calculation | +|:-----------|:------------------|:-------------------------------------------|:-------------| +| text | respondent_id | Respondent ID | | +| calculate | eligibility_status | | pulldata('eligibility', 'status', 'ID', 'respondent_id') | +| note | eligibility_not | Respondent is ${eligibility_status} for the study. | | +| survey | + +In the example above, the calculation retrieves the value from the `status` column of the `eligibility.csv` file, in the row where the `ID` in the CSV matches the ID entered in the `respondent_id` question of your form. + +
+Note: After using the pulldata() function to retrieve external CSV data, you can reference that field in subsequent skip logic conditions, constraints, and labels, just like any other field or calculation.
+
int() or number() functions to the retrieved value in your XLSForm.
+' in front of the date to avoid automatic date formatting in Excel.
+
+ Note: This article focuses on defining question options in XLSForm. To learn about question options in the KoboToolbox Formbuilder, see Using the question options.
+
+For hands-on practice with question options in XLSForm, see KoboToolbox Academy’s XLSForm Fundamentals Course.
+
+Note: Question hints can also be translated into multiple languages. For more information on translating forms, see Adding translations in XLSForm. +
+ +### Displaying guidance hints in KoboCollect + +In Enketo web forms, guidance hints appear in a collapsible **More Details** section. In KoboCollect, they are hidden by default, but you can [change your project settings](https://support.kobotoolbox.org/kobocollect_settings.html#form-management-settings) to always display them or show them in a collapsible section. + +To display guidance hints in KoboCollect, follow the steps below: +1. Tap the **Project icon** in the top right corner of your screen. +2. Tap **Settings**. +3. Under **Form management**, select **Show guidance for questions**. +4. Choose a display option: **No**, **Yes - always shown**, or **Yes - collapsed**. + ++Note: Guidance hints are always displayed in printed forms. +
+ +## Required questions + +By default, questions in a form are optional. Setting a question as **required** makes it mandatory for the respondent to answer. This can be useful for ensuring submissions are complete and avoiding missing data. + ++Note: Skip logic conditions take precedence over required settings, meaning that if a required question is hidden by skip logic, it is no longer mandatory to answer. +
+ +To set a question as required in XLSForm: +1. Add a `required` column to the `survey` worksheet. +2. In the `required` column, enter any of the following: **TRUE**, **true**, or **yes**. +3. For optional questions, leave the `required` column blank or enter any of the following: **FALSE**, **false**, or **no**. + +If a respondent does not answer a required question, they will not be able to proceed to the next page or submit the form. The default required message "This field is required" will be displayed. + +
+Note: Only questions that require an input should be marked as required in your XLSForm. If note questions are marked as required, you will not be able to continue or submit the form.
+
+Note: Custom form logic can be used to make a question required or optional based on a previous response. To learn more about condition-based required logic, see Adding required logic in XLSForm. +
+ +## Default responses + +A **default response** populates a question with a predefined answer based on a common or expected response. The default response can be fixed or [dynamically determined](https://support.kobotoolbox.org/question_options_xls.html#setting-dynamic-default-responses) based on the response to a previous question. + +The default response will be recorded as the final answer when the form is submitted **unless modified by the respondent** during data collection. To prevent respondents from editing a default response, add a **read-only** column and set it to **TRUE**. + ++Note: Although default responses can make data collection more efficient by prepopulating the form with expected or common responses, they also risk introducing bias or errors in the data, and should be used with caution. +
+ +To set a fixed default response in XLSForm: +1. Add a **default** column to the `survey` worksheet. +2. Enter the default response, following the [appropriate format](https://support.kobotoolbox.org/question_options_xls.html#default-response-format) for the question type. + +**survey worksheet** + +| type | name | label | default | +| :--- | :--- | :--- | :--- | +| text | name | What is your name? | John Doe | +| integer | age | What is your age? | 50 | +| select_one marital_options | marital_status | What is your marital status? | married | +| select_multiple income_options | income_sources | What are your sources of income? | formal_work farm_business | +| date | dob | When were you born? | 1990-03-25 | +| date | interview_date | When was this interview conducted? | today() | +| survey | + +### Default response format + +The format of the default response depends on the question type and the data being collected: + +| Question type | Default response format | +| :--- | :--- | +| integer | Number | +| text | Text (without quotation marks) | +| select_one | Choice **name** (as defined in the choices worksheet) | +| select_multiple | Choice **name(s)**, separated by a **space** if there are multiple | +| date | Date in the YYYY-MM-DD format. If needed, prefix the date with a single quote (') in Excel to avoid potential formatting issues. | + +### Setting dynamic default responses + +Default responses entered in the `default` field must be fixed values. To set a **dynamic default response** based on a previous answer, use the **calculation** and **trigger** columns instead of the `default` column: +1. In the `calculation` column, enter the **reference to the question** that will dynamically populate the default response. +2. In the `trigger` column, enter the question that will activate the calculation. + - Typically, this would be the same question referenced in the `calculation` column, so that any change to the trigger question will also update the default response. + +**survey worksheet** + +| type | name | label | calculation | trigger | +| :--- | :--- | :--- | :--- | :--- | +| text | hh_name | Name of the head of household | | | +| text | phone | Household phone number | | | +| text | phone_name | Name of the phone owner | ${hh_name} | ${hh_name} | +| survey | + + +## Question parameters + +Question parameters in XLSForm allow you to fine-tune how your questions behave beyond basic settings. + +To add question parameters in XLSForm: +1. Add a **parameters** column to the `survey` worksheet. +2. Enter the appropriate [parameter](https://support.kobotoolbox.org/question_options_xls.html#common-question-parameters) for your question type. +3. Some parameters can be combined and applied to the same question. Combine parameters by entering them in the same cell and separating them with a space. + +**survey worksheet** + +| type | name | label | parameters | +| :--- | :--- | :--- | :--- | +| select_one reasons | reasons | Please select all reasons that apply. | randomize=true | +| range | phone | Please select a number between 1 and 5. | start=1 end=5 step=1 | +| survey | + +### Common question parameters + +Different question types in `XLSForm` have different parameters. The most common parameters are: + +| Parameter | Question type | Description | +| :--- | :--- | :--- | +| randomize=true | rank, select_one, select_multiple | Randomizes the order of option choices | +| start=1 end=5 step=1 | range | Defines the minimum value, maximum value, and interval between numbers | +| capture-accuracy=20 | geopoint | Specifies the minimum acceptable GPS accuracy (in meters) for automatically capturing a location | +| warning-accuracy=50 | geopoint | Triggers a warning message if the GPS accuracy is not within the specified accuracy threshold | +| max-pixels=480 | image | Limits the maximum pixels for a photo, to reduce the image file size and improve upload speed | +| quality=low | audio | Captures a lower quality audio recording | +| quality=voice-only | audio | Captures the lowest quality audio recording | + +## Additional question options + +XLSForms can include additional columns in the survey worksheet for more advanced forms and functionalities. A few are listed below. + +| XLSForm column | Description | +| :--- | :--- | +| read_only | If `yes` is entered in the `read_only` field, the question cannot be edited by the respondent. `read_only` fields can be combined with `default` or `calculation` fields to display information to the respondent. | +| trigger | The trigger column can be used to run a calculation only when the response to another visible question in the form is changed. For more information, see XLSForm documentation. | +| body::accept | To limit the accepted file types for `file` questions, specify file extensions in the `body::accept` column, separated by a comma (e.g., .pdf, .doc). | + +Other columns can also be added to incorporate form logic into your XLSForm. + ++ To learn more about adding form logic, see Adding skip logic in XLSForm, Adding constraints in XLSForm, Adding required logic in XLSForm, Adding choice filters in XLSForm, and Adding calculations in XLSForm. +
diff --git a/source/question_types_xls.md b/source/question_types_xls.md new file mode 100644 index 000000000..bed97b9f3 --- /dev/null +++ b/source/question_types_xls.md @@ -0,0 +1,128 @@ +# Question types in XLSForm +**Last updated:** Oct 10, 2025 + +When adding questions to an XLSForm, you'll need to choose the appropriate **question type**. The question type will depend on the kind of information you want to collect: some question types are more suited for text, others for numbers, dates, or multiple choice inputs. + +The question type in XLSForm is entered in the **type** column of the **survey** worksheet. Always use the exact spelling and letter case. You can add additional [appearances](https://support.kobotoolbox.org/appearances_xls.html) to most question types to modify their display or functionality. + ++Note: While XLSForm is fully integrated within KoboToolbox, some question types have different names and functionalities in the Formbuilder than they do in XLSForm. +
+ +This article covers available question types in XLSForm, including their descriptions and Formbuilder equivalents. Links are provided at the end of each section for more information on question type functionalities and appearances during data collection. + ++To learn more about building forms in XLSForm, see Getting started with XLSForm. +
+ +### Select question types + +Select questions allow respondents to choose from predefined options. For `select_one`, `select_multiple`, and `rank` questions, [option choices](https://support.kobotoolbox.org/option_choices_xls.html) are defined in the **choices** worksheet of the XLSForm. + +| XLSForm type | Description | Formbuilder equivalent | +| :--- | :--- | :--- | +| `select_one` | Allows respondents to select one option from a predefined list. | Select One | +| `select_multiple` | Allows respondents to select multiple options from a predefined list. | Select Many | +| `rank` | Allows respondents to rank items or options in a choice list. | Ranking | +| `acknowledge` | A single checkbox that respondents can select to acknowledge their agreement with a statement. | Acknowledge | +| `select_one_from_file` | Allows respondents to select one option from a predefined list, stored in an external CSV file. | Select One From External File | +| `select_multiple_from_file` | Allows respondents to select multiple options from a predefined list, stored in an external CSV file. | Select Many From External File | + + ++To learn more about select question types in KoboToolbox, see Select One and Select Many question types, Rating vs Ranking question types, Acknowledge question type, and Select One or Many From External File question types. +
+ + +### Numeric question types + +Numeric questions are used to collect whole numbers, decimal numbers, or values within a specified range. + +| XLSForm type | Description | Formbuilder equivalent | +| :--- | :--- | :--- | +| `integer` | Allows respondents to input whole numbers. | Number | +| `decimal` | Allows respondents to input numbers that may contain decimal points. | Decimal | +| `range` | Allows respondents to select a numeric value within a specified range constrained by minimum and maximum values, configured in the **parameters column**. | Range | + + ++To learn more about numeric question types in KoboToolbox, see Number, Decimal, and Range question types. +
+ + +### Text and note question types + +Text questions are used to collect open-ended responses, while note questions provide information or give instructions to respondents. + +| XLSForm type | Description | Formbuilder equivalent | +| :--- | :--- | :--- | +| `text` | Provides a text box to collect open-ended responses when choices cannot be easily predefined, such as names, opinions, or detailed descriptions. | Text | +| `note` | Provides information to the respondent without requiring any input, such as instructions or explanations. | Note | + + ++To learn more about text and note question types in KoboToolbox, see Text and Note question types. +
+ +### Media question types + +Media questions allow respondents to upload or record images, audio, and video files, or to scan barcodes directly into their forms. + +| XLSForm type | Description | Formbuilder equivalent | +| :--- | :--- | :--- | +| `image` | Allows respondents to upload images or take photos when using the KoboCollect app. The quality of image files can be adjusted in the **parameters** column. | Photo | +| `audio` | Allows respondents to upload an audio file or record audio as a response to a specific question. The quality of audio files can be adjusted in the **parameters** column. | Audio | +| `video` | Allows respondents to upload videos or record videos when using the KoboCollect app. | Video | +| `file` | Allows respondents to upload files, such as text files, spreadsheets, and PDF files. Accepted file types can be restricted by specifying file extensions in the **body::accept** column (e.g., `.pdf, .docx`). | File | +| `barcode` | Scans a QR code to collect embedded information using the device's camera in KoboCollect. | Barcode | +| `background-audio` | Collects audio continuously while the form is open. Audio recording begins when the form is opened and continues until the form is closed. | Background Audio Recording | + + ++To learn more about media question types in KoboToolbox, see Media question types, Barcode/QR code question type, and Recording interviews using background audio recording. +
+ +### GPS question types + +GPS questions are used to capture the geographic coordinates of a location, path, or area directly within your forms. + +| XLSForm type | Description | Formbuilder equivalent | +| :--- | :--- | :--- | +| `geopoint` | Collects a single geographic location, such as the coordinates of a specific school, clinic, or house. Default accuracy and warning accuracy can be configured in the **parameters** column. | Point | +| `geotrace` | Records multiple GPS points that form a line, for example to track a path, trace a route, or map a drain. | Line | +| `geoshape` | Collects points that form an enclosed area, such as a plot of land or a field. | Area | + + ++To learn more about GPS question types in KoboToolbox, see GPS question types. +
+ +### Date and time question types + +Date and time questions are used to capture specific calendar dates, times, or both in a single response. + +| XLSForm type | Description | Formbuilder equivalent | +| :--- | :--- | :--- | +| `date` | Captures a specific calendar date, typically in the format of day, month, and year. | Date | +| `time` | Captures a specific time in hours and minutes. | Time | +| `datetime` | Captures both a date and a time in a single combined response. | Date and Time | + + ++To learn more about date and time questions in KoboToolbox, see Date and Time question types. +
+ +### Calculate and hidden question types + +Calculate and hidden questions are used to perform automatic calculations within a form based on previous responses or to store predefined values. + +| XLSForm type | Description | Formbuilder equivalent | +| :--- | :--- | :--- | +| `calculate` | Automatically performs calculations within a form based on responses to previous questions. | Calculate | +| `hidden` | Stores predefined values that are not visible to the respondent. The value is stored in the **default** column. | Hidden | + +To learn more about calculations in the Formbuilder, see Calculate question type. To learn more about calculations in XLSForm, see Adding calculations in XLSForm. + ++For hands-on practice with different question types XLSForm, see KoboToolbox Academy's XLSForm Fundamentals Course. +
diff --git a/source/repeat_groups_xls.md b/source/repeat_groups_xls.md new file mode 100644 index 000000000..4f03d2e8c --- /dev/null +++ b/source/repeat_groups_xls.md @@ -0,0 +1,182 @@ +# Repeat groups in XLSForm + +Repeat groups in XLSForm allow you to ask the same set of questions multiple times within a form. This is especially useful when collecting similar information about several people, items, or events. + +For example, if you're gathering details about each member of a household, you can use a repeat group to ask the same demographic questions for every individual. + +This article covers the following topics: +- Creating a repeat group +- Setting repeat counts to limit the number of repetitions +- Counting the number of repetitions within a repeat group +- Retrieving values from repeat groups + ++Note: This article focuses on repeating groups in XLSForm. To learn about repeating groups in the KoboToolbox Formbuilder and to preview repeat groups in action, see Grouping questions and repeating groups. +
+ +## Creating a repeat group + +To create a repeat group in XLSForm: + +1. In the `type` column of the survey worksheet, enter **begin_repeat** to indicate the start of the repeat group. +2. In the `name` column of the **begin_repeat** row, enter the unique identifier for the group. +3. In the `label` column, enter the title of the group as you want it displayed in the form. The label is optional and can be left blank. +4. Enter each question of the group in its own row, as you normally would. +5. In a new row after the repeating questions, enter **end_repeat** in the `type` column to indicate the end of the repeat group. + - In the **end_group** row, leave the `name` and `label` columns blank. + +**survey worksheet** + +| type | name | label | +| :--- | :--- | :--- | +| **begin_repeat** | household_members | Household Members | +| text | name | What is the person's name? | +| integer | age | How old are they? | +| select_one yn | married | Are they married? | +| **end_repeat** | | | +| survey | + +Repeat groups function similarly to question groups. With repeat groups, you can: + +- Use the **field-list** appearance to [display all questions](https://support.kobotoolbox.org/grouping_questions_xls.html#appearance-settings-for-question-groups) on the same page. +- Add [skip logic](https://support.kobotoolbox.org/grouping_questions_xls.html#applying-skip-logic-to-question-groups) to repeat groups in the **relevance** column. +- Create **nested** repeat groups, where one repeat group is added [inside another](https://support.kobotoolbox.org/grouping_questions_xls.html#nested-groups). + ++ Note: Adding repeat groups to your form creates a different data structure compared to standard variables or groups. When you download your data in .xlsx format, you will find a separate sheet for each repeat group. For more information on exporting and using repeat group data, see Managing repeat group data. +
+ +## Setting repeat counts + +By default, repeat groups can be repeated as many times as needed. To limit the number of times a repeat group is repeated in the form, you can set a repeat count. The **repeat count** can be either a fixed number or dynamically determined based on a previous response. + +To set a fixed number of repetitions: + +1. Add a **repeat_count** column in the `survey` worksheet. +2. Input a number in the **repeat_count** column. + +**survey worksheet** + +| type | name | label | repeat_count | +| :--- | :--- | :--- | :--- | +| begin_repeat | participant_profile | Participant profile | 3 | +| text | name | Name | | +| select_one gender | gender | Gender | | +| integer | age | Age | | +| end_repeat | | | | +| survey | + +To dynamically determine the number of repetitions based on a previous response: + +1. Add a **repeat_count** column in the `survey` worksheet. +2. Enter the question reference in the **repeat_count** column. + - The referenced question must be an `integer` question type. + + **survey worksheet** + +| type | name | label | repeat_count | +| :--- | :--- | :--- | :--- | +| integer | participants | Total number of training participants | | +| begin_repeat | participant_profile | Participant profile | ${participants} | +| text | name | Name | | +| select_one gender | gender | Gender | | +| integer | age | Age | | +| end_repeat | | | | +| survey | + ++ Note: Inside the repeat_count column, you can also include advanced conditional statements to determine if repetitions will continue. For more information, see ODK documentation. +
+ +## Counting number of repetitions inside a repeat group + +When using repeat groups, you may need a field that counts how many times the group has been repeated. This can be useful for calculations or form logic. For example, you can apply skip logic after a specific repetition or dynamically include the repeat number in a question label (e.g., Child 1, Child 2). + +To count how many times a repeat group has been repeated: +1. Add a **calculate** question inside the repeat group. +2. Enter `position(..)` in the **calculation** column. + +This variable stores the current repeat index. You can use it in form logic or to create dynamic question labels. + +**survey worksheet** + +| type | name | label | calculation | relevance | +| :--- | :--- | :--- | :--- | :--- | +| begin_repeat | profile | Participant profile | | | +| calculate | number | | **position(..)** | | +| note | instructions | Answer the questions below for each participant. | | **${number} = 1** | +| text | name | Name of participant **${number}** | | | +| select_one gender | gender | Gender of participant **${number}** | | | +| integer | age | Age of participant **${number}** | | | +| end_repeat | | | | | +| survey | + +## Counting total number of repeat group repetitions + +You can also add a separate question outside the repeat group to count the total number of repetitions. This is useful, for example, to confirm the number of participants or children listed in the repeat group. + +To count how many times a repeat group was filled in: +1. Add a **calculate** question after the repeat group. +2. In the **calculation** column, enter `count(${repeat_group_name})`, where `repeat_group_name` is the name of the repeat group. + +This variable stores the total number of group repetitions. You can use it in calculations or to create dynamic question labels in your form. + +**survey worksheet** + +| type | name | label | calculation | +| :--- | :--- | :--- | :--- | +| begin_repeat | children | Children roster | | +| text | name | Name | | +| select_one gender | gender | Gender | | +| integer | age | Age | | +| end_repeat | | | | +| calculate | count_children | | **count(${children})** | +| acknowledge | confirm_children | Confirm that there are **${count_children}** children in the household. | | +| survey | + +## Retrieving values from repeat groups + +Advanced forms often use [question referencing](https://support.kobotoolbox.org/form_logic_xls.html#question-referencing) to include responses from earlier questions in question labels, calculations, or skip logic. You can also use question referencing **within repeat groups** or to refer to repeated data elsewhere in your form. + +Within a repeat group, you can reference a response from another question in the same repetition using question referencing, as shown below. + +**survey worksheet** + +type | name | label | +| :--- | :--- | :--- | +| begin_repeat | children | Children roster | +| text | name | What is the child's name? | +| integer | age | How old is ${name}? | +| select_one gender | married | What is ${name}'s gender? | +| end_repeat | | | +| survey | + +Outside a repeat group, you can retrieve data from the repeat group for use in form logic or question labels: + +1. Add a **calculate** question after your repeat group. +2. Include one of the formulas listed below in the **calculation** column. +3. The **calculate** question stores the retrieved value, which you can then use in form logic or question labels. + +**Formulas to retrieve data from repeat groups** + +| Formula | Description | +| :--- | :--- | +| `max(${question-name})` | Retrieves the maximum value entered for one question in the repeat group. | +| `min(${question-name})` | Retrieves the minimum value entered for one question in the repeat group. | +| `sum(${question-name})` | Computes the sum of numerical values entered for one question in the repeat group. | +| `join('; ', ${question-name})` | Lists all responses to a given question inside a repeat group, separated by a semi-colon. | +| `indexed-repeat(${question-name}, ${repeat-name}, n)` | Retrieves the value for `${question-name}`, in the repeat group called `${repeat-name}`, in the nth repetition. | + +**survey worksheet** + +| type | name | label | calculation | +| :--- | :--- | :--- | :--- | +| begin_repeat | children | Children roster | | +| text | name | Name | | +| select_one gender | gender | Gender | | +| integer | age | Age | | +| end_repeat | | | | +| calculate | max_age | | **max(${age})** | +| acknowledge | confirm_age | Confirm that the oldest child in the household is **${max_age}** years old. | | +| survey | + diff --git a/source/required_logic_xls.md b/source/required_logic_xls.md new file mode 100644 index 000000000..c935e2d43 --- /dev/null +++ b/source/required_logic_xls.md @@ -0,0 +1,68 @@ +# Adding required logic in XLSForm + +Required logic allows you to make a question mandatory if specific conditions are met. For example, you can require a phone number question only if respondents agree to be contacted in the future. This option provides more control than simply marking a question as always required or always optional. + ++ To learn more about required questions and how to customize the message shown to respondents when they leave a required question unanswered, see Using question options in XLSForm. +
+ +This article explains how to add required logic conditions in XLSForm, including making a question required based on whether another question was answered. + +
+ Note: This article focuses on adding required logic in XLSForm. To learn about adding required logic in the KoboToolbox Formbuilder, see Using the question options.
+
+ For hands-on practice with required logic in XLSForm, see KoboToolbox Academy’s XLSForm Fundamentals Course.
+
+To learn more about building form logic expressions in XLSForm, see Introduction to form logic in XLSForm. +
+ +## Adding required logic based on whether a question was answered + +In addition to setting required logic for a specific response, you can also base it on whether a question was answered or left blank. This is useful when you want to ensure that at least one of two questions is required. + +Unanswered questions are treated as empty strings, noted as two single apostrophes `''`. The following required logic conditions can be used: + +| Required logic condition | Description | +|:---------------------------|:-------------| +| `${reference_question} != ''` | Require only if `reference_question` is answered (not blank). | +| `${reference_question} = ''` | Require only if `reference_question` is unanswered (blank). | + +**survey worksheet** + +| type | name | label | required | +|:------|:--------|:----------------------------------------------------|:-------------| +| note | contact | Please provide your phone number or email address below. | | +| text | phone | Phone number | | +| text | email | Email address | ${phone} = '' | +| survey | diff --git a/source/select_from_file_xls.md b/source/select_from_file_xls.md new file mode 100644 index 000000000..13b75891c --- /dev/null +++ b/source/select_from_file_xls.md @@ -0,0 +1,86 @@ +# Selecting options from an external file + +**Select from file** questions allow you to use a list of choice options stored in an external file instead of defining them directly in your form. There are two types: `select_one_from_file` for selecting a **single choice**, and `select_multiple_from_file` for selecting **multiple choices**. + +Using a separate file for your choice list makes it easier to manage long lists, reuse them across multiple forms, and update options when needed. Supported file formats include CSV, XML, and GeoJSON. + +This article explains how to format your external file, set up your XLSForm to use **select from file** questions, and upload your external file to KoboToolbox. + +
+Note: This article focuses on adding select from file questions in XLSForm. To learn about adding select from file questions in the KoboToolbox Formbuilder, see Select One or Many From External File Question Type.
+
+ For hands-on practice with select from file questions in XLSForm, see KoboToolbox Academy’s XLSForm Fundamentals Course.
+
+ To learn more about formatting XML or GeoJSON files, see XLSForm and ODK documentation. GeoJSON files are primarily used for selecting options from a map. +
+ +For CSV files, the structure is similar to the choices worksheet in an XLSForm. It should include the `name` and `label` columns, but the `list_name` column is not needed. + +**External CSV file** + +| name | label | +|:--------|:----------| +| option1 | Option 1 | +| option2 | Option 2 | +| option3 | Option 3 | + +If your file uses different names for the choice name and label, you can specify this in your XLSForm (see instructions [below](https://support.kobotoolbox.org/select_from_file_xls.html#configuring-choice-name-and-label-columns)). + ++Note: Use short, simple file names for your external files, avoiding spaces or special characters. The file name will be used in your XLSForm to link questions to their choice lists. If you use multiple external files, make sure each one has a unique name, even if they use different file types. +
+ +## Setting up your XLSForm + +To add a select from file question to your XLSForm: +1. In the `type` column of the `survey` worksheet, enter the select from file question type (`select_one_from_file` or `select_multiple_from_file`). +2. In the same cell, instead of the choices `list_name`, add a single space and the name of the external file, including the file extension. + - For example: `select_one_from_file households.csv` + +**survey worksheet** + +| type | name | label | +|:-------------------------|:-----|:----------------| +| select_one_from_file households.csv | hh | Select household | +| survey | + +### Configuring choice name and label columns + +If your external file uses different column names instead of `name` and `label`: +1. Add a **parameters** column to the `survey` worksheet +2. In the select from file question row, specify the custom names with the `value` and `label` parameters. + - `value` represents the choice **name**. + - `label` represents the choice **label**. + +**survey worksheet** + +| type | name | label | parameters | +|:-------------------------|:-----|:-----------------|:-----------------------------| +| select_one_from_file households.csv | hh | Select household | value=housenum label=housename | +| survey | + +## Uploading the external file to KoboToolbox + +When uploading your XLSForm to KoboToolbox, you must also upload the external file that contains your list of choices: +1. In KoboToolbox, navigate to the project **SETTINGS** page. +2. In the **Media** tab, upload the external file. Ensure the file name matches exactly the file name specified in the XLSForm. + +To update your list of choices, edit the external file as needed, re-upload it to KoboToolbox, and redeploy your form. + + + +## Troubleshooting + +label column. Any additional translated label columns will be ignored in Enketo or will cause an error in KoboCollect. For forms that include translations, use internal choice lists instead, or set up multiple select from file questions using skip logic to pull from different files depending on the form language.
+
+Note: The KoboToolbox Formbuilder does not support map-based selection for the select_one question type. To use this feature, configure it in an XLSForm and upload the form to KoboToolbox.
+
+ To learn more about downloading and editing your form as XLSForm, see Using XLSForm with KoboToolbox.
+
+Note: To obtain your GPS coordinates in the correct format, you can use this KoboToolbox form. It lets you select points on a map and automatically generates the corresponding GPS coordinates in ODK format. +
+ +If you are using a GeoJSON file to provide GPS coordinates, follow the [GeoJSON format](https://docs.getodk.org/form-datasets/#selects-from-geojson) to specify the feature `geometry` . + ++ For an example of map-based select questions, see this sample XLSForm. External choice files for upload to KoboToolbox are available here (CSV), here (GeoJSON), and here (XML). To learn more about using external choice files, see Selecting options from an external file. +
+ +## Adding choice properties + +You can further customize your map by adding choice properties in the `choices` worksheet or external choice file. + +Available choice properties include: + +| Choice property | Description | +|:----------------|:------------| +| `info` | Text description of the choice. | +| `marker-color` | HEX color for the geopoint marker. | +| `marker-symbol` | Single character, symbol, or emoji displayed on the geopoint marker. | +| `stroke` | HEX color for the geotrace line or the geoshape polygon outline. | +| `stroke-width` | Width of the geotrace line or the geoshape polygon outline (e.g., 5 or 6.5). | +| `fill` | HEX color for the polygon interior. The fill color is displayed with fixed transparency. | + +To add properties in the `choices` worksheet of your XLSForm: + +1. Add a column with the appropriate property name (e.g., `info`, `stroke`, or `fill`). +2. For each choice, enter the corresponding value (e.g., a text description or a HEX code) + +**choices worksheet** + +| list_name | name | label | geometry | info | +|:----------|:-----|:-------|:------------------|:---------------------------| +| cities | 1 | Warsaw | 52.2297 21.0122 0 0 | Capital of Poland | +| cities | 2 | Berlin | 52.5200 13.4050 0 0 | Capital of Germany | +| cities | 3 | Paris | 48.8566 2.3522 0 0 | Capital of France | +| cities | 4 | Kyiv | 50.4501 30.5234 0 0 | Capital of Ukraine | +| cities | 5 | Prague | 50.0755 14.4378 0 0 | Capital of Czech Republic | +| choices | + +If you are using a GeoJSON file to provide GPS coordinates, follow the [GeoJSON format](https://docs.getodk.org/form-datasets/#selects-from-geojson) to specify feature `properties`. + +## Map selection in KoboCollect + + + ++Note: Selecting options from a map is only available in KoboCollect. In Enketo web forms, the option choices will appear as a normal list of options. +
+ +In KoboCollect, adding a **select type question** with a **map** or **quick map** appearance allows users to choose an option directly from a map rather than from a list. When the map opens, it centers on the device’s current location. Buttons on the right let users recenter on their location or show all available map points. + +Point choices are shown as map markers. Tapping a marker increases its size. +Line and polygon choices are displayed as red outlines, with polygons shaded in red. Users can tap a line or polygon to select it. When a location is selected, its [properties](https://support.kobotoolbox.org/select_from_map_xls.html#adding-choice-properties) appear at the bottom of the screen, unless the **quick map** appearance is used. + +Under the choice label, a **Select** button appears to confirm and save the selected location to the form, unless the **quick map** appearance is used. + ++Note: The map and quick map appearances can be combined with choice filters to display options on the map based on a previous selection. +
+ diff --git a/source/skip_logic_xls.md b/source/skip_logic_xls.md new file mode 100644 index 000000000..b74b45955 --- /dev/null +++ b/source/skip_logic_xls.md @@ -0,0 +1,110 @@ +# Adding skip logic in XLSForm + +Skip logic, also known as relevance logic, allows you to **determine when a question or group of questions will be displayed** in the form based on a previous question or the result of a calculation. For example, you can use it to ask follow-up questions only to a subset of respondents, or to hide entire sections of a form if they are not relevant. + ++ To learn more about form logic in XLSForm, see Introduction to form logic in XLSForm. +
+ +This article covers the following topics: +- Adding skip logic to individual questions +- Combining multiple skip logic conditions +- Adding skip logic based on whether a question was answered +- Adding skip logic to question groups + +
+ Note: This article focuses on adding skip logic in XLSForm. To learn about adding skip logic in the KoboToolbox Formbuilder, see Adding skip logic in the Formbuilder.
+
+For hands-on practice with skip logic in XLSForm, see KoboToolbox Academy’s XLSForm Fundamentals Course.
+
+ To learn more about building form logic expressions in XLSForm, see Introduction to form logic in XLSForm. +
+ +## Combining multiple skip logic conditions + +Multiple relevance conditions can be combined into a single expression to determine when a question is displayed based on a previous response. Conditions can be combined using **and**, **or**, and **not** logical operators: + +- Use **and** when all conditions must be met for a question to be displayed. + - For example:${age} > 18 and ${student} = ‘no’
+- Use **or** when at least one condition must be met for a question to be displayed.
+ - For example: ${age} < 18 or ${student} = ‘yes’
+- Use **not** to indicate that a condition or set of conditions must not be met (e.g., when two conditions cannot be true together for a question to be displayed).
+ - For example: not(${age} > 18 and ${student} = ‘yes’)
+
+**survey worksheet**
+
+| type | name | label | relevant |
+|:--------------|:----------|:-------------------|:----------------------------------|
+| integer | age | What is your age? | |
+| select_one yn | employed | Are you employed? | ${age} >= 16 and ${age} <= 75 |
+| survey |
+
+## Adding skip logic based on whether a question was answered
+
+In addition to adding skip logic based on a specific response, you can add skip logic based on whether a question was answered or left blank. This can be useful to add follow-up questions, or when using [acknowledge questions](https://support.kobotoolbox.org/acknowledge.html) in your form.
+
+Unanswered questions are treated as empty strings, noted as two single apostrophes `''`. The following skip logic conditions can be used:
+
+| Skip logic condition | Description |
+|:---------------------|:-------------|
+| `${reference_question} != ''` | Display only if `reference_question` is answered (not blank). |
+| `${reference_question} = ''` | Display only if `reference_question` is unanswered (blank). |
+
+**survey worksheet**
+
+| type | name | label | relevant |
+|:--------------|:-----------|:---------------------|:---------------------|
+| text | why_joined | Why did you join? | |
+| select_one yn | benefits | Are you seeing benefits? | ${why_joined} != '' |
+| survey |
+
+## Adding skip logic conditions to question groups
+
+Skip logic can be applied to question groups as well as individual questions. Applying skip logic to a group will show or hide all questions within that group based on previous responses.
+
+To add skip logic to question groups:
+1. Add a **relevant** column to the `survey` worksheet.
+2. In the **begin_group** row of the question group you wish to display or hide, enter the condition that must be met **for the group to be displayed.**
+
+**survey worksheet**
+
+| type | name | label | relevant |
+|:-------------|:------------|:---------------------------------------------|:-------------------|
+| select_one yn | joined | Did you join the association? | |
+| begin_group | association | Association participation | ${joined} = 'yes' |
+| date | date_joined | When did you join the association? | |
+| select_one yn | voted | Have you ever voted in any election for the association? | |
+| end_group | | | |
+| survey |
+
diff --git a/source/xlsform_with_kobotoolbox.md b/source/xlsform_with_kobotoolbox.md
new file mode 100644
index 000000000..1df023f5d
--- /dev/null
+++ b/source/xlsform_with_kobotoolbox.md
@@ -0,0 +1,180 @@
+# Using XLSForm with KoboToolbox
+**Last updated:** Oct 7, 2025
+
+XLSForm integrates smoothly with Kobo Toolbox for creating, previewing,
+editing, and deploying forms for data collection. For example, you can start
+building a form in the Kobo Toolbox Formbuilder, then download it as an
+XLSForm for further customization. This provides a structured foundation,
+useful for new projects or users with less form building experience.
+
+Once customized, forms created in XLSForm can be uploaded to Kobo Toolbox
+for review, modification, and deployment.
+
+This article covers the following topics:
+- Downloading an XLSForm from Kobo Toolbox
+- Upload and previewing an XLSForm in Kobo Toolbox
+- Replacing an existing form with an XLSForm
+- Importing an XLSForm via URL
+- Testing and validating your XLSForm
+
+## Downloading an XLSForm from KoboToolbox
+
+When working in KoboToolbox, you may need to download your form as an
+XLSForm to make changes more efficiently, such as duplicating many
+questions, editing large option lists, adding translations, or using advanced
+functionalities not available in the Formbuilder. Additionally, downloading your
+form as an XLSForm allows you to build forms offline, share them as `.xlsx`
+files for collaboration and version management, and share them with the
+Kobo Toolbox support team or in the Community Forum to request assistance.
+
+Any form created using the KoboToolbox Formbuilder can be downloaded as
+an XLSForm file:
+
+1. Go to the **FORM** page of your project in KoboToolbox.
+2. Click the **More actions** icon.
+3. Select **Download XLS**.
+
+
+
+## Uploading an XLSForm to KoboToolbox
+Alternatively, you may need to create a new project from an XLSForm that you
+have created from scratch or that has been shared with you.
+
+To upload and preview an XLSForm to a new project in KoboToolbox:
+
+1. Go to the **Projects** home page in KoboToolbox and click **NEW**.
+2. Select **Upload an XLSForm** and upload your Excel file.
+3. Enter the project details and click **Create project**.
+4. Click the **Preview** button to preview
+ your form.
+
+
+
+## Replacing a form with an XLSForm
+Once a project has been created, you can replace any existing form with an
+updated XLSForm:
+
+1. Go to the **FORM** page of your project in KoboToolbox.
+2. Click **Replace form** in the top right
+ corner.
+3. Select **Upload an XLSForm** and upload your Excel file.
+
+
+
+## Importing an XLSForm via URL
+If you are using Google Sheets or storing the file in Dropbox, you can import
+an XLSForm via a URL. The URL must be publicly accessible and should
+initiate a file download when opened in a browser for the import to work.
+XLSForms can also be imported from similar software, such as Excel Web and
+OneDrive.
+
++For more information, see Google Sheets documentation. +
+ ++ Note: Changes made to a file in Dropbox or Google Sheets do not + automatically update in Kobo Toolbox. You must re-import the XLSForm via + URL and redeploy the form changes. +
+ +## Testing and validating your XLSForm +Validating, previewing, and testing your XLSForm is essential to ensuring its +structural integrity, functionality, and user experience. Each of these steps +help identify any errors or issues that might prevent the form from functioning +as intended. + +| Step | Description | +| :--- | :--- | +| Validating | This involves uploading the form and checking for errors (e.g., spelling or capitalization mistakes, incorrect form logic expressions, incorrect question referencing, missing labels). Form error messages typically appear when uploading, deploying, or opening a form. | +| Previewing | This allows you to visualize the form as it will be displayed to respondents and verify that all elements function correctly before deployment (e.g., form layout, question and choice labels). | +| Testing | This involves entering data to test form functionality (e.g., checking question appearances, choice options, and form logic). Testing can be done in **PREVIEW** mode before deployment. | + +Continuously validating and testing your XLSForm as you make changes will +simplify troubleshooting and help identify the cause of any issues. It is crucial +to ensure your form functions as expected before launching data collection. + +There are several tools available to test your XLSForm, including the KoboToolbox platform, the [KoboCollect app](https://play.google.com/store/apps/details?id=org.koboc.collect.android), and [ODK's XLSForm Online](https://getodk.org/xlsform/). When +previewing and testing your form, use the same platform that you will use for +data collection: [Enketo web forms](https://support.kobotoolbox.org/enketo.html), [KoboCollect](https://support.kobotoolbox.org/kobocollect_on_android_latest.html), or both. + ++To learn more about setting up KoboCollect to preview and test your forms, see +Getting started with KoboCollect. +
+ +## Troubleshooting + +