diff --git a/docs/end-user-guide-carry-forward-responses.md b/docs/end-user-guide-carry-forward-responses.md new file mode 100644 index 000000000..d054e92d4 --- /dev/null +++ b/docs/end-user-guide-carry-forward-responses.md @@ -0,0 +1,104 @@ +--- +title: Carry Forward Responses - SurveyJS +description: Learn how to use Carry Forward Responses technique in your SurveyJS forms. Carry forward involves taking certain answer choices from a previous question and carrying them forward to a subsequent question. This method is useful for follow-up questions where only selected or unselected items from a previous question are relevant. +--- + +# How to Carry Forward Responses + +## About Carry Forward Responses + +Carry Forward is a survey technique that takes selected responses from one question and copies them to a subsequent question. This method ensures that follow-up questions are directly relevant to the respondent's previous answers. You can use the feature for follow-up questions that require only the items selected from a previous question or, conversely, only the items that were not selected. + +## Supported Question Types + +Any multi-select question type from the list below can be used as both a source and a target question: + +- [Checkboxes](https://surveyjs.io/form-library/examples/create-checkboxes-question-in-javascript/) +- [Dropdown](https://surveyjs.io/form-library/examples/create-dropdown-menu-in-javascript/) +- [Tag Box](https://surveyjs.io/form-library/examples/how-to-create-multiselect-tag-box/) +- [Image Picker](https://surveyjs.io/form-library/examples/image-picker-question/) +- [Radio Group](https://surveyjs.io/form-library/examples/single-select-radio-button-group/) +- [Ranking](https://surveyjs.io/form-library/examples/add-ranking-question-to-form/) + +## Types of Choices to Carry Forward + +The **Which choice options to copy** property allows you to select what choices of a source question you want to use in the follow-up question: + +- **All** - Copies all choice options from the selected source question. +- **Selected** - Dynamically copies only selected choice options. +- **Unselected** - Dynamically copies only unselected choice options. + +How to use Carry Forward Responses in SurveyJS Form Builder + +The **None** and **Other** choice options are passed by default if enabled in the source question. + +## Limitations + +When choosing the source and target question types for Carry Forward, take into account the following factors: + +- Radio Button Group and Dropdown questions do not support multiple selections; they can pass only one selected choice. For this reason, it's recommended to use them as source questions only if unselected or all choices are required for the follow-up question. +- An Image Picker question passes selected, unselected, or all image/video files if the follow-up question is also an Image Picker type. Otherwise, it passes image/video captions. You can change the selection type—single or multiple—by using the **Allow multiple selection** checkbox. + How to allow multiple selection in the Image Picker +- A Ranking question can be used as a source of all choices only, unless the **Allow selective ranking** property checkbox is selected. + How to enable selective ranking in the Ranking question +- Checkboxes and Multi-Select Dropdown (Tag Box) can pass one or multiple selected choices, depending on the value set for the **Maximum choices to select** property. + How to set the maximum number of choices a user can select + +## Examples + +### Carry Forward Selected Responses from a Tag Box to a Dropdown + +1. Add a **Multi-Select Dropdown** question to the design surface. +2. Assign it a **Question name** (ID) and a user-friendly **Question title**. + Tag Box configuration +3. Under **Choice Options**, populate the Tag Box with choices. +4. Add a **Dropdown** question to the design surface. +5. Under **Choice Options**, locate the **Copy choices from the following question** setting and select a source question ID (**Question name** value) from the drop-down list of available questions. +6. Locate the **Which choice options to copy** setting and click **Selected**. + How to carry forward selected responses from a Tag Box to a Dropdown +7. Switch to the **Preview** tab to test the configuration. + Preview carrying forward selected responses from a Tag Box to a Dropdown + +### Carry Forward Selected Responses from Checkboxes to a Radio Button Group + +1. Add a **Checkboxes** question to the design surface. +2. Assign it a **Question name** (ID) and a user-friendly **Question title**. + Checkboxes configuration +3. Under **Choice Options**, populate the Checkboxes question with choices. +4. To restrict the number of items a respondent can select, under **Choice Options**, locate the **Minimum choices to select** and **Maximum choices to select** settings and enter the required values. + Restrict the number of items a respondent can select in a Checkboxes question +5. Add a **Radio Button Group** question to the design surface. +6. Under **Choice Options**, locate the **Copy choices from the following question** setting and select a source question ID (**Question name** value) from the drop-down list of available questions. +7. Locate the **Which choice options to copy** setting and click **Selected**. + Carry forward selected responses from a Checkboxes question to a Radio Button Group +8. Switch to the **Preview** tab to test the configuration. + Preview carrying forward selected responses from a Checkboxes question to a Radio Button Group + +### Carry Forward Unselected Responses Between Radio Button Groups + +1. Add a **Radio Button Group** question to the design surface. +2. Assign it a **Question name** (ID) and a user-friendly **Question title**. +3. Under **Choice Options**, populate the Radio Button Group with choices. +4. Add another **Radio Button Group** question to the design surface. +5. Under **Choice Options**, locate the **Copy choices from the following question** setting and select a source question ID (**Question name** value) from the drop-down list of available questions. +6. Locate the **Which choice options to copy** setting and click **Unselected**. + Carry forward unselected responses from a Radio Button Group to another Radio Button Group +7. Switch to the **Preview** tab to test the configuration. + Preview carrying forward unselected responses from a Radio Button Group to another Radio Button Group + +### Carry Forward Selected Responses from a Tag Box to a Ranking Question + +1. Add a **Multi-Select Dropdown** question to the design surface. +2. Assign it a **Question name** (ID) and a user-friendly **Question title**. +3. Under **Choice Options**, populate the Tag Box with choices. +4. Optionally, specify the **Choice Options** > **Maximum choices to select** setting to limit the number of choices a respondent can select. + How to set the maximum choices to select for a Tag Box +5. Add a **Ranking** question to the design surface. +6. Under **General**, select the **Allow selective ranking** checkbox. +7. Under **Choice Options**, locate the **Copy choices from the following question** setting and select a source question ID (**Question name** value) from the drop-down list of available questions. +8. Locate the **Which choice options to copy** setting and click **Selected**. + How to carry forward responses to a Ranking question and enable selective ranking +9. Set a required value in the **Maximum choices to select** input field. + Limit the number of choices to select in a Ranking question with enabled selective ranking +10. Switch to the **Preview** tab to test the configuration. +Preview carrying forward selected responses from a Tag Box to a Ranking question diff --git a/docs/end-user-guide-how-to-format-user-input-for-single-line-fields.md b/docs/end-user-guide-how-to-format-user-input-for-single-line-fields.md index b25754d39..4a51c951c 100644 --- a/docs/end-user-guide-how-to-format-user-input-for-single-line-fields.md +++ b/docs/end-user-guide-how-to-format-user-input-for-single-line-fields.md @@ -70,7 +70,7 @@ The Range input type allows users to select a numeric value within a specified r ### Phone Number -The Phone Number input type is used for fields that require telephone numbers. If you want to apply a specific phone number format, e.g. +1 (234) 555-12-34, you can use [input masking](https://surveyjs.io/form-library/examples/masked-input-fields/). +The Phone Number input type is used for fields that require telephone numbers. If you want to apply a specific phone number format, e.g. +1 (234) 555-12-34, you can use [input masking](https://surveyjs.io/form-library/examples/masked-input-fields/) instead. ### Text diff --git a/docs/images/eud-allow-multiple-selection-cf.png b/docs/images/eud-allow-multiple-selection-cf.png new file mode 100644 index 000000000..b934e24c2 Binary files /dev/null and b/docs/images/eud-allow-multiple-selection-cf.png differ diff --git a/docs/images/eud-allow-selective-ranking.png b/docs/images/eud-allow-selective-ranking.png new file mode 100644 index 000000000..7dae2b8bd Binary files /dev/null and b/docs/images/eud-allow-selective-ranking.png differ diff --git a/docs/images/eud-checkboxes-radio-button-group.png b/docs/images/eud-checkboxes-radio-button-group.png new file mode 100644 index 000000000..09213c8f0 Binary files /dev/null and b/docs/images/eud-checkboxes-radio-button-group.png differ diff --git a/docs/images/eud-checkboxes.png b/docs/images/eud-checkboxes.png new file mode 100644 index 000000000..d3ad0d9f3 Binary files /dev/null and b/docs/images/eud-checkboxes.png differ diff --git a/docs/images/eud-dropdown.png b/docs/images/eud-dropdown.png new file mode 100644 index 000000000..0049d8f33 Binary files /dev/null and b/docs/images/eud-dropdown.png differ diff --git a/docs/images/eud-example-one.png b/docs/images/eud-example-one.png new file mode 100644 index 000000000..3dd2d05cb Binary files /dev/null and b/docs/images/eud-example-one.png differ diff --git a/docs/images/eud-max-choices-to-select-tag-box.png b/docs/images/eud-max-choices-to-select-tag-box.png new file mode 100644 index 000000000..42f7131b7 Binary files /dev/null and b/docs/images/eud-max-choices-to-select-tag-box.png differ diff --git a/docs/images/eud-max-choices-to-select.png b/docs/images/eud-max-choices-to-select.png new file mode 100644 index 000000000..a3b7f682f Binary files /dev/null and b/docs/images/eud-max-choices-to-select.png differ diff --git a/docs/images/eud-max-ranking.png b/docs/images/eud-max-ranking.png new file mode 100644 index 000000000..98e290f80 Binary files /dev/null and b/docs/images/eud-max-ranking.png differ diff --git a/docs/images/eud-min-max-cf.png b/docs/images/eud-min-max-cf.png new file mode 100644 index 000000000..84587e30d Binary files /dev/null and b/docs/images/eud-min-max-cf.png differ diff --git a/docs/images/eud-radio-button-group.png b/docs/images/eud-radio-button-group.png new file mode 100644 index 000000000..d8d37571f Binary files /dev/null and b/docs/images/eud-radio-button-group.png differ diff --git a/docs/images/eud-radio-to-radio.png b/docs/images/eud-radio-to-radio.png new file mode 100644 index 000000000..1bff5ba5f Binary files /dev/null and b/docs/images/eud-radio-to-radio.png differ diff --git a/docs/images/eud-ranking.png b/docs/images/eud-ranking.png new file mode 100644 index 000000000..12a27fb82 Binary files /dev/null and b/docs/images/eud-ranking.png differ diff --git a/docs/images/eud-tag-box-to-ranking.png b/docs/images/eud-tag-box-to-ranking.png new file mode 100644 index 000000000..42b23b06a Binary files /dev/null and b/docs/images/eud-tag-box-to-ranking.png differ diff --git a/docs/images/eud-tag-box.png b/docs/images/eud-tag-box.png new file mode 100644 index 000000000..237034b96 Binary files /dev/null and b/docs/images/eud-tag-box.png differ diff --git a/docs/images/eud-unselected.png b/docs/images/eud-unselected.png new file mode 100644 index 000000000..91f852ce2 Binary files /dev/null and b/docs/images/eud-unselected.png differ diff --git a/docs/images/eud-which-choices-to-copy.png b/docs/images/eud-which-choices-to-copy.png new file mode 100644 index 000000000..c805e2b9c Binary files /dev/null and b/docs/images/eud-which-choices-to-copy.png differ diff --git a/docs/sidebar.json b/docs/sidebar.json index 59ddd3638..bf13380e4 100644 --- a/docs/sidebar.json +++ b/docs/sidebar.json @@ -92,6 +92,10 @@ "Name": "end-user-guide-branching-logic", "Title": "Branching Logic" }, + { + "Name": "end-user-guide-carry-forward-responses", + "Title": "Carry Forward Responses" + }, { "Name": "end-user-guide-add-navigation-elements-to-form", "Title": "Form Navigation"