====== captureRanks - Capture ranks for piping into other questions ======
The captureRanks function captures ranks and recodes from **__any__** type of ranking question into embedded data fields. For example, the label and recode of the top ranked item will be saved in embedded data fields named something like 'Q1.rank.text.1' and 'Q1.rank.recode.1', the label and recode of the second ranked item will be saved in embedded data fields named something like 'Q1.rank.text.2' and 'Q1.rank.recode.2', etc.

The captureRanks function gets added to the ranking question itself, so later sorting is not needed and ranks are available for piping on the next page. 

It's primary use is piping ranked items in order or piping any ranked items for follow-up questions (only the first and last item are natively available for piping in Qualtrics). It also provides an alternative way of saving ranking data (i.e., a field for the top ranked item instead of items with their ranks). 
  * Supports rank order questions in **__any__** format - Drag and drop, Radio buttons, Text box, and Select box.
  * Supports Pick, Group, Rank (PGR) questions with any number of groups.
  * Supports **[[bubbleburst|Bubble Burst]]** ranking.
  * Saves labels of ranked choices to embedded data fields. Labels can be saved as HTML or text only.
  * Saves recodes of ranked choices to embedded data fields.
  * Ranked items can be piped on the next page - no additional questions, blocks, or survey flow logic needed.

Here is a demo of a Pick, Group, Rank question:
{{ :captureranks.mp4?600 |captureRanks Demo}}

This function is available for a reasonable fee. Contact **[[https://community.qualtrics.com/XMcommunity/messages/add/TomG|TomG]]** on the Qualtrics Community to learn more.
===== Set-up Instructions =====
==== Survey Header ====
Add the captureRanks 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 captureRanks function JS:
<code>
<script>/*Paste captureRanks function JS here*/</script>
</code>
Alternatively, paste the captureRanks function JS into a question's JS outside the existing Qualtrics functions to make it available to questions on the page.
==== Question JavaScript ====
Add JS to call the captureRanks function to apply it to a ranking question as follows:
<code>
Qualtrics.SurveyEngine.addOnload(function() {
	captureRanks(this);
});
</code>

To override the default options, specify the desired **[[captureRanks#options|options]]** in the second function argument as an object. For example:
<code>
Qualtrics.SurveyEngine.addOnload(function() {
	captureRanks(this,{prefix:"Q1"});
});
</code>
===== Embedded Fields =====
The captureRanks function saves both labels (html or text) and recodes of ranked items into embedded data fields.
==== Embedded Field Names ====
Embedded data field names are in two formats. For PGR questions with more than one group, the embedded field names include a 'group' section.  For all other questions types (basic) there is no 'group' section.
=== Basic format ===
Labels: {prefix}{delim}{rankText}{delim}{labelText}{delim}{rank number} (e.g., Q1.rank.text.1)

Recodes: {prefix}{delim}{rankText}{delim}{recodeText}{delim}{rank number} (e.g., Q1.rank.recode.1)
=== PGR > 1 Group format ===
Labels: {prefix}{delim}{groupText}{delim}{group number}{delim}{rankText}{delim}{labelText}{delim}{rank number} (e.g., Q1.group.1.rank.text.1)

Recodes: {prefix}{delim}{groupText}{delim}{group number}{delim}{rankText}{delim}{recodeText}{delim}{rank number} (e.g., Q1.group.1.rank.recode.1)
==== Saving Embedded Fields ====
For captureRanks embedded data fields to be saved to Qualtrics response data the names must be defined as embedded fields in the survey flow. The embedded data fields must be defined before they are set in the ranking question(s). Only the fields that need to be saved need to be defined in the survey flow. For example, if you are only interested in the top 3 fields, only add those embedded data fields to the survey flow. It is not necessary to save fields in order to pipe them.
===== Options =====
==== delim ====
**delim** is a delimiter used to break the embedded data field names into sections. The delimiter is placed between each section.

Default: %%"."%%
==== groupText ====
**groupText** is the text used in the group section of the embedded data field names. The group section in only used for Pick, Group, Rank (PGR) questions with more than one group.

Default: %%"group"%%
==== labelText ====
**labelText** is used in embedded data field names that capture labels of ranked items. 

Default: %%"text"%%
==== prefix ====
**prefix**, if not blank, is used at the beginning of embedded data field names.

Default: %%""%% (empty)
==== rankText ====
**rankText** is the text used to in the rank section of embedded data field names.

Default: %%"rank"%%
==== recodeText ====
**recodeText** is used in embedded data field names that capture recodes of ranked items. 

Default: %%"recode"%%
==== textOnly ====
**textOnly** is a boolean used to remove HTML from labels when set to true. 

Default: false
====== Qualtrics Wiki ======
[[start|Qualtrics Wiki]]