====== csRanks - Rank constant sum values for piping into other questions ======
The **csRanks** function ranks constant sum values into embedded data fields for piping both labels and values into other questions. For example, the label and value of the top ranked item will be saved in embedded data fields named something like 'Q1.rank.text.1' and 'Q1.rank.value.1', the label and value of the second ranked item will be saved in embedded data fields named something like 'Q1.rank.text.2' and 'Q1.rank.value.2', etc.

The csRanks function gets added to the constant sum 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. It also provides a way of saving ranking data (i.e., fields for the top ranked item and its value).

Features: 
  * Supports constant sum questions with or without total option checked.
  * Supports ranking in descending or ascending order (descending is default)
  * Supports two modes: allow ties or break ties
  * Supports tie breaking based on question randomization or one or more of these other choice fields: text, id, variable name, html, or recode. Other choices fields can be sorted ascending or descending for tie breaking purposes.  
  * Saves labels of choices to embedded data fields. Labels can be saved as HTML, text only, variable names, or entered text.
  * Saves values of choices to embedded data fields.
  * Ranked items can be piped on the next page - no additional questions, blocks, or survey flow logic needed.
  * Translation friendly
  * Flexible embedded data field naming
  * Optionally rank items with zero values
  * Sets embedded data fields for all ranked items (1, 2, 3, etc.) and last ranked item.

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 csRanks 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 csRanks function JS:
<code>
<script>/*Paste csRanks function JS here*/</script>
</code>
Alternatively, paste the csRanks 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 csRanks function to apply it to a ranking question as follows:
<code>
Qualtrics.SurveyEngine.addOnload(function() {
	csRanks(this);
});
</code>

To override the default options, specify the desired **[[csRanks#options|options]]** in the second function argument as an object. For example:
<code>
Qualtrics.SurveyEngine.addOnload(function() {
	csRanks(this,{prefix:"Q1"});
});
</code>
===== Embedded Fields =====
The csRanks function saves both labels and values of ranked items into embedded data fields. When ties are allowed, labels of tied items are joined together (e.g., Item 1, Item 2, and Item 3).
==== Embedded Field Names ====
=== Ranked ===
Labels: {prefix}{delim}{rankText}{delim}{labelText}{delim}{rank number} (e.g., Q1.rank.text.1)

Values: {prefix}{delim}{rankText}{delim}{recodeText}{delim}{rank number} (e.g., Q1.rank.value.1)
=== Last ===
Label: {prefix}{delim}{rankText}{delim}{labelText}{delim}{last} (e.g., Q1.rank.text.last)

Value: {prefix}{delim}{rankText}{delim}{recodeText}{delim}{last} (e.g., Q1.rank.value.last)
==== Saving Embedded Fields ====
For csRanks 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 constant sum 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 ratings, only add those embedded data fields to the survey flow. It is not necessary to save fields in order to pipe them.
===== Options =====
==== allowTies ====
**allowTies** is a boolean that specifies if ties are allowed. When **allowTies** is true, labels of choices with the same values will be combined and given the same rank. The options **[[csranks#and|and]]**, **[[csranks#join|join]]**, and **[[csranks#oxford|oxford]]** specify how labels are to be combined. When false, ties will be broken based on **[[csranks#otherSortArr|otherSortArr]]**.

Default: false
==== and ====
**and** is text used to join the last label when **[[csranks#allowTies|allowTies]]** is true. If **and** is not empty, a space is added before and after if it does not start with a comma (,), colon (:), semi-colon (;), or pipe (|). For translated surveys pipe the value from a translated question. 

Default: %%"and"%%
==== delim ====
**delim** is a delimiter used to break the embedded data field names into sections. The delimiter is placed between each section.

Default: %%"."%%
==== join ====
**join** is text used to join three or more labels when **[[csranks#allowTies|allowTies]]** is true. 

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

Default: %%"text"%%
==== last ====
**last** is text used in embedded data field names for the last ranked item in place of a rank number (e.g., Q1.rank.text.last). 

Default: %%"last"%%
==== otherSortArr ====
**otherSortArr** is an array used to specify the fields used for tie breaking. It also specifies the order of combined labels when **[[csranks#allowTies|allowTies]]** is true. An empty array (the default) means ties will be broken based on the randomized order of the choices in the question. If other fields are specified, they should be specified by field name in priority order. Add a minus sign (-) in front of the field name to specify descending order. Available fields (case sensitive) are: Text, id, VariableName, html, and Recode. For example, to specify a tie breaker of descending recode followed by choice text, the function would be called like this:
<code>
csRanks(this,{otherSortArr:['-Recode','Text']});
</code>

Default: []
==== oxford ====
**oxford** is text used before **[[csranks#and|and]]** when **[[csranks#allowTies|allowTies]]** is true and three or more labels are joined. In the text "Item1, Item2, and Item3" the comma before "and" is called an Oxford comma. Change **oxford** to %%""%% to remove the Oxford comma. 

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

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

Default: %%"rank"%%
==== rankZero ====
**rankZero** is a boolean that specifies if choices with a value of zero should be included in ranking. 

Default: false
==== sortAsc ====
**sortAsc** is a boolean used to rank choices based on ascending values when set to true. 

Default: false
==== textEnter ====
**textEnter** is a boolean used to capture entered text for the choice label when ‘Allow text’ is turned on. 

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

Default: false
==== textVar ====
**textVar** is a boolean used to save choice variable names instead of choice text when **[[csranks#textOnly|textOnly]]** AND **textVar** are true. 

Default: false
==== valueText ====
**valueText** is used in embedded data field names that capture values of ranked items. 

Default: %%"value"%%
====== Qualtrics Wiki ======
[[start|Qualtrics Wiki]]