====== mcAlphabetize - Alphabetize choices on-the-fly in all languages ======
The mcAlphabetize function arranges multiple choice choices into alphabetical order on-the-fly. It is useful for translated surveys where you want the choices in alphabetical order for every language. It is also useful if you don't want to manually alphabetize each time you add a choice to a question.

Functionality includes:
  * Works with vertical single answer, vertical multi-answer, dropdown list, select box and multi-select box
  * Alphabetizes based on the current language
  * Supports anchoring of choices to the bottom of the list
  * Compatible with **[[mccolumns|mcColumns]]** (a multiple choice responsive columns function)

mcAlphabetize currently does **not** support choice groups.

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.

To alphabetize options in side-by-side dropdowns on-the-fly, see **[[sbsSelectAlphabetize|sbsSelectAlphabetize]]**. To alphabetize drill-down dropdowns on-the-fly, see **[[ddAlphabetize|ddAlphabetize]]**.

===== Set-up Instructions =====
==== Survey Header ====
Add the mcAlphabetize 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 mcAlphabetize function JS:
<code>
<script>/*Paste mcAlphabetize function JS here*/</script>
</code>
Alternatively, paste the mcAlphabetize function JS into a question's JS outside the existing Qualtrics functions to make it available to questions on the page.
==== Multiple Choice Question ====
=== Question Settings ===
Any "Answers" setting is valid.

If "Answers" is set to either "Single Answer" or "Multiple Answer", "Position" should be set to "Vertical" (fully compatible with **[[mccolumns|mcColumns]]** if a column layout is desired).
=== Question JavaScript ===
Add JS to call the mcAlphabetize function to apply it to the Multiple Choice question as follows:
<code>
Qualtrics.SurveyEngine.addOnload(function() {
	mcAlphabetize(this);
});
</code>

For anchored choices, use the **[[mcalphabetize#anchors|anchors]]** option to specify the choice ids as an array in the order the choices should be listed. For example:
<code>
Qualtrics.SurveyEngine.addOnload(function() {
	mcAlphabetize(this,{anchors:[7,8]});
});
</code>
===== Options =====
==== anchors ====
**anchors** specifies the array of choice ids that should be anchored to the bottom of the list.

For multi-select boxes, the choice ids are specified as "QR~QIDxx~id" where 'QIDxx' is the QID of the question and 'id' is the choice id. For all other answer types, the choice id is a number or a number preceded by 'x' for carry forward questions.

To identify choice ids, preview the question and use the Inspect feature of your browser.

Default: [] (nothing anchored)
==== langs ====
**langs** is an object for mapping Qualtrics language codes to valid JavaScript locale languages for correct sorting. It is only needed if the Qualtrics language code doesn't resolve to a valid JavaScript locale language code. Of the built-in Qualtrics language only ZH-S (Simplified Chinese) and ZH-T (Traditional Chinese) don't resolve, but they are included in the **langs** object by default.

If you have created your own language code, you made need to add your language to the langs object if it doesn't automatically resolve. A new language specification would look like %%langs:{"XX":"yy"}%%.
==== qlang ====
**qlang** is the Qualtrics language code string that should be used to do the alphabetization. By default, this is the current language of the survey. 

Default: %%"${e://Field/Q_Language}"%%
====== Qualtrics Wiki ======
[[start|Qualtrics Wiki]]