====== mcSubChoices - Multiple choice with sub-choices ======
The **mcSubChoices** function enables the addition of sub-choices to a multi-select multiple choice question. When a primary choice is selected, the sub-choices for the primary choice are displayed and can be selected. Optional exclusive options allow the multi-select to act like a single single select.  

Here is a quick video demonstration:\\
{{ ::mcSubChoices.mp4?650 |mcSubChoices Demonstration}}

Features include:
  * Option to turn **[[mcsubchoices#subdeselect|automatic deselection of sub-choices]]** on or off
  * Exclusive group (parent of sub-choices) option
  * Exclusive sub-choices (children) option
  * Supports randomization of sub-choices
  * Supports anchoring of sub-choices when randomized

This function is available for a reasonable fee. Contact **[[https://community.qualtrics.com/inbox/conversation?with=373|TomG]]** on the Qualtrics Community to learn more.
===== Set-up Instructions =====
==== Survey Header ====
Add the mcSubChoices function to the survey header to make it available to any question in the survey. Go to Look & Feel -> General -> Header edit -> {{::icon_source.jpg?20|}} and paste the provided mcSubChoices function JS:
<code>
<script>/*Paste mcSubChoices function JS here*/</script>
</code>
Alternatively, paste the mcSubChoices function JS into a question's JS outside the existing Qualtrics functions to make it available to questions on the page.
===== Question Setup =====
==== Question Options ====
The requirements for the multiple choice question are:
  * Answer type: Allow multiple answers
  * Format: List
  * Alignment: Vertical
==== Choice Groups ====
Create a [[https://www.qualtrics.com/support/survey-platform/survey-module/editing-questions/formatting-answer-choices/#AssigntoGroup|choice group]] for each primary choice (parent) and its sub-choices (children). There should be **__one__** **[[mcsubchoices#parent_choices|parent choice]]** per choice group.

Do NOT hide the choice group title. That will be handled by the mcSubChoices function.

The choice group selection must be set to 'Multiple Answer Within Question' (the default).

The choices within the choice group may be randomized if desired.
==== Parent Choices ====
To specify a choice as a primary choice (parent), put the choice text inside a span with the class ''parent''. For example:
<code>
<span class="parent">Parent choice text</span>
</code>
=== Exclusive Group ===
To make a group (parent and it's children) exclusive to other groups and choices, add the class ''exGroup'' to the parent. For example:
<code>
<span class="parent exGroup">Parent choice text</span>
</code>
=== Exclusive Sub-choices ===
To make sub-choices within a group exclusive (single select), add the class ''exChild'' to the parent. For example:
<code>
<span class="parent exChild">Parent choice text</span>
</code>
To make both group and sub-choices exclusive add both classes to the parent:
<code>
<span class="parent exGroup exChild">Parent choice text</span>
</code>
==== Anchoring Sub-choices ====
To anchor a sub-choice (child) when a choice group is randomized, put the choice text inside a span with the class ''anchor''. For example:
<code>
<span class="anchor">Other</span>
</code>
==== Question JavaScript ====
Add JS to call the mcSubChoices function to apply it to the multiple choice question as follows:
<code>
Qualtrics.SurveyEngine.addOnload(function() {
	mcSubChoices(this);
});
</code>
To override the default options, specify the desired **[[mcsubchoices#options|options]]** is the second function argument as an object. For example:
<code>
Qualtrics.SurveyEngine.addOnload(function() {
	mcSubChoices(this,{subDeselect:false,subIndent:'20px'});
});
</code>
===== Options =====
==== align ====
**align** is a string that specifies the alignment of the choice text. 

Default: 'left'
==== subDeselect ====
**subDeselect** is a boolean that specifies if sub-choices (children) should be automatically deselected when the primary choice (parent) is deselected. When **subDeselect** is false, the parent cannot be deselected unless all the children are already deselected. 

Default: true
==== subIndent ====
**subIndent** is a string that specifies how much the sub-choices (children) should be indented. 

Default: %%"10px"%%
====== Qualtrics Wiki ======
[[start|Qualtrics Wiki]]