diff --git a/source/_static/files/question_library/collection_import_sample.xlsx b/source/_static/files/question_library/collection_import_sample.xlsx index ad5b4a213..896e39f2c 100644 Binary files a/source/_static/files/question_library/collection_import_sample.xlsx and b/source/_static/files/question_library/collection_import_sample.xlsx differ diff --git a/source/acknowledge.md b/source/acknowledge.md deleted file mode 100644 index 6d063eaea..000000000 --- a/source/acknowledge.md +++ /dev/null @@ -1,66 +0,0 @@ -# Acknowledge question type -**Last updated:** 17 Jul 2025 - - -The "Acknowledge" question type displays a single option, to select "OK" on the -form. - -You can use the "Acknowledge" type for questions that require only 2 states of -response: answered and not answered, or accepted and not accepted. You could use -this question type with an informed consent in your survey form, or as a way of -ensuring the interviewee has read through and agrees to the terms, usually -outlined using a ["Note" question type](question_types.md). - -## How to set up the question - -1. In the formbuilder, click the button to - add a new question. -2. Type the question text. For example, "If you agree to continue with the - survey, click OK." -3. Click " ADD QUESTION" (or press the Enter - key on the keyboard). -4. Choose the " Acknowledge" - question type. - -![Adding the acknowledge question](images/acknowledge/acknowledge_adding.gif) - -## How it is displayed in web forms and KoboCollect - -The "Acknowledge" question displays a single radio button with the label "OK" as -shown below: - -![Acknowledge questions in KoboCollect and Enketo](images/acknowledge/acknowledge.png) - -## Using skip logic and validation criteria - -An "Acknowledge" question has only 2 states of response: one where the question -is answered, and one where it is not, i.e. the response value is either "OK" or -_blank_. - -![Acknowledge questions in Skip logic](images/acknowledge/acknowledge_skip.gif) - -In the above example, the group "Survey" will only be displayed if the -"Acknowledge" question was answered (the user clicked OK). - -Below is the equivalent form logic in XLSForm syntax: - -**survey sheet** - -| type | name | label | relevant | -| :---------- | :------ | :------------------------------------------------- | :---------------- | -| acknowledge | consent | If you agree to continue with the survey, click OK | | -| begin_group | survey | Survey | ${consent} = "OK" | -| text | name | What is your name? | | -| integer | age | How old are you? | | -| end_group | | | | -| survey | - -

- You can download the example XLSForm - here . -

diff --git a/source/adding_skip_to_matrix.md b/source/adding_skip_to_matrix.md deleted file mode 100644 index fc951669f..000000000 --- a/source/adding_skip_to_matrix.md +++ /dev/null @@ -1,165 +0,0 @@ -# Adding Skip Logic to a Matrix Question -**Last updated:** 11 Mar 2022 - -In most situations, you can add skip logic to any question type as outlined in -the support article **[Adding Skip Logic](skip_logic.md)**. However, when -working within the formbuilder, adding skip logic to a `matrix` question is not -yet possible. Instead, an XLSForm can be used to implement skip logic for this -question type. This support article illustrates how you can add skip logic to a -`matrix` question using XLSForm. - -If you have gone through the support article -**[Question Matrix Response Type](matrix_response.md)**, you will already know -that there are 2 approaches to create a `matrix` question in KoboToolbox: the -_formbuilder approach_ and the _`kobo--matrix_list` approach_. This support -article provides an overview of the necessary steps to add skip logic to a -`matrix` question when using either of these approaches. - -## The formbuilder Approach: - -The approach works with **Enketo**, also known as **web forms**, utilizing the -**Grid-theme layout**. It may not function as expected if you ignore the -**Grid-theme layout** settings as outlined in the support article -**[Using Alternative Enketo Web Form Styles](alternative_enketo.md)**. - -Follow the steps outlined below to add skip logic to a `matrix` question using -the formbuilder approach. - -**Step 1:** Create a `matrix` question in the formbuilder: - -The first step is to create a `matrix` question in the formbuilder as outlined -in the support article **[Question Matrix Response Type](matrix_response.md)**. -Simply add rows and columns with the variables you intend to collect data for. - -**Step 2:** Download form as XLSForm: - -Once the `matrix` question is ready, **SAVE** the form and then -[download it as an XLSForm](getting_started_xlsform.md#downloading-an-xlsform-from-kobotoolbox). - -**Step 3:** Add relevant column header and skip logic to your XLSForm: - -Now open the XLSForm and then add the `relevant` column header to the XLSForm. -Once you have the `relevant` column header, you will be able to add skip logic -to all the questions as needed. - -To improve the way in which the `matrix` questions are displayed when -responding, it is advised to add a `note` question type (highlighted in yellow -in the image below) and then include skip logic to it as appropriate. This is -entirely optional as it will simply affect the formatting of the `matrix` -question. The difference of _using_ and _not using_ the `note` question type is -illustrated below in **Step 6: Collect Data**. - -![XLSForm formbuilder Approach](images/adding_skip_to_matrix/formbuilder_xlsform.png) - -**Step 4:** Replace XLSForm: - -Upload and replace your XLSForm into the existing project, or create a new -project (if needed). - -**Step 5:** Deploy Form: - -Once you have replaced the XLSForm (or uploaded the XLSForm as a new project), -you will need to deploy your form. - -**Step 6:** Collect Data: - -After deploying the form, you can go to **FORM>Collect Data>OPEN** to start -collecting data with the web form. - -**Data entry screen as seen in Enketo (web form): _when nothing is entered_.** - -![Empty Enketo Form formbuilder Approach](images/adding_skip_to_matrix/formbuilder_enketo_form_empty.png) - -**Data entry screen as seen in Enketo (web form) with `note` question type -added: _when the `matrix` question is filled in_.** - -![Filledup Enketo Form formbuilder Approach](images/adding_skip_to_matrix/formbuilder_enketo_form_filled_no_issue.png) - -As you can see in the image above, the format of the `matrix` question has not -been distorted. This is how the `matrix` table will be displayed when you use -the `note` question type that was highlighted in the image shared earlier. - -**Data entry screen as seen in Enketo (web form) with `note` question type not -added: _when the `matrix` question is filled in_.** - -![Filledup Enketo Form formbuilder Approach](images/adding_skip_to_matrix/formbuilder_enketo_form_filled_with_issue.png) - -In this case, the format of the `matrix` question has been distorted. This is -the `matrix` table that will be displayed when the `note` question type is not -used. - -

- You can access the XLSForm - here - that was used for this approach - (adding skip logic to a matrix question using the formbuilder - approach). -

- -## `kobo--matrix_list` Approach: - -Just like with the formbuilder approach, this method of adding skip logic with -an XLSForm works with **Enketo** using the **Grid-theme layout**. - -Follow the steps below to add skip logic to a `matrix` question with an XLSForm -using the `kobo--matrix_list` approach. - -**Step 1:** Create a `matrix` question in the XLSForm: - -Create a `matrix` question in the XLSForm, as outlined in the support article -**[Question Matrix Response Type](matrix_response.md)**. - -**Step 2:** Add `relevant` column header and skip logic to your XLSForm: - -Once the `matrix` question is ready, you must add the `relevant` column header. -You can now add skip logic to all the questions under the `relevant` column -header. - -![XLSForm kobo_matrix Approach](images/adding_skip_to_matrix/kobo_matrix_xlsform.png) - -**Step 3:** Upload the XLSForm: - -If your XLSForm is ready, upload it as a new project. - -**Step 4:** Deploy Form: - -Once you have uploaded the XLSForm, you will need to deploy your form. - -**Step 5:** Collect Data: - -You can now go to **FORM>Collect Data>OPEN** to start collecting data. - -**Data entry screen as seen in Enketo (web form): _when nothing is entered_.** - -![Empty Enketo Form kobo_matrix Approach](images/adding_skip_to_matrix/kobo_matrix_enketo_form_empty.png) - -**Data entry screen as seen in Enketo (web form): _when the `matrix` question is -filled in_.** - -![Filledup Enketo Form kobo_matrix Approach](images/adding_skip_to_matrix/kobo_matrix_enketo_form_filled.png) - -As you can see in the second image, the format of the `matrix` question has been -distorted. In the `kobo--matrix_list` approach you do not have the space to fix -the `matrix` table like you had with the formbuilder approach. - -

- You can access the XLSForm - here - that was used for this approach - (adding skip logic to a matrix question using the - kobo--matrix_list approach). -

diff --git a/source/advanced_calculate.md b/source/advanced_calculate.md deleted file mode 100644 index 29e6ed7cb..000000000 --- a/source/advanced_calculate.md +++ /dev/null @@ -1,79 +0,0 @@ -# Advanced Calculate Question Type -**Last updated:** 2 Dec 2021 - - -Some advanced forms may require an internal calculation to take place as part of the form (rather than afterwards during the analysis). This can be done by adding a **Calculation**, and writing the mathematical expression into the question label field. - -This article provides step-by-step instructions on how to add calculations while using the formbuilder or by downloading and adding it directly to the XLSform. - -To view a complete and detailed list of all functions please visit ODK's excellent [XPath Functions documentation](https://getodk.github.io/xforms-spec). - -## Approaches towards adding calculate questions: - -### Using the formbuilder - -Step 1: Add a calculate question - -![image](/images/advanced_calculate/calculate_question.jpg) - -Step 2: Type your calculation formulae where you would typically write your question. - -![image](/images/advanced_calculate/formulas.jpg) - -Note: - -* Your calculate question will not be displayed when conducting data entry/collection either on Kobo Collect or Enketo. It will, however, be displayed when looking at the data in the table view or in the downloaded version. -* You must follow similar rules as for XLS forms (see our section rules below). - -### Using the XLS forms - -We recommend this approach when working with more advanced calculate functions. - -XLS forms allow for use of calculate function on different types of question types. - -* You can mimic the approach used in the formbuilder where the question will not be displayed on data collection by simply defining the question type as 'calculate' and then typing your calculation within the calculate column. -* You can use 'calculate' for different question types, and in this case the question will be displayed during data collection. You can choose to make that question a read-only so that no one can change the entry. The question types we have tested with this approach include: - - a. integer (will only take numeric calculate functions) - b. text (will only take string calculate functions) - c. note (will take only question referencing and not calculate functions) - d. date (will only take date calculate functions) - e. time (will only take time calculate functions) - - ![image](/images/advanced_calculate/xls.png) - -## Rules when working with calculate questions: - -### These rules apply to both the formbuilder and XLSform - -1. You cannot use both numeric and string calculations within the same question -2. Your numeric calculations will follow the BODMAS rule in applying calculations i.e. the order of executing the calculations will be Brackets, Divisions, Multiplications, Additions then Subtractions (Always remember this when ordering a question) -3. Calculate questions that reference other questions should not be placed on the same group as the reference questions since the calculate will not appear unless you move from the group -4. When referencing a question in a calculation you need to indicate it as `${Question}` where question is the name of the question -5. You can "force" a calculation to evaluate by setting 'required' to TRUE - -### List of tested calculate functions - -_(Please feel free to recommend additional ones and we will update)_ - -![image](/images/advanced_calculate/list.png) - -### Working with IF command on calculations - -![image](/images/advanced_calculate/if_command.png) - -### Work-arounds for calculations - -_Recommended for advanced users_ - -#### Workaround 1: Creating Dummy Questions for Calculation of Final Score in a Series of Questions** - -Let's say you have a question like `QN1 Do you have a question?` Answers `Yes=1 No=2 Don’t Know=999` - -In this case you may want to create a dummy QN1 right after QN1 to account for the differences in coding and define the mathematical equivalent. So you will create a calculate question QN1d (_note this is my own naming convention d stands for dummy) and define the default value as 0 but write the formula as **If (${QN1}=1,1,0**_) - -Notice in my test form I managed to create the situation and the data appears as coded for Q1N and as calculated for mathematical meaning for Q1Nd. This should be meaning that is meant by your score. _You can do this for calculations such as wealth where Yes and No could mean a different value in different countries._ - -Once you do this for all your questions you can add a calculate question that sums up all the dummies as: - -`${QN1d}+${QN2d}+ etc` diff --git a/source/audit_logging.md b/source/audit_logging.md deleted file mode 100644 index 50851c006..000000000 --- a/source/audit_logging.md +++ /dev/null @@ -1,60 +0,0 @@ -# Audit Logging Meta Question Type -**Last updated:** 29 Jul 2025 - - -Audit Logging can be a useful tool to monitor enumerator behavior and discover -which questions are taking longer to answer, better understand how the -enumerators are navigating a certain form, and see which enumerators are -generally taking longer periods of time to submit answers. - -

This feature requires manually analyzing CSV files.

- -The audit log meta question is a question type that is only supported by using -the [Collect Android app](kobocollect_on_android_latest.md). - -To add an `audit` meta question type to a form and view the finalized data, -please follow the steps below: - -1. In an XLSForm file, add `audit` in the same fashion as you would any other - meta questions. Then upload the form file to your project and deploy the - form. - -**survey sheet** - -| type | name | label | -| :---- | :---- | :--------------------- | -| start | start | | -| end | end | | -| audit | audit | | -| text | Q1 | Q1. What is your name? | -| survey | - -2. Collect data using the [Collect Android app](kobocollect_on_android_latest.md) and send - the finalized forms back to the server. Collect saves the audit logs for each - submission in a CSV file that are saved and uploaded to the server just as an - attached photo would be. - -3. After the data has been submitted, open your project in the browser and go to - **DATA**, then **Downloads**. Select **Media Attachments (ZIP)** as the - export type and then click on **New Export**. Once the download is done - pending, click on the file to download it to your computer. - -![image](/images/audit_logging/zip_export.png) - -4. Once the ZIP file has been extracted and opened, click on the file labeled - 'audit.csv' to view the audit logs. It's important to note that the CSV uses - [Unix Epoch](https://www.unixtimestamp.com/index.php) time so the logs are - recorded in milliseconds. - -5. Because timestamps are saved for each individual submission, you will - probably need to copy the values into a new spreadsheet to do further - analysis across all submissions (e.g. by enumerator or by question). - Collating many different CSV files into can be done by - [many free tools or by writing a script](https://www.google.com/search?q=merge+many+CSV). - To read more detailed information regarding log structure and event types, - please visit ODK's great documentation on - [Logging Enumerator Behavior](https://docs.getodk.org/form-audit-log/#). - -Please feel free post on our -[community forum](https://community.kobotoolbox.org/) to share your favorite -approach or script to use this feature so others can learn from your example. diff --git a/source/barcode_qrcode_questions.md b/source/barcode_qrcode_questions.md deleted file mode 100644 index 909a05dd0..000000000 --- a/source/barcode_qrcode_questions.md +++ /dev/null @@ -1,101 +0,0 @@ -# Barcode/QR code question type -**Last updated:** 24 Sep 2025 - - -The "Barcode/QR code" question type is used for scanning, decoding and capturing -barcodes and QR codes using the device camera. When a code is scanned with the -camera the value (whether numbers or text) stored in the code is captured. - -

- Barcode/QR code scanning only works when using KoboCollect on mobile devices. -

- -A wide range of Barcode and QR code formats are supported, including the -following: - -- UPC-A -- UPC-E -- EAN-8 -- EAN-13 -- Code 39 -- Code 93 -- Code 128 -- Codabar -- ITF -- RSS-14 -- RSS-Expanded -- QR Code -- Data Matrix -- Aztec -- PDF 417 -- MaxiCode - -"Barcode/QR code" questions can be used in different scenarios including asset -management or item distribution. For example, you can scan a QR code on a -beneficiary identity card to capture their ID number. You can then use use the -`pulldata()` function to automatically populate fields from a CSV attached to -your project or from a [linked project](dynamic_data_attachment.md) with -information about the beneficiary. You can learn more about the `pulldata()` -function [here](https://xlsform.org/en/#how-to-pull-data-from-csv). - -## How to set up the "Barcode/QR code" question type - -### Setting up in formbuilder - -To add a "Barcode/QR code" question: - -- Click the button to add a new question -- Type the question text, for example "Collect the beneficiary identification - code", then click **ADD QUESTION** or press ENTER on your keyboard -- Choose the question type - -![Adding Barcode/QRCode questions](images/barcode_qrcode_questions/adding_barcode_qrcode_questions.gif) - -### Setting up in XLSForm - -To add a "Barcode/QR code" question in XLSForm, add a question with type -`barcode` as follows: - -| type | name | label | -| :------ | :------------- | :------------------------------ | -| barcode | beneficiary_id | Capture the beneficiary ID code | -| survey | - -## How "Barcode/QR code" questions are displayed on web forms and KoboCollect - -### Default appearance - -![Default appearance of Barcode/QRCode questions](images/barcode_qrcode_questions/barcode_qrcode_default.png) - -### Advanced appearance - -When adding the "Barcode/QR code" question type, you can change the appearance -settings to switch from using the default (back) camera of the device to using -the front camera. - -### Changing advanced Appearance in formbuilder - -Go to the question settings of the "Barcode/QR code" question, and type "front" -in the "Appearance (Advanced)" box - -![Changing appearance of Barcode/QRCode questions](images/barcode_qrcode_questions/change_appearance_barcode_qrcode_questions.png) - -### Changing advanced Appearance in XLSForm - -In XLSForm, you can set the default camera for capturing the "Barcode/QR code" -to be the front camera by typing 'front' in the `appearance` column as follows: - -| type | name | label | appearance | -| :------ | :--------------- | :------------------------------ | :--------- | -| barcode | beneficiary_id_2 | Capture the beneficiary ID code | front | -| survey | - -

- You can download an XLSForm with examples from this article - here. -

diff --git a/source/calculations_constraints_matrix.md b/source/calculations_constraints_matrix.md deleted file mode 100644 index b36e4852c..000000000 --- a/source/calculations_constraints_matrix.md +++ /dev/null @@ -1,103 +0,0 @@ -# Adding Calculations and Constraints in a Matrix Question -**Last updated:** 14 Apr 2022 - -When working in the formbuilder, it is simple to -[add calculations](calculate_questions.md) or -[constraints](validation_criteria.md) to almost any question type. While the -formbuilder does not currently support adding these features to a matrix -question, you can use XLSForm to do so. The steps listed below in this support -article will illustrate how you can add calculations and constraints to a matrix -question using XLSForm. - -## Setting up the question and fields - -**Step 1: Create a matrix question in the formbuilder** - -The first step is creating a matrix question in the formbuilder (as outlined in -the support article [Question Matrix Response Type](matrix_response.md)). Simply -add rows and columns with the variables necessary for data collection. - -**Step 2: Download the form as XLSForm** - -Once the matrix question has been created, **SAVE** the form and -[download it as an XLSForm](getting_started_xlsform.md#downloading-an-xlsform-from-kobotoolbox). - -**Step 3: Add logic to the matrix question** - -Open the XLSForm and add `calculation`, `constraint` and `constraint_message` -column headers. With these column headers, you will be able to add the _column -total_ and _row total_ expressions under the `calculation` column header. You -can also add appropriate _constraints_ under the `constraint` column header and -_constraint message_ under the `constraint_message` header as needed. - -Additionally, you may also choose to add a `read_only` column header to restrict -enumerators from editing the responses while collecting data to certain -questions (for example, the _row total_ and _column total_ that gets -calculated). - -![Survey Tab](images/calculations_constraints_matrix/survey_tab.png) - -

- In the image above, you may notice that the name inputs are - shorter. In this example, they have been renamed from the ones auto-generated - in the formbuilder to capture the entire screenshot of the survey tab. If you - choose to rename yours, make sure to use your new variable names in the - calculation and constraint column headers. If the - form has already been deployed and data has been collected, it is recommended - that you do not rename the existing variables. -

- -**Step 4: Replace form** - -Upload and replace your XLSForm within the existing project, or create a new -project (if needed). - -**Step 5: Deploy form** - -**Step 6: Collect data** - -After deploying the form, you can go to **FORM>Collect Data>OPEN** to start -collecting data with the web form. - -## Viewing the result - -The following images illustrate how the form will look and function in the -Enketo web form after the above steps have been followed: - -**No data is entered:** - -![Enketo Nothing Entered](images/calculations_constraints_matrix/enketo_nothing_entered.png) - -**An input error is made:** - -![Enketo Wrong Inputs Entered](images/calculations_constraints_matrix/enketo_wrong_inputs_entered.png) - -Here you will see that there are only five total household members. If an -enumerator enters 6 for the number of males (0-14 Years), the constraint will -show an error message. - -**No input errors:** - -![Enketo Correct Inputs Entered](images/calculations_constraints_matrix/enketo_correct_inputs_entered.png) - -Here, when you enter values in a matrix table, the rows and columns are -automatically calculated. - -

- You can download the XLSForm that was used for this article - here. -

- -## Troubleshooting - -- The matrix question only works with **Enketo web forms**. It is not - supported with the **KoboCollect Android App**. - -- The matrix table will appear distorted if you fail to set the layout to - **Grid-theme**. For more details on web form appearances, you can refer to - [Using Alternative Enketo Web Form Styles](alternative_enketo.md). diff --git a/source/calculations_xls.md b/source/calculations_xls.md index 9f2bd9fe8..dc39d6b39 100644 --- a/source/calculations_xls.md +++ b/source/calculations_xls.md @@ -8,7 +8,7 @@ Calculations are processed within the form, helping save time during data analys This article explains how to add calculations in XLSForm, covering both basic arithmetic and more advanced expressions.

-Note: This article focuses on adding calculations in XLSForm. To learn about adding calculations in the KoboToolbox Formbuilder, see Calculate question type. +Note: This article focuses on adding calculations in XLSForm. To learn about adding calculations in the KoboToolbox Formbuilder, see Adding calculations in the Formbuilder.

For hands-on practice with calculations in XLSForm, see KoboToolbox Academy’s XLSForm Fundamentals Course.

@@ -60,7 +60,7 @@ Advanced calculations in XLSForm often rely on **functions** and **regular expre * **Regular expressions (regex)** are search patterns used to match specific characters within a string of text.

- 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. + For a comprehensive list of functions available in XLSForm, see Using functions in XLSForm. To learn more about regular expressions, see Using regular expressions in XLSForm.

Examples of more advanced calculations include: diff --git a/source/collecting_signatures.md b/source/collecting_signatures.md deleted file mode 100644 index 4e1bf72f9..000000000 --- a/source/collecting_signatures.md +++ /dev/null @@ -1,47 +0,0 @@ -# Signature Question Type -**Last updated:** 29 Jul 2025 - - -Some forms may require signatures to be included with them. You can use -appearance `signature` on both Collect Android app and Enketo. The draw widget -is only available when using Enketo for data collection. - -## Collect Android app - -Collect allows for a digital signature to be collected directly on the screen of -the phone/tablet. - -To add this to your form: - -1. Open or download the XLS version of your form. -2. Create the question and set the type as `image` -3. Set the appearance to `signature` - -## Enketo - -Digital signatures also work on Enketo web forms, where you have the additional -option to use a draw widget to collect signatures. In your XLSForm just add -`signature` or `draw` under the `appearance` column for an `image`-type -question. - -**survey sheet** - -| type | name | label | appearance | hint | -| :---- | :--- | :--------------- | :--------- | :------------------------------- | -| image | draw | Draw widget | draw | Image type with draw appearance | -| image | sign | Signature widget | signature | Image type with signature widget | -| survey | - -[Follow this link](https://enke.to/draw) to test the difference between the draw -and signature widgets. - -## Create a Signature question type in the formbuilder - -1. Create a new question and select Photo as the question type. - -![image](/images/collecting_signatures/new_question.jpg) - -2. In the Settings under Question Options, click on the Appearance drop down and - select Signature. - -![image](/images/collecting_signatures/signature.jpg) diff --git a/source/custom_format_web.md b/source/custom_format_web.md deleted file mode 100644 index df0a676e3..000000000 --- a/source/custom_format_web.md +++ /dev/null @@ -1,28 +0,0 @@ -# Custom Formatting in Web Forms -**Last updated:** 15 Feb 2022 - - -_Please note: Custom formatting does work on the KoboCollect android -application._ - -When using Web Forms (Enketo) as your data collection method, you have the -option to format your question labels in several ways. - -To format your note text, use one of these options: - -- _emphasize words_ by wrapping them inside `_these_` or `*these characters*` -- **strongly emphasize** words by wrapping them inside `__these characters__` - or `**these**` -- [a link](https://www.kobotoolbox.org) can be added by using - `[a link](https://www.kobotoolbox.org)` - -These formattings will not work in KoboCollect, which will just show the `_` or -`*` characters along with the text. - -## Combining text and media by 'combining' subsequent notes - -You can already include an image, video, or audio file in your questions. (This -works both in Web forms and in KoboCollect.) But when using Web Forms, you can -choose to show the image next to the text, for example, simply by adding two -subsequent notes. To learn more about this process, please -[see this post](https://blog.enketo.org/better-notes). diff --git a/source/dynamic_data_attachment.md b/source/dynamic_data_attachment.md index 95c7593b7..0e4f37a88 100644 --- a/source/dynamic_data_attachment.md +++ b/source/dynamic_data_attachment.md @@ -1,4 +1,4 @@ -# Dynamic data attachments +# Dynamic data attachments in XLSForm **Last updated:** 4 Jan 2026 @@ -10,7 +10,7 @@ Dynamic linking allows you to use data from a **parent project** within **child You can retrieve various **non-media responses** from a parent project and perform calculations on this linked data in a child project. This can be useful for retrieving baseline data, contact information, or health records in cohort studies, or for confirming or verifying previously collected data. -We recommend using [XLSForm](https://support.kobotoolbox.org/edit_forms_excel.html) to set up dynamic data attachments. For examples of parent and child projects, download sample files [here](https://support.kobotoolbox.org/_static/files/dynamic_data_attachment/parent.xlsx) and [here](https://support.kobotoolbox.org/_static/files/dynamic_data_attachment/child.xlsx). +We recommend using [XLSForm](https://support.kobotoolbox.org/edit_forms_excel.html) to set up dynamic data attachments. For examples of parent and child projects, download sample files [here](https://support.kobotoolbox.org/_static/files/dynamic_data_attachment/parent.xlsx) and [here](https://support.kobotoolbox.org/_static/files/dynamic_data_attachment/child.xlsx). To learn how to set up dynamic data attachments in the KoboToolbox Formbuilder, see Dynamic data attachments using the Formbuilder. ## Dynamically linking projects in XLSForm diff --git a/source/dynamic_data_attachment_formbuilder.md b/source/dynamic_data_attachment_formbuilder.md new file mode 100644 index 000000000..cb1685e45 --- /dev/null +++ b/source/dynamic_data_attachment_formbuilder.md @@ -0,0 +1,124 @@ +# Dynamic data attachments using the Formbuilder + +Dynamic linking allows you to retrieve data from a **parent project** within **child projects**, simplifying the management of longitudinal data collection. + +You can retrieve various **non-media responses** from a parent project and perform calculations on this linked data in a child project. This can be useful for retrieving baseline data, contact information, or health records in cohort studies, or for confirming or verifying previously collected data. + +This article explains how to dynamically link data between KoboToolbox projects within the KoboToolbox Formbuilder. + +

+Note: It can be easier to use XLSForm to set up dynamic data attachments. To learn more, see Dynamic data attachments in XLSForm. +

+ +## Dynamically linking projects in the Formbuilder + +Dynamically linking projects requires a **parent project** and at least one **child project.** The **parent project** requires no modification from a normal KoboToolbox form. However, setting up the **child project(s)** involves the following steps: + +First, add an **External XML** question to your child form. This links the parent form to the child form. To do so: + +1. Click the button. +2. Click **+ ADD QUESTION.** +3. Choose the External XML question type. +4. Instead of the question label, provide a short name for the parent form. This name can consist of Latin alphabet characters, underscores, and numbers. + +![Select External XML question](images/dynamic_data_attachment_formbuilder/external_xml.png) + +Then, throughout the form, you can retrieve values from the parent project using **Calculate** questions: + +1. Click the button. +2. Click **+ ADD QUESTION.** +3. Choose the Calculate question type. +4. Instead of the question label, include a calculation expression to retrieve the parent data (see table [below](#calculation-syntax-for-dynamic-data-attachments)). + +After retrieving the parent data in a **Calculate** question, you can reference it elsewhere in your form, including in question labels, notes, or form logic, using the standard [question referencing format](https://support.kobotoolbox.org/form_logic.html#question-referencing). + +![Retrieve data from calculate question](images/dynamic_data_attachment_formbuilder/example.png) + +

+To learn more about calculations in the Formbuilder, see Adding calculations in the Formbuilder. +

+ +## Calculation syntax for dynamic data attachments + +In the **question label** field of the Calculate question where linked data will be retrieved, include one of the expressions in the table below. These expressions are called **XPaths.** + +For each expression in the table below: + +- `parent` is the unique name assigned to the **parent form** (in the External XML question of the **child form**). +- `parent_question` refers to the data column name of a question from the **parent form.** +- `child_question` refers to the data column name of a question from the **child form.** +- `parent_index_question` is the identifying question from the **parent form** that links it to the **child form** (e.g., unique ID, organization name). +- `child_index_question` is the identifying question from the **child form** that links it to the **parent form** (e.g., unique ID, organization name). +- `parent_group` refers to the data column name of the group in the **parent form** in which the `parent_question` is located. +- `parent_index_group` refers to the data column name of the group in the **parent form** in which the `parent_index_question` is located. + +| **XPath** | **Description** | +| :----------------- | :--------------------------------------------- | +| `count(instance('parent')/root/data)` | Returns the total number of rows in the parent project. | +| `count(instance('parent')/root/ data[parent_group/parent_question])` | Returns the total number of rows in the parent project where `parent_question` (in `parent_group`) is not empty. | +| `count(instance('parent')/root/ data[parent_group/parent_question= current()/../child_question])` | Returns the total count of instances where the value of `parent_question` (in `parent_group`) in the parent project is equal to the value of `child_question` in the child project. | +| `instance('parent')/root/ data[parent_index_group/parent_index_question= current()/../child_index_question]/parent_group/ parent_question` | Returns the value of `parent_question` (in `parent_group`) from the parent project where `child_index_question` in the child project is equal to `parent_index_question` in the parent project. | +| `instance('parent')/root/ data[parent_index_group/parent_index_question= current()/../child_index_question][position()= 1]/parent_group/parent_question` | Same as above, but specifies that only data from the first instance of `parent_index_question` should be returned, using the `[position() = 1]` argument. Used in case of possible duplicates in the parent form. | +| `sum(instance('parent')/root/ data/parent_group/parent_question)` | Returns the sum of values from `parent_question` (in `parent_group`) from the parent project. Note that `parent_question must be numeric` | +| `max(instance('parent')/root/ data/parent_group/parent_question)` | Returns the maximum value entered in `parent_questio`n (in parent_group) from the parent project. Note that `parent_question` must be numeric. | +| `min(instance('parent')/root/ data/parent_group/parent_question)` | Returns the minimum value entered in `parent_question` (in `parent_group`) from the parent project. Note that `parent_question` must be numeric. | + +

+Note: If the parent question is not included in any group, omit parent_group/ from the expression. +

+ +## Setting up projects for dynamic linking + + + +Once your parent and child projects are set up and deployed in KoboToolbox, follow these steps: + +1. Enable data sharing for the parent project: + - In the **SETTINGS > Connect Projects** tab of the parent project, toggle the **Data sharing** switch (disabled by default) and click **ACKNOWLEDGE AND CONTINUE** in the confirmation window. + - All data is shared by default, but you can restrict specific variables to share with child projects by clicking "Select specific questions to share". + +

+ Note: If projects have different owners, the parent project owner must share the project with the child project owner. The minimum permissions required for dynamic data attachments to work are View form and View submissions. Note that this allows child project administrators to view all parent project data. +

+ +2. Connect the child project to the parent project: + - In the **SETTINGS > Connect Projects** tab of the child project, click the “Select a different project to import data from.” A dropdown menu will allow you to select a parent project to link. + - Rename the linked parent project to the External XML question label defined in the Formbuilder and click **IMPORT.** + - You can then select specific questions from the parent project to share with the child project (recommended), or select all questions. +3. If you add new fields to the parent form and wish to use them in the child project, re-import the parent project in the child project settings. + +

+Note: Forms can only be linked together if they are on the same KoboToolbox server. +

+ +## Dynamically linking a form to itself + +It is possible for a parent and child project to be the same project. The steps are the same as those described above. Examples of use cases include: + +- **Daily monitoring:** If a form is used to survey the same person over time, you can link it to itself to count previous submissions. This can allow you to display a message (e.g., "monitoring is complete") after a certain number of entries or to inform the enumerator of the number of forms submitted, as shown in the example below. + +![Daily monitoring of a survey](images/dynamic_data_attachment_formbuilder/monitoring.png) + +- **Registration form:** By linking a registration form to itself, you can check whether a user has already been registered. This can allow you to generate an error message or add [validation criteria](https://support.kobotoolbox.org/validation_criteria.html) if they are already registered, preventing duplicate registrations. + +## Collecting and managing data with dynamic linking + +Data for dynamically linked projects can be collected using the [KoboCollect Android app](https://support.kobotoolbox.org/kobocollect_on_android_latest.html) or [Enketo web forms](https://support.kobotoolbox.org/data_through_webforms.html). + +When collecting data, note the following: + +- The parent project must have at least one submission for the child project to function correctly. +- When collecting data online, there is a five-minute delay in syncing new parent project data with the child project. +- In offline mode, frequently download the child project to ensure data synchronization with the parent project. + +You can [configure the KoboCollect Android app](https://support.kobotoolbox.org/kobocollect_settings.html#form-management-settings) to automatically update the parent project's data when an internet connection is available: + +1. Go to **Settings > Form management > Blank form update mode** +2. Select either **Previously downloaded forms only** or **Exactly match server.** +3. Set the automatic download frequency to occur every 15 minutes, every hour, every six hours, or every 24 hours. Note that enabling this setting may increase battery consumption. + +

+Note: To learn how to set up dynamic data attachments in XLSForm and for additional troubleshooting support, see Dynamic data attachments in XLSForm. +

+ + diff --git a/source/form_logic_xls.md b/source/form_logic_xls.md index 6e7d91772..2bb1d5885 100644 --- a/source/form_logic_xls.md +++ b/source/form_logic_xls.md @@ -94,7 +94,7 @@ Regex can be used in **constraints** to control the length and characters entere 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. + To learn more about using regex in KoboToolbox, see Using regular expressions in XLSForm.

diff --git a/source/form_settings_xls.md b/source/form_settings_xls.md index eacdf6566..cf3697268 100644 --- a/source/form_settings_xls.md +++ b/source/form_settings_xls.md @@ -6,7 +6,7 @@ XLSForm allows you to configure settings for your forms using the `settings` wor 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. +Note: This article focuses on form settings forms in XLSForm. To learn about configuring form styles in the KoboToolbox Formbuilder, see Styling Enketo web forms in the Formbuilder.

## Adding form settings in XLSForm diff --git a/source/form_style_xls.md b/source/form_style_xls.md index 9193223c3..682ad61b4 100644 --- a/source/form_style_xls.md +++ b/source/form_style_xls.md @@ -6,7 +6,7 @@ With KoboToolbox, you can customize the appearance of your forms and questions t 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. +Note: This article focuses on styling forms in XLSForm. To learn about setting Enketo themes in the KoboToolbox Formbuilder, see Styling Enketo web forms in the Formbuilder.

## Themes for Enketo web forms diff --git a/source/formbuilder.md b/source/formbuilder.md index 970cc71cf..91a520b82 100644 --- a/source/formbuilder.md +++ b/source/formbuilder.md @@ -38,7 +38,7 @@ To remove a question, click **Delete Question** in To access advanced question settings, click on **Settings** in the question menu on the right. Here, you can add skip logic, validation criteria, guidance hints, and make a question required.

-To learn more about question settings, see Using the question options, Adding skip logic in the Formbuilder, and Adding validation criteria in the Formbuilder. +To learn more about question settings, see Question options in the Formbuilder, Adding skip logic in the Formbuilder, and Adding validation criteria in the Formbuilder.

## Adding questions to the library diff --git a/source/glossary.md b/source/glossary.md index 7f004557f..1bfacd874 100644 --- a/source/glossary.md +++ b/source/glossary.md @@ -45,7 +45,7 @@ A set of tools that allows different software systems to communicate with KoboTo Setting that changes how a question or group is displayed in a form, such as showing multiple questions on one screen or modifying how response options are presented.

- For more information, see Using the Formbuilder support articles and Question appearances in XLSForm. + For more information, see Question options in the Formbuilder and Question appearances in XLSForm.

--- @@ -60,7 +60,7 @@ Projects that have been removed from the active project list and no longer accep ## Audit -A record that tracks specific actions taken during data collection or form completion, such as question timing or location, when audit settings are enabled in a form. +A record that tracks specific actions taken during data collection or form completion, such as question timing or location, when audit metadata is enabled in a form.

For more information, see Form Audit Log (ODK). @@ -103,7 +103,7 @@ Empty data collection forms that have been downloaded to a device in the KoboCol An automated expression in a form that generates a value based on other responses or predefined rules, without requiring the respondent to enter the value manually.

- For more information, see Calculate question type and Adding calculations in XLSForm. + For more information, see Adding calculations in the Formbuilder and Adding calculations in XLSForm.

**Related term(s):** [Functions](https://support.kobotoolbox.org/glossary.html#functions) @@ -158,7 +158,7 @@ The language that displays by default when a form is opened, usually the languag A preset answer that automatically appears when a form loads, allowing respondents to keep the value as is or replace it with their own response.

- For more information, see Question options in the Formbuilder and Question options in XLSForm. + For more information, see Question options in the Formbuilder and Question options in XLSForm.

--- @@ -205,10 +205,10 @@ Projects that are still being developed or edited and are not yet deployed, so t ## Dynamic data attachments -A feature that allows a form to access records from another KoboToolbox project, so selected data fields are automatically refreshed and available during data collection. +A feature that allows a form to access submissions from another KoboToolbox project, so selected data fields are automatically retrieved and available during data collection.

- For more information, see Dynamic data attachments. + For more information, see Dynamic data attachments using the Formbuilder and Dynamic data attachments in XLSForm.

--- @@ -259,7 +259,7 @@ The KoboToolbox server hosted in the European Union, which users can select for The set of rules and conditions that control how a form behaves, including skip logic, validation criteria, calculations, and other automated actions that respond to user input.

- For more information, see Introduction to form logic in XLSForm. + For more information, see Introduction to form logic in the Formbuilder and Introduction to form logic in XLSForm.

**Related term(s):** [Skip logic](https://support.kobotoolbox.org/glossary.html#skip-logic), [Validation criteria](https://support.kobotoolbox.org/glossary.html#validation-criteria), [Choice filter](https://support.kobotoolbox.org/glossary.html#choice-filter), [Calculation](https://support.kobotoolbox.org/glossary.html#calculation) @@ -317,7 +317,7 @@ The KoboToolbox server hosted in the United States, which users can select for s Additional instructions for a question that are hidden behind an expandable section and can be opened by the respondent to view extra guidance during data collection.

- For more information, see Question options in the Formbuilder and Question options in XLSForm. + For more information, see Question options in the Formbuilder and Question options in XLSForm.

**Related term(s):** [Regular hint](https://support.kobotoolbox.org/glossary.html#regular-hint) @@ -329,7 +329,7 @@ Additional instructions for a question that are hidden behind an expandable sect Standardized hashtags added to datasets to improve interoperability, allowing data to be easily understood, merged, and analyzed across different humanitarian organizations and tools.

- For more information, see Using HXL tags. + For more information, see Question options in the Formbuilder.

--- @@ -381,7 +381,7 @@ The text shown to respondents for a question or response option during data coll A collection of reusable questions or forms that can be added to new projects, helping you design forms more efficiently. Libraries can also be shared with other users for collaborative use.

- For more information, see Using the question library. + For more information, see Using the KoboToolbox question library.

**Related term(s):** [Public collections](https://support.kobotoolbox.org/glossary.html#public-collections), [Library locking](https://support.kobotoolbox.org/glossary.html#library-locking) @@ -405,7 +405,7 @@ A feature that controls how templates from the Library can be edited after they Information automatically added to a submission that provides context about how or when the data was collected, such as device ID, start and end time, or location.

- For more information, see Form settings and metadata in the Formbuilder and Form metadata in XLSForm. + For more information, see Adding form metadata in the Formbuilder and Form metadata in XLSForm.

--- @@ -470,7 +470,7 @@ The Projects home page is the main dashboard you see by default when you sign in A feature that allows users to share selected form templates or questions from their Library publicly, making them available for anyone to browse and reuse.

- For more information, see Using Public Collections. + For more information, see Public collections in the KoboToolbox library.

**Related term(s):** [Library](https://support.kobotoolbox.org/glossary.html#library) @@ -492,7 +492,7 @@ A feature that allows a form to retrieve values from an external CSV file during A set of related questions grouped together in a form to improve structure and organization. Question groups can be displayed on the same screen, skipped as a unit using skip logic, or repeated to collect multiple sets of responses.

- For more information, see Grouping questions and repeating groups and Grouping questions in XLSForm. + For more information, see Grouping questions and repeating groups in the Formbuilder and Grouping questions in XLSForm.

**Related term(s):** [Repeat group](https://support.kobotoolbox.org/glossary.html#repeat-group) @@ -504,7 +504,7 @@ A set of related questions grouped together in a form to improve structure and o Using answers from one question elsewhere in the form, such as displaying a previous response in later question text or using it in calculations, skip logic, or validation criteria.

- For more information, see Introduction to form logic in XLSForm. + For more information, see Introduction to form logic in the Formbuilder and Introduction to form logic in XLSForm.

**Related term(s):** [Form logic](https://support.kobotoolbox.org/glossary.html#form-logic) @@ -516,7 +516,7 @@ Using answers from one question elsewhere in the form, such as displaying a prev The kind of question used in a form, which determines how respondents provide their answers, such as text, number, select one, or rating.

- For more information, see Introduction to question types and Question types in XLSForm. + For more information, see Adding questions in the Formbuilder and Question types in XLSForm.

--- @@ -538,7 +538,7 @@ To update an already deployed form after changes have been made, replacing the p Additional information displayed directly below a question label to help respondents or enumerators understand how to answer. Regular hints are always visible in the form. Regular hints are also called **Question hints** in the Formbuilder.

- For more information, see Question options in the Formbuilder and Question options in XLSForm. + For more information, see Question options in the Formbuilder and Question options in XLSForm.

**Related term(s):** [Guidance hint](https://support.kobotoolbox.org/glossary.html#guidance-hint) @@ -550,7 +550,7 @@ Additional information displayed directly below a question label to help respond A set of questions that can be answered multiple times within a form, allowing respondents to enter repeated information such as household members, items, or events.

- For more information, see Grouping questions and repeating groups and Repeat groups in XLSForm. + For more information, see Grouping questions and repeating groups in the Formbuilder and Repeat groups in XLSForm.

**Related term(s):** [Question group](https://support.kobotoolbox.org/glossary.html#question-group) @@ -657,4 +657,8 @@ The XML version of a form generated when a project is deployed, used by data col The internal short names assigned to questions and choices that are used to store and reference data in a form. These are also called **Data Column Names** in the Formbuilder, and **question names** or **choice names** in XLSForm. Exporting your data using XML values can facilitate data management and analysis. +

+ For more information, see Adding questions in the Formbuilder. +

+ **Related term(s):** [Label](https://support.kobotoolbox.org/glossary.html#label) diff --git a/source/group_repeat.md b/source/group_repeat.md index 055491e7d..03e940caf 100644 --- a/source/group_repeat.md +++ b/source/group_repeat.md @@ -1,4 +1,4 @@ -# Grouping questions and repeating groups +# Grouping questions and repeating groups in the Formbuilder **Last updated:** 25 Nov 2025 @@ -79,7 +79,7 @@ In KoboCollect, questions appear one at a time by default. In Enketo web forms, To display questions by group on the same screen during data collection, click the **Settings** icon to the right of the group name. Then, under **Appearance (Advanced)**, select **field-list** (Show all questions in this group on the same screen).

- Note: If you plan to collect data using Enketo web forms, you will also need to enable the Multiple pages theme in the Form style menu (Layout & Settings). For more information on Enketo web form styles, see Using alternative Enketo web form styles. + Note: If you plan to collect data using Enketo web forms, you will also need to enable the Multiple pages theme in the Form style menu (Layout & Settings). For more information on Enketo web form styles, see Styling Enketo web forms in the Formbuilder.

### Skipping a question group diff --git a/source/grouping_questions_xls.md b/source/grouping_questions_xls.md index f002f863d..8968a827c 100644 --- a/source/grouping_questions_xls.md +++ b/source/grouping_questions_xls.md @@ -12,7 +12,7 @@ This article covers the following topics: - 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. +Note: This article focuses on grouping questions in XLSForm. To learn about grouping questions in the KoboToolbox Formbuilder, see Grouping questions and repeating groups in the Formbuilder.

## Creating a question group diff --git a/source/hxl.md b/source/hxl.md deleted file mode 100644 index be82a8a79..000000000 --- a/source/hxl.md +++ /dev/null @@ -1,54 +0,0 @@ -# Using HXL Tags -**Last updated:** 29 Jul 2025 - - -## What exactly is HXL? - -HXL stands for **Humanitarian Exchange Language**. The goal of HXL is to improve -information sharing during a humanitarian crisis by creating a simple way to -promote interoperability of data. It does this by coding the data through -hashtags (#) similar to Twitter. For more information on HXL, please -[visit here](https://hxlstandard.org). - -## How to use the HXL feature in the formbuilder - -_Credits: [David Megginson](http://www.megginson.com)_ _Link to step-by-step -[slide show guide](https://docs.google.com/presentation/d/123bHSkNh4T30CNq0i37IxOLfrqSC-3V_Khtkf6bIdg0/edit#slide=id.p)_ - -1. After starting a form and creating a question, go into Question Settings and - in the Question Options tab, choose your HXL tag and add attributes. - - ![image](/images/hxl/hxl.gif) - -2. After the form has been created, the project deployed, and data has been - collected, go to the Downloads tab in the Data page. Select the export type - as XLS and be sure to select **XML values and headers** for the value and - header format. Then Export. - - ![image](/images/hxl/xml_values.gif) - -3. Once you have exported and downloaded the data to your computer, open up the - XLS file to see your HXL tags. It's okay to have Kobo metadata that doesn't - have HXL hashtags. - - ![image](/images/hxl/xls_affected.jpg) - -

The hashtag before name is mandatory and spaces are not allowed.

- -## How to use HXL in an XLSForm - -When authoring an XLSForm, simply insert one extra column in any existing -spreadsheet and fill it with HXL hashtags identifying the type of information in -each column. - -**survey sheet** - -| type | name | label | hxl | -| :------------------- | :------- | :------------------------------- | :--------- | -| select_one countries | country | Select affected country | #country | -| select_one admin1 | province | Please select the province | #adm1+code | -| select_one admin2 | county | Select the county | #adm2+name | -| select_one sector | cluster | Cluster | #sector | -| integer | affected | Number of people affected | #affected | -| integer | reached | Number of people reached to date | #reached | -| survey | diff --git a/source/images/dynamic_data_attachment_formbuilder/example.png b/source/images/dynamic_data_attachment_formbuilder/example.png new file mode 100644 index 000000000..d22099a79 Binary files /dev/null and b/source/images/dynamic_data_attachment_formbuilder/example.png differ diff --git a/source/images/dynamic_data_attachment_formbuilder/external_xml.png b/source/images/dynamic_data_attachment_formbuilder/external_xml.png new file mode 100644 index 000000000..932b78f6e Binary files /dev/null and b/source/images/dynamic_data_attachment_formbuilder/external_xml.png differ diff --git a/source/images/dynamic_data_attachment_formbuilder/monitoring.png b/source/images/dynamic_data_attachment_formbuilder/monitoring.png new file mode 100644 index 000000000..c2fa1d2c7 Binary files /dev/null and b/source/images/dynamic_data_attachment_formbuilder/monitoring.png differ diff --git a/source/images/note_questions/enketo_note.png b/source/images/note_questions/enketo_note.png new file mode 100644 index 000000000..ba28585b5 Binary files /dev/null and b/source/images/note_questions/enketo_note.png differ diff --git a/source/images/note_questions/kobocollect_note.png b/source/images/note_questions/kobocollect_note.png new file mode 100644 index 000000000..ec3d2f1dd Binary files /dev/null and b/source/images/note_questions/kobocollect_note.png differ diff --git a/source/images/note_questions/note.png b/source/images/note_questions/note.png new file mode 100644 index 000000000..f38e74450 Binary files /dev/null and b/source/images/note_questions/note.png differ diff --git a/source/images/photo_audio_video_file/media.png b/source/images/photo_audio_video_file/media.png new file mode 100644 index 000000000..2e10d5bfa Binary files /dev/null and b/source/images/photo_audio_video_file/media.png differ diff --git a/source/images/photo_audio_video_file/table_updated.png b/source/images/photo_audio_video_file/table_updated.png new file mode 100644 index 000000000..884e47011 Binary files /dev/null and b/source/images/photo_audio_video_file/table_updated.png differ diff --git a/source/images/question_types/add_question.png b/source/images/question_types/add_question.png new file mode 100644 index 000000000..53fe0bb55 Binary files /dev/null and b/source/images/question_types/add_question.png differ diff --git a/source/images/question_types/delete_choice.png b/source/images/question_types/delete_choice.png new file mode 100644 index 000000000..fe25b351f Binary files /dev/null and b/source/images/question_types/delete_choice.png differ diff --git a/source/images/select_one_and_select_many/appearance.png b/source/images/select_one_and_select_many/appearance.png new file mode 100644 index 000000000..8de309308 Binary files /dev/null and b/source/images/select_one_and_select_many/appearance.png differ diff --git a/source/images/select_one_and_select_many/autocomplete.png b/source/images/select_one_and_select_many/autocomplete.png new file mode 100644 index 000000000..c4906360d Binary files /dev/null and b/source/images/select_one_and_select_many/autocomplete.png differ diff --git a/source/images/select_one_and_select_many/columns_n.png b/source/images/select_one_and_select_many/columns_n.png new file mode 100644 index 000000000..401c74b90 Binary files /dev/null and b/source/images/select_one_and_select_many/columns_n.png differ diff --git a/source/images/select_one_and_select_many/compact.png b/source/images/select_one_and_select_many/compact.png new file mode 100644 index 000000000..f262797e6 Binary files /dev/null and b/source/images/select_one_and_select_many/compact.png differ diff --git a/source/images/select_one_and_select_many/horizontal-compact_columns-pack.png b/source/images/select_one_and_select_many/horizontal-compact_columns-pack.png new file mode 100644 index 000000000..35726e4e0 Binary files /dev/null and b/source/images/select_one_and_select_many/horizontal-compact_columns-pack.png differ diff --git a/source/images/select_one_and_select_many/horizontal_columns.png b/source/images/select_one_and_select_many/horizontal_columns.png new file mode 100644 index 000000000..ba3624e25 Binary files /dev/null and b/source/images/select_one_and_select_many/horizontal_columns.png differ diff --git a/source/images/select_one_and_select_many/likert.png b/source/images/select_one_and_select_many/likert.png new file mode 100644 index 000000000..c88677935 Binary files /dev/null and b/source/images/select_one_and_select_many/likert.png differ diff --git a/source/images/select_one_and_select_many/minimal.png b/source/images/select_one_and_select_many/minimal.png new file mode 100644 index 000000000..46714afef Binary files /dev/null and b/source/images/select_one_and_select_many/minimal.png differ diff --git a/source/images/select_one_and_select_many/ranking.png b/source/images/select_one_and_select_many/ranking.png new file mode 100644 index 000000000..4a7f3888e Binary files /dev/null and b/source/images/select_one_and_select_many/ranking.png differ diff --git a/source/images/select_one_and_select_many/rating.png b/source/images/select_one_and_select_many/rating.png new file mode 100644 index 000000000..b4ee5b2be Binary files /dev/null and b/source/images/select_one_and_select_many/rating.png differ diff --git a/source/images/select_one_and_select_many/select.png b/source/images/select_one_and_select_many/select.png new file mode 100644 index 000000000..3947dc287 Binary files /dev/null and b/source/images/select_one_and_select_many/select.png differ diff --git a/source/images/select_one_and_select_many/table.png b/source/images/select_one_and_select_many/table.png new file mode 100644 index 000000000..c7d2a5d01 Binary files /dev/null and b/source/images/select_one_and_select_many/table.png differ diff --git a/source/index.rst b/source/index.rst index 32c7226bc..0879b1dad 100644 --- a/source/index.rst +++ b/source/index.rst @@ -55,37 +55,29 @@ Search the knowledge base, browse our resources, and visit our forum for more de formbuilder question_types - text_and_note + text_questions select_one_and_select_many acknowledge number_decimal_range date_time photo_audio_video_file - barcode_qrcode_questions - rating_ranking - external_file gps_questions - calculate_questions - advanced_calculate - collecting_signatures - matrix_response - responses_inside_question + note_questions question_options - skip_logic - validation_criteria - number_text_responses - cascading_select group_repeat - restrict_responses + matrix_response language_dashboard - form_meta - audit_logging - custom_format_web alternative_enketo + form_meta + form_logic + skip_logic + validation_criteria + calculate_questions + cascading_select + external_file + dynamic_data_attachment_formbuilder question_library using_public_collections - public_collections_advanced_search - hxl .. raw:: html @@ -113,6 +105,7 @@ Search the knowledge base, browse our resources, and visit our forum for more de media form_logic_xls functions_xls + restrict_responses skip_logic_xls constraints_xls required_logic_xls @@ -126,6 +119,7 @@ Search the knowledge base, browse our resources, and visit our forum for more de select_from_map_xls dynamic_data_attachment library_locking + import_collection .. raw:: html diff --git a/source/kobocollect_settings.md b/source/kobocollect_settings.md index 569d1c29a..e6445ef2b 100644 --- a/source/kobocollect_settings.md +++ b/source/kobocollect_settings.md @@ -73,13 +73,13 @@ Form management settings control how forms are handled within the app, including | Constraint processing | When your forms include constraints (validation criteria), choose between validating responses when moving to the next page or at the end of the form. | | High res video | Enable or disable high-resolution video recordings when taking videos through the app. | | Image size | Define the preferred image size, from very small to large. This can help conserve storage space on the server. | -| Show guidance for questions | Define how [guidance hints](https://support.kobotoolbox.org/question_options.html?highlight=guidance+hint#guidance-hint-optional) should be displayed within your form. | +| Show guidance for questions | Define how [guidance hints](https://support.kobotoolbox.org/question_options.html#guidance-hint) should be displayed within your form. | | Use external app for audio recording | By default, an internal recorder is used for audio recording. Enable this setting to use an external audio application instead. | | Finalize forms on import | When enabled, forms that are brought into KoboCollect from outside the app (e.g. copied from device storage or SD card) are automatically marked as Finalized, so they are ready to send without requiring manual finalization. |

- Note: Configuring projects for automatic form updates is recommended in projects with frequent form edits or dynamic data attachments. This removes the need to manually download form updates. However, more frequent automatic updates will drain your device’s battery more quickly. + Note: Configuring projects for automatic form updates is recommended in projects with frequent form edits or dynamic data attachments. This removes the need to manually download form updates. However, more frequent automatic updates will drain your device’s battery more quickly.

## User and device identity settings diff --git a/source/kobotoolbox_interface.md b/source/kobotoolbox_interface.md index 612cdbd93..825980b03 100644 --- a/source/kobotoolbox_interface.md +++ b/source/kobotoolbox_interface.md @@ -70,7 +70,7 @@ The **SETTINGS** page contains configuration options for your project. It is div * **General:** Update the project name and description, [archive](https://support.kobotoolbox.org/managing_projects.html#archiving-and-deleting-projects) or delete the project. * **Media:** Upload and manage [project media files](https://support.kobotoolbox.org/upload_media.html). * **Sharing:** Update [sharing permissions](https://support.kobotoolbox.org/managing_permissions.html) for other users. -* **Connect Projects:** Set up connections for [dynamic data attachments](https://support.kobotoolbox.org/dynamic_data_attachment.html). +* **Connect Projects:** Set up connections for [dynamic data attachments](https://support.kobotoolbox.org/dynamic_data_attachment_formbuilder.html). * **REST Services:** Configure [REST services](https://support.kobotoolbox.org/rest_services.html) to automatically send submissions to third-party applications. * **Activity:** View and export the [project history logs](https://support.kobotoolbox.org/activity_logs.html#project-history-logs), including changes made by other users. diff --git a/source/library_locking.md b/source/library_locking.md index 53caed8df..db6dde34f 100644 --- a/source/library_locking.md +++ b/source/library_locking.md @@ -8,9 +8,9 @@ The [KoboToolbox library](https://support.kobotoolbox.org/question_library.html) 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.

-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. +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. +To learn more about uploading and using templates in KoboToolbox, see Using the question library.

## Introduction to library locking diff --git a/source/managing_repeat_groups.md b/source/managing_repeat_groups.md index ae5f2a49b..bb58530da 100644 --- a/source/managing_repeat_groups.md +++ b/source/managing_repeat_groups.md @@ -5,7 +5,7 @@ KoboToolbox allows you to collect repeated data within a form, for example, when conducting a household survey where all members are asked the same questions. This article explains how to view, edit, and export repeat group data, and how to link repeat group data to the main data.

- To learn more about setting up repeat groups in your forms, see Grouping questions and repeating groups. + To learn more about setting up repeat groups in your forms, see Grouping questions and repeating groups in the Formbuilder and Repeat groups in XLSForm.

## Viewing and editing repeat group data diff --git a/source/metadata_xls.md b/source/metadata_xls.md index 2713e4a73..aa1e38725 100644 --- a/source/metadata_xls.md +++ b/source/metadata_xls.md @@ -6,7 +6,7 @@ Metadata questions automatically gather information about the data collection pr Metadata questions are hidden from respondents, and metadata fields cannot be edited in the KoboToolbox data table. This background information supports auditing, helps maintain data integrity, and can be used in 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. +Note: This article focuses on adding metadata questions in XLSForm. To learn about adding metadata questions in the KoboToolbox Formbuilder, see Adding form metadata in the Formbuilder.

## Adding metadata questions in XLSForm diff --git a/source/note_questions.md b/source/note_questions.md new file mode 100644 index 000000000..06b58e252 --- /dev/null +++ b/source/note_questions.md @@ -0,0 +1,53 @@ +# Note questions in KoboToolbox + +Note questions are used to display information within your form without collecting a response. Although they are listed as a question type, note questions do not store any data. Instead, they are used to **provide instructions, context, or additional details** that help respondents or enumerators understand and complete the form correctly. + +You can use note questions to introduce a new section, explain why certain questions are being asked, provide guidance on how to respond, [display media](https://support.kobotoolbox.org/media.html), or show the results of [hidden calculations](https://support.kobotoolbox.org/calculate_questions.html) or [previous responses](https://support.kobotoolbox.org/form_logic.html#question-referencing). + +This article explains how to add a **Note** question in the Formbuilder and how to add styling to your note text. + +## Adding a note question in the Formbuilder + +To add a note question to your form: + +1. Click the button. +2. Enter your question label. +3. Click **+ ADD QUESTION.** +4. Choose the Note question type. + +![Choose note question type](images/note_questions/note.png) + +## Appearances of note questions + +By default, note questions appear as simple text in your form. + +| Enketo web form | KoboCollect | +|:----------------|:------------| +| ![Note question in Enketo](images/note_questions/enketo_note.png) | ![Note question in KoboCollect](images/note_questions/kobocollect_note.png) | + +### Advanced appearances + +When adding notes to your form, you can use Markdown and HTML to **style text, add emphasis** with bold or italics, **create headers** of different sizes, **change fonts and colors**, and **add clickable web links.** + +

+Note: Text styling can also be applied to questions and choice labels. +

+ +Text styling features in the Formbuilder include: + +| Feature | Formatting | +|:---------------|:-----------| +| Italics | `*italics*` or `_italics_` | +| Bold | `**bold**` or `__bold__` | +| Hyperlink | `[name of link](url)` | +| Headers | `# Header 1` (biggest) to `###### Header 6` (smallest) | +| Emojis | For example, 🙂 😐 🙁 😦 😧 😩 😱 | +| Superscript | `100 m2` turns into 100 m² | +| Subscript | `H2O` turns into H₂O | +| Colored text | `orange` turns into orange
`red` turns into red | +| Font | `cursive` turns into cursive
`red and cursive` turns into red and cursive| +| Align center | `

Centered label

` centers the text on the screen | + +

+Note: Additional formatting features, such as paragraph support, bullet lists, and numbered lists, are available only when building your form in XLSForm. +

diff --git a/source/number_text_responses.md b/source/number_text_responses.md deleted file mode 100644 index a4e111928..000000000 --- a/source/number_text_responses.md +++ /dev/null @@ -1,11 +0,0 @@ -# Limits on Number and Text Responses -**Last updated:** 21 Jun 2020 - - -There are underlying technical constraints to the length of the response in a **Number** or **Text** question. - -**Number questions** can save up to 17 digits (positive or negative number). To be exact, the largest number that can be entered is 2147483647 and the smallest -2147483648. - -If you want a numeric response but need a number with more than 9 digits (i.e. larger than the one given above) - e.g. for long phone numbers in some countries - you can do this with a trick. Instead of a Number question, add a Text question to your form. Then in the Appearance setting of the question, set it to numbers. This will show the number keyboard instead of the standard text keyboard. - -**Text questions** (as well as Barcode questions) are almost unlimited in terms of the characters that can be entered. (The total length of text needs to be less than 1MB in size, which is more than 300 pages of text - more than can ever be expected in a response to a question. diff --git a/source/photo_audio_video_file.md b/source/photo_audio_video_file.md index d04881695..6159d61bf 100644 --- a/source/photo_audio_video_file.md +++ b/source/photo_audio_video_file.md @@ -1,8 +1,18 @@ -# Media question types +# Media questions in KoboToolbox **Last updated:** 3 Feb 2026 Many data collection projects require more than just quantitative data. KoboToolbox allows you to capture various media files from respondents, including photos, audio recordings, videos, and files, to provide key qualitative information and add visual and auditory depth to your datasets. +The method of capturing or uploading media depends on whether you are using [KoboCollect](https://support.kobotoolbox.org/kobocollect_on_android_latest.html) or [Enketo web forms](https://support.kobotoolbox.org/enketo.html) for data collection. In KoboCollect, you can either upload or record media files directly within the app. With Enketo, you can upload any media file, and record audio directly within the forms. + +This article covers the following topics: +- Available media question types in KoboToolbox +- Adding media questions in the Formbuilder +- Default and advanced appearances of media questions +- Parameters for media questions + +## Media question types + The following media question types are available in the KoboToolbox Formbuilder: | Question type | Description | @@ -11,26 +21,23 @@ The following media question types are available in the KoboToolbox Formbuilder: | Audio | Record or upload an audio file | | Video | Record or upload a video file | | File | Attach a file (e.g., .pdf, .docx) | +| Barcode / QR Code | Scan barcodes and QR codes using the device camera | -The method of capturing or uploading media depends on whether you are using [KoboCollect](https://support.kobotoolbox.org/kobocollect_on_android_latest.html) or [Enketo web forms](https://support.kobotoolbox.org/enketo.html) for data collection. In KoboCollect, you can either upload or record media files directly within the app. With Enketo, you can upload any media file, and record audio directly within the forms.

Note: KoboToolbox also supports background audio recordings for entire interviews or focus group discussions. When background audio recording is active on a form, Audio question types in KoboCollect are deactivated, as it is not possible to record audio using both features simultaneously. For more information, see Recording interviews with background audio recording.

-This article covers the following topics: -- Adding media questions in the Formbuilder -- Default and advanced appearances of media questions -- Parameters for media questions - ## Adding media questions in the Formbuilder -To add media questions: -1. Click the button to add a new question. -2. Type the question text and click **+ ADD QUESTION.** -3. Choose the desired question type (Photo, Audio, Video, or File). +To add a media question to your form: -![Add a media question to Formbuilder](images/photo_audio_video_file/add.gif) +1. Click the button. +2. Enter your question label. +3. Click **+ ADD QUESTION.** +4. Choose the appropriate question type. + +![Add a media question to Formbuilder](images/photo_audio_video_file/media.png) ## Appearances of media questions @@ -40,29 +47,40 @@ Media questions can display differently depending on whether you are using Enket The table below shows how media questions are displayed by default in Enketo web forms and KoboCollect. -![Default appearances of media questions](images/photo_audio_video_file/table.png) - -### Advanced appearances +![Default appearances of media questions](images/photo_audio_video_file/table_updated.png) -Only the **Photo** question type supports advanced appearances. These appearances alter how the question behaves in web forms and KoboCollect, enabling users to do more than just upload or capture images. With advanced appearances, you can draw sketches, add signatures, annotate images, and take selfies. +

+Note: Barcode / QR Code questions are supported only in KoboCollect on mobile devices. When a code is scanned using the device’s camera, the value encoded in the barcode or QR code is automatically captured. In Enketo web forms, this question type appears as a standard text field, where respondents must manually enter the value. +

-Available appearances include: +### Advanced appearances -| Appearance | Description | -|:--------------|:-------------| -| signature | Allows the user to capture a signature by signing directly on the device's screen (e.g., for forms that require a digital signature for verification). | -| draw | Enables users to sketch or create drawings directly on the device’s screen (e.g., to capture illustrations or hand-drawn maps). | -| annotate | Allows the user to annotate an image by drawing or writing on it. | -| new | Prompts the user to take a new picture using the device camera (only available when using KoboCollect). | -| new-front | Prompts the user to take a new picture using the device's front-facing camera (only available when using KoboCollect). | +You can apply advanced appearances to **Photo** and **Barcode / QR Code** questions to modify how they display and behave in your form. Advanced appearances for **Photo** questions allow users to do more than simply upload or capture an image, including drawing sketches, adding signatures, annotating images, and taking selfies directly within the form. To add an advanced appearance: + 1. Open the question settings by clicking **Settings** to the right of the question. This will take you to the **Question Options** tab. 2. In **Appearance (Advanced)**, choose the desired appearance. - If the appearance is not listed, select **Other** and type the name of the appearance in the text box, exactly as written above. + +![Question appearances](images/photo_audio_video_file/appearances.png) + +Available appearances for **Photo** questions include: + +| Appearance | Description | +|:--------------|:-------------| +| `signature` | Allows the user to capture a signature by signing directly on the device's screen (e.g., for forms that require a digital signature for verification). | +| `draw` | Enables users to sketch or create drawings directly on the device’s screen (e.g., to capture illustrations or hand-drawn maps). | +| `annotate` | Allows the user to annotate an image by drawing or writing on it. | +| `new` (other) | Prompts the user to take a new picture using the device camera (only available when using KoboCollect). | +| `new-front` (other) | Prompts the user to take a new picture using the device's front-facing camera (only available when using KoboCollect). | -![image](images/photo_audio_video_file/appearances.png) +For **Barcode / QR Code** questions, there is only one advanced appearance available: + +| Appearance | Description | +|:--------------|:-------------| +| `front` | Switches from the device's default rear camera to the front-facing camera. | ## Parameters for media questions @@ -77,6 +95,7 @@ Beyond their basic function, media questions also offer advanced parameters that If your project involves collecting a significant amount of media, you might encounter difficulties uploading files to KoboToolbox, depending on your internet speed. Users of the [Community Plan](https://www.kobotoolbox.org/pricing/) are also limited to 1GB of free file storage. Therefore, it is advisable to manage the file sizes of the media files you collect. To define the maximum size of images collected using the **Photo** question type: + 1. Open the question settings by clicking **Settings** to the right of the question. This will take you to the **Question Options** tab. 2. Set the **max-pixels** parameter to the value of your choice (e.g., 1000). @@ -89,6 +108,7 @@ To define the maximum size of images collected using the **Photo** question type ### Restricting accepted file types By default, the **File** question type accepts all file types. To restrict the type of files this question accepts: + 1. Open the question settings by clicking **Settings** to the right of the question. This will take you to the **Question Options** tab. 2. In the **Accepted Files** text box, list the file extensions that you would like to allow, separated by a comma (e.g., .doc, .pdf, .xlsx) @@ -116,4 +136,9 @@ By default, the **File** question type accepts all file types. To restrict the t +
+
+ Supported barcode / QR code formats +KoboCollect supports a wide range of barcode and QR code formats, including UPC-A, UPC-E, EAN-8, EAN-13, Code 39, Code 93, Code 128, Codabar, ITF, RSS-14, RSS-Expanded, QR Code, Data Matrix, Aztec, PDF 417, and MaxiCode. If a barcode cannot be scanned, verify that it uses one of these supported formats. +
diff --git a/source/project_files_media.md b/source/project_files_media.md index ff7ba85dd..2913877ce 100644 --- a/source/project_files_media.md +++ b/source/project_files_media.md @@ -59,7 +59,7 @@ There are two main ways to connect your form to external files: Supported file formats for these features include CSV, XML, and GeoJSON.

- To learn how to attach external datasets to your form, see Pulling data from an external CSV and Selecting options from an external file. + To learn how to attach external datasets to your form, see Pulling data from an external CSV and Selecting options from external files in the Formbuilder.

### Uploading files and media to KoboToolbox @@ -104,7 +104,7 @@ KoboToolbox also supports background audio recording for entire interviews or focus group discussions.

- To learn more about collecting media from respondents, see Media question types. To learn more about background audio recording, see Recording interviews with background audio recording. + To learn more about collecting media from respondents, see Media questions in KoboToolbox. To learn more about background audio recording, see Recording interviews with background audio recording.

### Viewing respondent media files diff --git a/source/public_collections_advanced_search.md b/source/public_collections_advanced_search.md deleted file mode 100644 index ccae2282d..000000000 --- a/source/public_collections_advanced_search.md +++ /dev/null @@ -1,104 +0,0 @@ -# Public Collections Advanced Search -**Last updated:** 4 Mar 2021 - -**_Please note that the search capability is a work in progress, and we plan to -add a more user-friendly syntax in future releases._** - -## The Default Search Behaviour - -When you enter a term into the search bar without specifying a field, your query -will return results where that term, regardless of capitalization, can be found -in: - -- The name of the survey, collection, question, block, or template; -- The owner's username; -- The description; -- The summary, which contains all question labels and languages; -- The name of any assigned tag; -- The object's UID. - -For example, a default search with the term: "_examples_", will result in the -following: - -``` -name__icontains:examples OR owner__username__icontains:examples OR -settings__description__icontains:examples OR summary__icontains:examples OR -tags__name__icontains:examples OR uid__icontains:examples -``` - -![examples](/images/public_collections_advanced_search/advanced_search_1.png) - -## Valid Search Field Operators - -The field operator is the value after the last double-underscore in the search -field, i.e. `__icontains`. - -- For _case-sensitive_ **text** searches, the following operators can be used: - `contains`, `exact`, `startswith` -- For _case-insensitive_ **text** searches: `icontains`, `iexact`, - `istartswith` -- For **numeric** search, the following operators are valid: `exact`, `lt`, - `lte`, `gt`, `gte` - -Note that by default the `exact` operator is set, therefore `name:foo` is -equivalent to `name__exact:foo` - -## Understanding the Search Field Syntax - -The double underscore syntax mimics the behaviour of -[Django's object filtering syntax](https://docs.djangoproject.com/en/3.1/ref/contrib/admin/#django.contrib.admin.ModelAdmin.search_fields) -and it allows one to traverse related object relationships and JSON hierarchies, -such as those seen at the endpoint: - -`https://kf.kobotoolbox.org/api/v2/assets/` - -For example, if an asset has the following settings: - -``` -{ - ... - "settings": { - ... - "country": { - "label": "United States", - "value": "USA" - } - ... - }, - ... -} -``` - -The object could be searched through the following methods: - -``` -settings__country__value:USA -``` - -![examples](/images/public_collections_advanced_search/advanced_search_2.png) - -Or more loosely: - -``` -settings__country__value__icontains:usa -``` - -![examples](/images/public_collections_advanced_search/advanced_search_3.png) - -## Using the Query Parser - -Finally, the search fields described above can be combined using the -[query parser](https://github.com/kobotoolbox/kpi#searching) syntax for more -refined searches. For example: - -``` -owner__username__icontains:foo AND tags__name__icontains:bar -``` - -Or: - -``` -owner__username__icontains:foo AND NOT tags__name__icontains:bar -``` - -![examples](/images/public_collections_advanced_search/advanced_search_4.png) diff --git a/source/question_options_xls.md b/source/question_options_xls.md index 9808caa2c..d99ccb5b3 100644 --- a/source/question_options_xls.md +++ b/source/question_options_xls.md @@ -6,7 +6,7 @@ When designing a form in XLSForm, you can customize questions by adding hints, s This article covers the most common question options and how to add them to your XLSForm, including question hints, required questions, default responses, and question parameters.

- Note: This article focuses on defining question options in XLSForm. To learn about question options in the KoboToolbox Formbuilder, see Using the question options. + Note: This article focuses on defining question options in XLSForm. To learn about question options in the KoboToolbox Formbuilder, see Question options in the Formbuilder.

For hands-on practice with question options in XLSForm, see KoboToolbox Academy’s XLSForm Fundamentals Course.

diff --git a/source/question_types.md b/source/question_types.md index d2571eddb..e80fd5a75 100644 --- a/source/question_types.md +++ b/source/question_types.md @@ -1,51 +1,95 @@ -# List of Question Types +# Adding questions in the Formbuilder **Last updated:** 28 Oct 2024 -The below table provides a high-level summary of each of the response types -available to use in your XLSForm and formbuilder: - -| Question type | Icon | Answer input | -| :------------------------------- | :-------------------------------------------- | :------------------------------------------------------------------------------------------- | -| integer | | Integer (i.e., whole number) input. | -| decimal | | Decimal input. | -| range | | Range input (including rating). | -| text | | Free text response. | -| select_one [options] | | Multiple choice question; only one answer can be selected. | -| select_multiple [options] | | Multiple choice question; multiple answers can be selected. | -| select_one_from_file [file] | | Multiple choice from file; only one answer can be selected. | -| select_multiple_from_file [file] | | Multiple choice from file; multiple answers can be selected. | -| rank [options] | n/a | Rank question; order a list. | -| note | | Display a note on the screen, takes no input. Shorthand for type=text with readonly=true. | -| geopoint | | Collect a single GPS coordinate. | -| geotrace | | Record a line of two or more GPS coordinates. | -| geoshape | | Record a polygon of multiple GPS coordinates; the last point is the same as the first point. | -| date | | Date input. | -| time | | Time input. | -| datetime | | Accepts a date and a time input. | -| image | | Take a picture or upload an image file. | -| audio | | Take an audio recording or upload an audio file. | -| background-audio | | Audio is recorded in the background while filling the form. | -| video | | Take a video recording or upload a video file. | -| file | | Generic file input (txt, pdf, xls, xlsx, doc, docx, rtf, zip) | -| barcode | | Scan a barcode or QR Code | -| calculate | | Perform a calculation; see the Calculation section below. | -| acknowledge | | Acknowledge prompt that sets value to "OK" if selected. | -| hidden | | A field with no associated UI element which can be used to store a constant. | -| xml-external | | Adds a reference to an external XML data file. | - -For more information on the response types, please visit -[xlsform.org](http://xlsform.org/). - -Additionally, KoboToolbox-specific types can also be used from within the -formbuilder: - -| Formbuilder Question type | Icon | Answer input | -| :------------------------ | :----------------------------------------------- | :----------------------------------------------------------- | -| Rating | | Compare different items using a common scale. | -| Ranking | | Compare a list of different objects to one another. | -| Question Matrix | | Create a group of questions that display in a matrix format. | - -

Calculate Questions are not displayed in your form, but are executed automatically as your form is being answered.

- -

The Question Matrix Type is only supported in Enketo and with the Grid Theme set.

+The KoboToolbox Formbuilder allows you to easily add questions to your form as you build your survey or questionnaire. + +This article explains how to add questions to your form, define answer choices where applicable, and provides an overview of the available question types in the Formbuilder to support effective form design. + +## Adding a question + +To add a question to your form: + +1. Click the button. +2. Enter your question label. +3. Click **+ ADD QUESTION.** +4. Choose the [question type](#question-types-in-the-formbuilder). + +![Add a question to the Formbuilder](images/question_types/add_question.png) + +

+Note: Once the question type has been selected, it cannot be changed in the Formbuilder. To change the question type of an existing question, delete the question and create a new question with the same label. +

+ +### Setting data column names + +After adding a question to your form, it is strongly recommended to define a **Data Column Name** in the question **Settings.** The data column name is used to identify the question throughout the form logic and in the exported dataset. + +By default, KoboToolbox creates the data column name for you by removing spaces and capital letters from the question label. For example, if the question label is “Respondent name”, the data column name will be `respondent_name`. + +

+ To learn more about data column names, see Question options in the Formbuilder. +

+ +## Adding option choices + +When adding Select One or Select Many questions to your form, you will be prompted to enter option choices. + +- You can enter as many option choices as you want. +- To reorder the list of choices, click and drag an item to the desired position. +- Click the trash can icon next to a choice label to delete it. + +![Delete choice](images/question_types/delete_choice.png) + +

+Note: Managing long choice lists in the Formbuilder can be time-consuming. If your form includes many options or the same choice list used in multiple questions, it is often easier to create and manage these lists using XLSForm instead. To learn more, see Managing option choices in XLSForm. +

+ +### Setting XML values for option choices + +Next to each choice option, you will see a field labeled **AUTOMATIC.** This field contains the [XML value](https://support.kobotoolbox.org/glossary.html#xml-value) for that option. + +The XML value is a short, internal name that KoboToolbox uses to save and identify the selected option in your data. By default, KoboToolbox creates the XML value for you by removing spaces and capital letters from the option label. For example, if the option label is “Option 1”, the XML value will be `option_1`. + +In some cases, you may want to set your own XML value. This can be helpful if the option label is very long or if you want to use a clearer or more consistent name. To do this, click **AUTOMATIC** and replace it with your own custom value. + +

+Note: It is strongly recommended to define XML values for all choices when using non-Latin scripts, such as Chinese, Arabic, or Nepali, to ensure your data is stored and exported correctly. +

+ +## Question types in the Formbuilder + +The following question types are available in the Formbuilder: +| Question type | Description | +|:-----------------------------------------------------|:-----------------------------------------------------------------------------------------------------------------------------------------------| +| Select One | Allows respondents to [select one option](https://support.kobotoolbox.org/select_one_and_select_many.html) from a predefined list. | +| Select Many | Allows respondents to [select multiple options](https://support.kobotoolbox.org/select_one_and_select_many.html) from a predefined list. | +| Text | Provides a [text box](https://support.kobotoolbox.org/text_questions.html) to collect open-ended responses. | +| Number | Allows respondents to input [whole numbers](https://support.kobotoolbox.org/number_decimal_range.html). | +| Decimal | Allows respondents to [input numbers](https://support.kobotoolbox.org/number_decimal_range.html) that may contain decimal points. | +| Date | Captures a specific [calendar date](https://support.kobotoolbox.org/date_time.html), including year, month, and day. | +| Time | Captures a [specific time](https://support.kobotoolbox.org/date_time.html) in hours and minutes. | +| Date & time | Captures both [a date and a time](https://support.kobotoolbox.org/date_time.html) in a single combined response. | +| Point | Records a [single GPS location](https://support.kobotoolbox.org/gps_questions.html). | +| Line | Records [multiple GPS points](https://support.kobotoolbox.org/gps_questions.html) that form a line. | +| Area | Records [multiple GPS points](https://support.kobotoolbox.org/gps_questions.html) that form an enclosed area. | +| Photo | Allows respondents to [upload images](https://support.kobotoolbox.org/photo_audio_video_file.html) or take photos (when using the [KoboCollect app](https://support.kobotoolbox.org/glossary.html#kobocollect)). | +| Audio | Allows respondents to [upload an audio file](https://support.kobotoolbox.org/photo_audio_video_file.html) or record audio. | +| Video | Allows respondents to [upload videos](https://support.kobotoolbox.org/photo_audio_video_file.html) or record videos (when using the [KoboCollect app](https://support.kobotoolbox.org/glossary.html#kobocollect)). | +| Barcode / QR Code | Scans a [QR code](https://support.kobotoolbox.org/photo_audio_video_file.html) to collect embedded information using the device's camera (when using the [KoboCollect app](https://support.kobotoolbox.org/glossary.html#kobocollect)). | +| File | Allows respondents to [upload files](https://support.kobotoolbox.org/photo_audio_video_file.html), such as text files, spreadsheets, and PDF files. | +| Note | [Provides information](https://support.kobotoolbox.org/note_questions.html) to the respondent without requiring any input. | +| Acknowledge | A [single checkbox](https://support.kobotoolbox.org/select_one_and_select_many.html) that respondents can select to acknowledge their agreement with a statement. | +| Rating | Allows respondents to [rate different items](https://support.kobotoolbox.org/select_one_and_select_many.html#setting-up-rating-questions) using a common scale. | +| Question Matrix | Creates a [group of questions](https://support.kobotoolbox.org/matrix_response.html) that display in a matrix format, whereby each cell within the matrix represents a separate question. | +| Ranking | Allows respondents to [rank items](https://support.kobotoolbox.org/select_one_and_select_many.html#setting-up-ranking-questions) in order of preference. | +| Calculate | Automatically performs [calculations](https://support.kobotoolbox.org/calculate_questions.html) within a form based on responses to previous questions. | +| Hidden | Stores [predefined values](https://support.kobotoolbox.org/form_logic.html#storing-constants-in-your-form) that are not visible to the respondent. | +| Range | Allows respondents to [select a numeric value](https://support.kobotoolbox.org/number_decimal_range.html#setting-up-range-questions) within a specified range. | +| External XML | Connects the KoboToolbox project to [other projects](https://support.kobotoolbox.org/dynamic_data_attachment_formbuilder.html) in order to dynamically retrieve data. | +| Select One from File | Allows respondents to select one option [from a predefined list](https://support.kobotoolbox.org/external_file.html), stored in an external CSV file. | +| Select Many from File | Allows respondents to select multiple options [from a predefined list](https://support.kobotoolbox.org/external_file.html), stored in an external CSV file. | + +

+Note: Select One from File and Select Many from File question types only appear as options in the Formbuilder if an external choice file has been uploaded to KoboToolbox. +

diff --git a/source/question_types_xls.md b/source/question_types_xls.md index 41808597e..567a63128 100644 --- a/source/question_types_xls.md +++ b/source/question_types_xls.md @@ -30,7 +30,7 @@ Select questions allow respondents to choose from predefined options. For `selec

-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. +To learn more about select question types in KoboToolbox, see Select questions in KoboToolbox.

@@ -46,7 +46,7 @@ Numeric questions are used to collect whole numbers, decimal numbers, or values

-To learn more about numeric question types in KoboToolbox, see Number, Decimal, and Range question types. +To learn more about numeric question types in KoboToolbox, see Numeric questions in KoboToolbox.

@@ -61,7 +61,7 @@ Text questions are used to collect open-ended responses, while note questions pr

-To learn more about text and note question types in KoboToolbox, see Text and Note question types. +To learn more about text and note question types in KoboToolbox, see Text questions in KoboToolbox and Note questions in KoboToolbox.

### Media question types @@ -79,7 +79,7 @@ Media questions allow respondents to upload or record images, audio, and video f

-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. +To learn more about media question types in KoboToolbox, see Media questions in KoboToolbox and Recording interviews using background audio recording.

### GPS question types @@ -94,7 +94,7 @@ GPS questions are used to capture the geographic coordinates of a location, path

-To learn more about GPS question types in KoboToolbox, see GPS question types. +To learn more about GPS question types in KoboToolbox, see GPS questions in KoboToolbox.

### Date and time question types @@ -109,7 +109,7 @@ Date and time questions are used to capture specific calendar dates, times, or b

-To learn more about date and time questions in KoboToolbox, see Date and Time question types. +To learn more about date and time questions in KoboToolbox, see Date and time questions in KoboToolbox.

### Calculate and hidden question types @@ -121,7 +121,7 @@ Calculate and hidden questions are used to perform automatic calculations within | `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. +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/quick_start.md b/source/quick_start.md index 1aa3f94db..edb3a281e 100644 --- a/source/quick_start.md +++ b/source/quick_start.md @@ -41,7 +41,7 @@ To create your first form: 4. To save the form, click **Save** in the top right corner, then click to close the form.

- To learn more about using the Formbuilder, see Getting started with the KoboToolbox Formbuilder and Using the question options. + To learn more about using the Formbuilder, see Getting started with the KoboToolbox Formbuilder and Question options in the Formbuilder.

diff --git a/source/rating_ranking.md b/source/rating_ranking.md deleted file mode 100644 index 5ccd251c2..000000000 --- a/source/rating_ranking.md +++ /dev/null @@ -1,53 +0,0 @@ -# Rating vs Ranking Question Types -**Last updated:** 19 Jun 2020 - - -## Difference between rating and ranking questions? - -Often times, people use the terms ranking question and rating question interchangeably, when in fact there is a distinct difference between the two question types. A **rating question** asks survey respondents to compare different items using a common scale (e.g. “Please rate each of the following objects on a rating scale of 1-10, where 1 is ‘not at all important’ and 10 is ‘very important.’”). A **ranking question** on the other hand asks survey respondents to compare a list of different objects to one another (e.g. “Please rank each of the following items in order of importance with #1 being the most important object to #10 being the least important object.”). The ranking question asks respondents to compare items to each other by placing them in order of preference. When analyzing ranking questions, an average ranking is calculated for each answer choice, allowing you to quickly evaluate the most preferred answer choice. - -## When should you use ranking or rating questions? - -The choice of ranking or rating should be purely informed on the mode of analysis one needs to conduct. Note you can rate different components the same way, however when it comes to ranking you can’t give them the same rank. - -## How to add a ranking question in the FormBuilder - -1. Add a question to the survey and select "ranking" - - ![image](/images/rating_ranking/add_question.gif) - -2. Now you can add the different elements of the ranking question - - ![image](/images/rating_ranking/elements.png) - - Example: - - ![image](/images/rating_ranking/example.png) - -3. When you preview your form, the question will look like this. Each choice will now offer all of the previous defined response options, however, respondents can only select each response option once. - - ![image](/images/rating_ranking/preview_ranking.gif) - -## How to add a Rating Question - -1. You will need to create a question using the same process above. - - ![image](/images/rating_ranking/create_question.png) - -2. Select the option for Rating question and you will see the interface below. - - ![image](/images/rating_ranking/rating.png) - -3. You can then type your questions and response options. You can add more of the same using the + button provided. - - ![image](/images/rating_ranking/more_questions.png) - - Kindly note you can change the values of your response options and questions to reflect what you want. You can change them by replacing the grey text written automatic. - - ![image](/images/rating_ranking/change_values.png) - -4. You can save your form and preview it to see the effect. - - ![image](/images/rating_ranking/preview_rating.png) - -If you have any questions or feedback on this article, please post about it on our community forum! diff --git a/source/recording-interviews.md b/source/recording-interviews.md index 0d7e6ae66..10eae4d75 100644 --- a/source/recording-interviews.md +++ b/source/recording-interviews.md @@ -15,7 +15,7 @@ This article covers the following topics: - Managing background audio data

-Note: To learn about collecting short audio responses instead of a full background recording, see Media question types. +Note: To learn about collecting short audio responses instead of a full background recording, see Media questions in KoboToolbox.

## Enabling background audio recording in the Formbuilder @@ -125,6 +125,6 @@ If a form with background audio recording is saved as a draft in KoboCol
Unable to download large audio files - If large or long audio files fail to download as Media Attachments (ZIP), see Downloading photos and other media for guidance on retrieving large media files. + If large or long audio files fail to download as Media Attachments (ZIP), see Downloading media files for guidance on retrieving large media files.
diff --git a/source/repeat_groups_xls.md b/source/repeat_groups_xls.md index 617d1681c..3defb8fa9 100644 --- a/source/repeat_groups_xls.md +++ b/source/repeat_groups_xls.md @@ -12,7 +12,7 @@ This article covers the following topics: - 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. +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 in the Formbuilder.

## Creating a repeat group diff --git a/source/required_logic_xls.md b/source/required_logic_xls.md index 70e1572bc..b209100b2 100644 --- a/source/required_logic_xls.md +++ b/source/required_logic_xls.md @@ -10,7 +10,7 @@ Required logic allows you to make a question mandatory if specific conditions ar 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. + Note: This article focuses on adding required logic in XLSForm. To learn about adding required logic in the KoboToolbox Formbuilder, see Question options in the Formbuilder.

For hands-on practice with required logic in XLSForm, see KoboToolbox Academy’s XLSForm Fundamentals Course.

diff --git a/source/responses_inside_question.md b/source/responses_inside_question.md deleted file mode 100644 index 215003873..000000000 --- a/source/responses_inside_question.md +++ /dev/null @@ -1,37 +0,0 @@ -# Including Responses Inside Another Question -**Last updated:** 5 Oct 2020 - - -You can include the response of one question (such as include the answer of the question 'How old are you?') inside the label of another question. This can be useful for many reasons in advanced forms. For example, you might want to confirm that a response is really correct. - -Referencing other questions in another question requires giving them a fixed name through the question settings, such as `age` or `income`. When referencing other questions always use the unique question name inside the question referencing style, such as - -`${age}` or `${income}` - -Simply include the reference to the other question among the other words of your label. For example, you can add a new question with the label - -`Are you sure you are ${age} years old?` - -![image](/images/responses_inside_question/question_name.gif) - -And you can also create a skip logic for this question so that it is only asked whenever the age response is lower than 18. - -Note that if you reference a question that doesn't exist, it will create an error when you try to deploy your form. Always make sure to reference questions with their exact name, which is also case sensitive. For example, if your question is called `age` you can't use `${Age}`. You can easily check your form by clicking on Preview at any point. - -![image](/images/responses_inside_question/preview.gif) - -**You can also reference the response from a Select One/Many question and display the answer instead of the code using hidden Calculate questions** - -If you'd like to reference the response to a Select One/Many question and show the response's answer (e.g. "Strongly Agree") instead of its encoded value (e.g. "strongly_agr"), you can: - -1. Create a Select One/Many question, and give the question a fixed reference name through the question settings, such as `instruction`. And create an intermediate Calculate question and enter: `jr:choice-name(${instruction}, '${instruction}')`. - - ![image](/images/responses_inside_question/select_updated.gif) - -2. Give this Calculate question a reference name, such as `instruction_calculation`. In your new question, reference this Calculate question instead of the name given to the Select One/Many question. - - ![image](/images/responses_inside_question/calculate.gif) - -3. Preview and validate the form to make sure everything works as designed. - - ![image](/images/responses_inside_question/preview_calculate.gif) diff --git a/source/select_from_file_xls.md b/source/select_from_file_xls.md index 9ba8b86b7..64d0e516e 100644 --- a/source/select_from_file_xls.md +++ b/source/select_from_file_xls.md @@ -1,4 +1,4 @@ -# Selecting options from an external file +# Selecting options from an external file in XLSForm **Last updated:** 10 Feb 2026 **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**. @@ -8,7 +8,7 @@ Using a separate file for your choice list makes it easier to manage long lists, 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. +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 Selecting options from external files in the Formbuilder.

For hands-on practice with select from file questions in XLSForm, see KoboToolbox Academy’s XLSForm Fundamentals Course.

diff --git a/source/select_one_and_select_many.md b/source/select_one_and_select_many.md index 0a7883105..39c9c045c 100644 --- a/source/select_one_and_select_many.md +++ b/source/select_one_and_select_many.md @@ -1,117 +1,158 @@ -# "Select One" and "Select Many" question types +# Select questions in KoboToolbox **Last updated:** 4 Jan 2026 +Select questions allow respondents to **choose from predefined response options.** They are useful for standardizing answers, improving data quality, and making data easier to clean, analyze, and compare. -When you have a categorical question with a list of predefined options for -respondents to choose from, you have to choose either the "Select One" or -"Select Many" question type in KoboToolbox. A "Select One" question type, also -known as a "single response" question, means a respondent can only select a -single response from a list of options. Similarly, a "Select Many" question type -is also known as a "multiple response" question where a respondent can select -multiple responses from a list of options. +Depending on your needs, select questions can be used to choose one or multiple options, acknowledge a statement, rank items in order, rate items using a common scale, or select options from an external file. -"Select One" and "Select Many" question types can be better choices for -maintaining quality data when the question has a narrow and defined scope. This -is because, unlike the open-ended nature of the "Text" question type, the two -select question types limit the user to the options listed. +This article lists the different select questions available in KoboToolbox, explains how to add select questions in the Formbuilder, describes the available appearance options, and outlines key considerations when using these question types. -## When to use them +## Select question types -Use the "Select One" question type when a question has a list of choices, and -the respondent is limited to just a single option from the list. Examples -include marital status, sex, or religion. +The following question types are available in the Formbuilder for respondents to select options: -Use the "Select Many" question type if there is a list of choices and the -respondent may find it appropriate to select more than one choice. Examples -include household sources of income or a list of household assets. +| Question type | Description | +|:---|:---| +| Select One | Allows respondents to select one option from a predefined list. | +| Select Many | Allows respondents to select multiple options from a predefined list. | +| Ranking | Allows respondents to rank items or options in a choice list. | +| Rating | Allows respondents to evaluate multiple items using the same response scale. | +| Acknowledge | Allows respondents to acknowledge their agreement with a statement. | +| Select One from File | Allows respondents to select one option from a predefined list, stored in an external CSV file. | +| Select Many from File | Allows respondents to select multiple options from a predefined list, stored in an external CSV file. | -## Setting up the question and choices +

To learn more about Select One from File and Select Many from File question types, see Selecting options from external files in the Formbuilder. +

+ +## Adding a select question in the Formbuilder -Follow the same steps for setting up either a "Select One" or a "Select Many" -question: +To add a select question to your form: -- In the formbuilder, click the button to - add a new question. -- Type the question label, for example, "What is your marital status?". Then - click **+ Add Question** (or press **Enter**). -- Choose the question type ("Select One" or "Select Many") -- Type the response labels where there is "Option 1", "Option 2". Add more - choices if necessary. +1. Click the button. +2. Enter your question label. +3. Click **+ ADD QUESTION.** +4. Choose the appropriate question type. +6. Enter the option choices for the select question. + +![Question types in Formbuilder](images/select_one_and_select_many/select.png)

- You can reorder your list of choices by clicking and dragging each item to a - new position in the list. + To learn more about managing options choices for select questions in the Formbuilder, see Adding questions in the Formbuilder.

-Click the trash can icon to the left of the -option's label to remove it. +### Setting up Ranking questions -## Translating question and choice labels +**Ranking** questions are used to ask respondents to place items in order of preference, importance, or sequence. -For translating select type questions and their labels into other languages -through the KoboToolbox UI, refer to the support articles -[Adding translations in KoboToolbox](language_dashboard.md) or -[Adding translations in XLSForm](language_xls.md) if you are creating your form using XLSForm. +After adding a **Ranking** question in the Formbuilder, configure the following components: -## XML values +1. **Question label**: The overall instruction for the ranking task, such as “Select your first and second choices in order of preference.” +2. **Number of ranks**: By default, the question includes only a 1st choice. Click the sign below the first rank to add additional ranks. You can also edit the label for each rank. +3. **Items to rank**: The list of items respondents will rank. Click the sign below the last item to add more options. +4. **Constraint message**: Each item can be selected only once. If a respondent selects the same item more than once, an error message appears stating “Items cannot be selected more than once.” You can edit this default error message below the items list. -When setting up "Select One" and "Select Many" question responses, you have the -choice to specify the XML values or to let KoboToolbox generate them -automatically. +![Ranking question type](images/select_one_and_select_many/ranking.png)

- It is strongly recommended that you specify XML values for - all questions and choices before deploying your form, - especially if the labels are non-Latin character languages such as - Chinese, Arabic or Nepali. +Note: You can include more items than ranks, but the number of ranks cannot exceed the number of items.

-XML values are the values that get saved in the submission when a user chooses -the response, not the label. In the formbuilder, type the values where it says -"AUTOMATIC" as shown below. +### Setting up Rating questions + +**Rating** questions are used when you have multiple **Select One** questions that share the same set of response options, such as a scale from “Strongly disagree” to “Strongly agree.” + +After adding a **Rating** question in the Formbuilder, configure the following components: + +- **Question label**: The overall instruction for the question set, such as “Rate the following on a scale of 1 to 5.” +- **Rows**: The individual items, statements, or questions that respondents will rate. Click on the sign at the bottom of the table to add rows. +- **Columns**: The response options that make up the rating scale, such as “Strongly disagree” to “Strongly agree.” Click on the sign to the right of the table to add columns. + +![Rating question type](images/select_one_and_select_many/rating.png) + +## Appearances of select questions + +The table below displays the default appearances for select type questions: + +![Question appearances in Formbuilder](images/select_one_and_select_many/table.png) + +

+Note: The Ranking and Rating question types are available only in the KoboToolbox Formbuilder. If you are building forms using XLSForm, the appearance and behavior of the rank question type will differ from the Formbuilder version. To create a Rating question in XLSForm, add select questions with the label and list-nolabel appearances. +

+ +### Advanced appearances + +You can apply advanced appearances to **Select One, Select Many, Select One from File** and **Select Many from File** questions to modify how they display and behave in your form. -![XML Values](/images/select_one_and_select_many/xml_values.png) +To add an advanced appearance: -The predefined choices for a "Select One" and "Select Many" questions may -sometimes be insufficient while collecting data. It is possible to include the -option for a text response in that case, as outlined in our support article, -[User-Specified "Other" Responses for Multiple-Choice Questions](user_specified_other.md). +1. Open the question settings by clicking **Settings** to the right of the question. This will take you to the **Question Options** tab. +2. In **Appearance (Advanced)**, choose the desired appearance. + - If the appearance is not listed, select **other** and type the name of the appearance in the text box, exactly as written below. -## How they are displayed by default on web forms and KoboCollect +![Advanced appearance](images/select_one_and_select_many/appearance.png) -![Comparison of select one and select many on Enketo and KoboCollect](/images/select_one_and_select_many/select_one_select_many_comparison.png) +The following advanced appearances are available for **Select One, Select Many, Select One from File** and **Select Many from File** questions: -You can easily differentiate between a "Select One" and a "Select Many" question -in a data entry form. The "Select One" question has choices with a radio button -(a solid dot appears after selecting an item) while the "Select Many" question -has choices with a square checkbox (check marks appear after selecting items). +| Appearance | Description | Compatibility | +|:---|:---|:---| +| `minimal` | Displays choices in a drop-down menu.
![Minimal appearance](images/select_one_and_select_many/minimal.png) | Enketo and KoboCollect | +| `autocomplete` | Adds a search bar at the top of the option list.
![Autocomplete appearance](images/select_one_and_select_many/autocomplete.png) | Enketo and KoboCollect (combine with `minimal` appearance) | +| `likert` | Displays answer choices as a Likert scale (**Select One** only).
![Likert scale](images/select_one_and_select_many/likert.png) | Enketo and KoboCollect | +| `compact` | Displays choices side-by-side with minimal padding and without visible choice boxes. The number of choices per row may vary based on the length of each option label.
![Compact appearance](images/select_one_and_select_many/compact.png) | Enketo and KoboCollect | +| `quick` | Auto-advances the form to the next question after an answer is selected (**Select One** only). | KoboCollect only | +| `quickcompact` | Displays choices side-by-side with minimal padding and without choice boxes, and auto-advances to the next question after an answer is selected (**Select One** only).
![Quick compact appearance](images/select_one_and_select_many/compact.png) | KoboCollect only | +| `horizontal` | Displays choices in evenly sized columns, with the same number of choices in each row.
![Horizontal appearance](images/select_one_and_select_many/horizontal_columns.png) | Enketo only. Use `columns` instead for compatibility with KoboCollect. | +| `columns` (other) | Displays choices in evenly sized columns, with the same number of choices in each row.
![Columns other appearance](images/select_one_and_select_many/horizontal_columns.png) | Enketo and KoboCollect. | +| `horizontal-compact` | Displays choices in columns with visible choice boxes. The number of columns may vary by row, depending on the length of each option label.
![Horizontal compact appearance](images/select_one_and_select_many/horizontal-compact_columns-pack.png) | Enketo only. Use `columns-pack` instead for compatibility with KoboCollect. | +| `columns-pack` (other) | Displays choices in columns with visible choice boxes. The number of columns may vary by row, depending on the length of each option label.
![Columns pack appearance](images/select_one_and_select_many/horizontal-compact_columns-pack.png) | Enketo and KoboCollect | +| `columns-n` (other) | Displays available choices in the specified number (n) of columns.
![Columns-n appearance](images/select_one_and_select_many/columns_n.png)| Enketo and KoboCollect | +| `label` | Displays choice labels without the choice boxes. | Enketo and KoboCollect | +| `list-nolabel` | Displays the answer choice boxes without the labels. | Enketo and KoboCollect | -## Export options +## Best practices for using select questions -When exporting "Select Many" questions, you can choose between exporting all -selected responses in a single column or having the options in separate columns -or both. Read more about exporting and downloading data in -[this support article](export_download.md). +The following guidance highlights important considerations when using select questions in your form. -## Advanced appearances +### Acknowledge questions -When adding "Select One" and "Select Many" questions, you can choose from a wide -range of appearances. Appearances change the way the question is displayed in -the web forms or KoboCollect. +The **Acknowledge** question type allows respondents to indicate agreement with a statement using a single checkbox. However, this question does not distinguish between respondents who actively disagree and those who skip the question, which may affect data quality. In addition, the default label of the Acknowledge choice cannot be edited. -![Appearances](/images/select_one_and_select_many/appearances.png) +If you need more flexibility in labeling response options, or if you want to include a clear “No” option, use a **Select One** question instead. + +### Defining XML values for choices + +It is strongly recommended to define XML values for all choices in select questions before deploying your form. XML values ensure consistency in your dataset and prevent issues during export and analysis. + +

To learn more about defining XML values, see Adding questions in the Formbuilder. +

+ +### Adding an “Other, specify” response + +If predefined choices do not cover all possible responses, you can add an “Other” option followed by a [Text question](https://support.kobotoolbox.org/text_questions.html) that allows respondents to specify their answer. Use skip logic to display the Text question only when the “Other” option is selected. + +

+ For more information, see Adding skip logic in the Formbuilder. +

+ +### Randomizing option choices + +For **Select One** and **Select Many** questions, you can randomize the order of option choices by going to the question **Settings > Question Options > Parameters** and selecting **randomize.** + +You can also set a **seed**, which ensures that the randomization follows a consistent pattern. Using a seed allows the same randomized order to be reproduced when needed, such as when reviewing submissions or testing the form, while still reducing order bias during data collection.

- The option "other" provides you with a space where you can type a different - appearance that is not shown on the list. + To learn more about question options, see Question options in the Formbuilder.

-The following table shows the different available appearances and how they are -displayed both in the web forms and KoboCollect. +### Exporting options for Select Many questions + +When exporting data for **Select Many** questions, you can choose how responses are structured in your dataset. You can choose to: -![Appearances](/images/select_one_and_select_many/select_one_select_many_table.png) +- Export all selected options in a single column +- Export each option as a separate column +- Export both formats

- The appearances "quick", "likert" and "quickcompact" are only applicable to - "Select One" questions. + For more information, see Advanced options for exporting data.

+ diff --git a/source/skip_logic.md b/source/skip_logic.md index 5146d2741..cccf7a500 100644 --- a/source/skip_logic.md +++ b/source/skip_logic.md @@ -41,6 +41,6 @@ To manually enter skip logic in XLSForm code, follow these steps: In XLSForm code, questions are referred to by their **question name** (Data Column Name) using the format `${question_name}`. For example, if Q2 should be asked only if the answer to Q1 is "Yes", the skip logic condition for Q2 would be `${Q1} = ‘yes’`.

- For more information on XLSForm code and operators, see Introduction to form logic in XLSForm. + For more information on XLSForm code and operators, see Introduction to form logic in the Formbuilder.

diff --git a/source/skip_logic_xls.md b/source/skip_logic_xls.md index a54f3c462..1a744adc3 100644 --- a/source/skip_logic_xls.md +++ b/source/skip_logic_xls.md @@ -73,7 +73,7 @@ Multiple relevance conditions can be combined into a single expression to determ ## 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. +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/select_one_and_select_many.html) in your form. Unanswered questions are treated as empty strings, noted as two single apostrophes `''`. The following skip logic conditions can be used: diff --git a/source/text_and_note.md b/source/text_and_note.md deleted file mode 100644 index 08e63ef27..000000000 --- a/source/text_and_note.md +++ /dev/null @@ -1,68 +0,0 @@ -# Text and Note question types -**Last updated:** 9 May 2022 - - -The "Text" question type is best used for questions that require undefined or -open-ended responses, such as names, feedback, explanations or descriptions. - -The "Note" question type does not allow for a response value, instead they can -be used to add instructions, or any additional information to make the survey -clearer or easier to navigate. For instance, you can use it to inform the -respondent or enumerator about what the next section of questions contains, -provide background context for why the survey is being done, -[display various kinds of media](media.md), or -[display the results of hidden calculations or responses to previous questions](responses_inside_question.md). - -## How to set the questions up - -Setting up `text` or `note` questions is very similar: - -- In the formbuilder, click the button to - add a new question. -- Type the question text. For example, "What is your name?". Then click **+ - ADD QUESTION** (or press Enter). -- Choose the question type ("Text" or "Note") - -![Setting up text and note questions](images/text_and_note/text_note_setup.gif) - -## Appearance in web forms and KoboCollect - -### Default appearance - -![Default appearance of text and note](images/text_and_note/text_note_default_appearance.png) - -

- The default text box in Enketo Webform accepts only one line of text. However, - in KoboCollect, the text field expands as you type. You can also add line - breaks to form paragraphs -

- -### Advanced appearances - -You can change the appearance of "Text" questions in its settings. - -![Appearance settings](images/text_and_note/text_appearance_settings.png) - -![Advanced appearances for text](images/text_and_note/text_advanced_appearance.png) - -## Considerations when using "Text" questions - -For the sake of data quality, it may be advisable to use -["Select one" or "Select many" question types](select_one_and_select_many.md) -when you are able to predefine a list of the responses. Limiting responses can -streamline data cleaning, processing and analysis. - -The use of the "Text" question type is best suited to open-ended questions, -where you are unable to have a predefined list of responses. - -## Using question logic - -Since the responses to "Text" questions are open-ended, using question logic may -be more challenging and is best facilitated by using "Regular Expressions". - -With RegEx, you can implement validation logic, such as limiting the length of -text responses, restricting the characters and sequence (such as a unique ID) or -only allowing responses that are in capital letters. - -To learn more about implementing RegEx, read the support article -[Restricting Text Responses With Regular Expressions](restrict_responses.md) diff --git a/source/validation_criteria.md b/source/validation_criteria.md index 48d054b81..a80b4578c 100644 --- a/source/validation_criteria.md +++ b/source/validation_criteria.md @@ -49,7 +49,7 @@ In XLSForm syntax, a dot `.` is used to refer to the current question, and `${qu

- For more information on XLSForm code and operators, see Introduction to form logic in XLSForm. + For more information on XLSForm code and operators, see Introduction to form logic in the Formbuilder.

## Error message diff --git a/source/viewing_validating_data.md b/source/viewing_validating_data.md index 38dd57c6a..bb338fb14 100644 --- a/source/viewing_validating_data.md +++ b/source/viewing_validating_data.md @@ -39,7 +39,7 @@ Above the data table, you can configure the following settings: |:-------------------------------|:---------------------------------------------------------------------------------------------| | Display labels or XML values? | Choose whether to show XML values or full question and choice labels in any form language in your table. | | Show group names in table headers | Decide whether column headers in the table include the name of the question group (e.g., `demographics / age`). | -| Show HXL tags | Display Humanitarian Exchange Language (HXL) tags if they were added to your form. | +| Show HXL tags | Display Humanitarian Exchange Language (HXL) tags if they were added to your form. | Within the data table, you can click a column header and select **Hide field** to remove fields you do not need, or **Freeze field** to keep frequently used fields visible while you scroll. diff --git a/source/welcome.md b/source/welcome.md index b181eef25..60c4a980a 100644 --- a/source/welcome.md +++ b/source/welcome.md @@ -47,7 +47,7 @@ Standardize data and streamline form building by creating form templates and usi ![Library](/images/welcome/library.png)

-For more information about the KoboToolbox question library, see Using the question library. +For more information about the KoboToolbox question library, see Using the KoboToolbox question library.

## Collecting data