====== stroopTest - Conduct a Stroop Test in Qualtrics ======
The **stroopTest** function enables for the administration of a [[https://en.wikipedia.org/wiki/Stroop_effect|Stroop Test]] in Qualtrics. Functionality includes:
  * Supports any number of tasks
  * Supports all screen sizes
  * Supports physical keyboard and touchscreen
  * Records word color, word text, congruency, answer key, correctness, and response time for each task.
  * Records score, total response time, congruent count, and incongruent count for overall test.
  * Optionally ensures 25% congruency
  * Translation friendly
  * Flexible configuration of:
     * Colors, words, and keys
     * Focus time
     * Task time
     * Result display time
     * Number of tasks
     * Correct and incorrect text/images

Here is a demo:\\
{{ :stroop.mp4?600 |stroopTest Demo}}

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 =====
==== Add Stroop Test Block to Survey ====
The stroopTest function uses Qualtrics Loop & Merge functionality. There will be one Stroop question within its own block. Set the number of loops to the number of Stroop tasks.
==== Add Form Field Question to Stroop Block ====
The stroopTest function is built upon a Qualtrics Form Field Question with six fields in this order:
  - WordColor (e.g., RED, GREEN, BLUE, YELLOW)
  - WordText (e.g., RED, GREEN, BLUE, YELLOW)
  - CongruentFlag (1 = congruent, 0 = incongruent)
  - KeyPressed (e.g., r, g, b, y)
  - CorrectFlag (1 = correct, 0 = incorrect)
  - msTime (response time in milliseconds)

The field labels can be changed. Fields are populated based on position in the list.
==== Add HTML/CSS to Stroop Question Text ====
Copy and paste the provided html/css to the Stroop question's question text. __Always__ use HTML View to edit the question's text. Adjust styles as needed.
==== Add stroopTest Function To Question ====
Copy and paste the provided stroopTest function JavaScript code to the question's JS __outside__ the existing Qualtrics functions.
==== JavaScript Function Call ====
Call the stroopTest function from the question's addOnReady function using the default settings as follows:
<code>
Qualtrics.SurveyEngine.addOnReady(function() {
	stroopTest(this);
});
</code>

To override the default options, specify the desired options in the second function argument as an object. For example:
<code>
Qualtrics.SurveyEngine.addOnReady(function() {
	stroopTest(this,{msFocus:500,{colors:{c4:{color:"FFF000"}}});
});
</code>
See **[[stroopTest#stroopTest Options|stroopTest Options]]** for details. Through the use of embedded data fields, many of the default settings are actually dynamic. See **[[stroopTest#Configuration Embedded Data Fields|Configuration Embedded Data Fields]]** for details. 
==== Add Stroop Test Instructions Question ====
In the question block just prior to the Stroop question block, add a text/graphic question with respondent instructions.
==== Update Survey Flow ====
Below is an example survey flow for a Stroop test survey. See [[strooptest#Embedded Data Fields|Embedded Data Fields]] for embedded data field definitions.\\
{{ :stroop_survey_flow.png?600 |Stroop Test Survey Flow}}
===== Embedded Data Fields =====
The stroopTest function uses specific Qualtrics Embedded Data fields to record data and as default configuration values.
==== Recorded Embedded Data Fields ====
These fields must be added to the survey flow in order to record them in the Qualtrics response data. The stroopTest function will work regardless of whether the fields are recorded or not.
=== stroopScore ===
**stroopScore** captures the total number of correct tasks. Must be initialized as empty or zero.
=== stroopTotalTime ===
**stroopTotalTime** captures the total response time (the sum of all task response times) in milliseconds. Must be initialized as empty or zero.
=== stroopCongruentCount ===
**stroopCongruentCount** captures the number of congruent tasks in the test. Must be initialized as empty or zero.
=== stroopIncongruentCount ===
**stroopIncongruentCount** captures the number of incongruent tasks in the test. Must be initialized as empty or zero.
==== Configuration Embedded Data Fields ====
These fields allow for a convenient way to set stroopTest function options without having specify them in the stroopTest function call.
=== stroopMsTimeout ===
**stroopMsTimeout** is the number of milliseconds the respondent has to complete each Stroop task. If set to zero, there is no time limit. Must be a whole number.
=== stroopMsFocus ===
**stroopMsFocus** is the number of milliseconds the respondent has to focus (display of '+') before each Stroop task. Must be a whole number.
=== stroopMsResult ===
**stroopMsResult** is the number of milliseconds the task result (e.g., Correct) will be displayed before moving to the next task. Must be a whole number.
=== stroopTasks ===
**stroopTasks** is the number of tasks in the test. __Must__ be a whole number and should __always__ match the number of loops.  It is used to calculate the number of congruent and incongruent tasks when **[[strooptest#useQuotas|useQuotas]]** is true. It is also a convenient way to record the number of tasks in the response data. 
=== padTopHide ===
**padTopHide** is used to push the form fields off the bottom of the screen during loading so the respondent doesn't see them flash on the screen. Should be set to 'padding-top:2500px'. 
===== stroopTest Options =====
**stroopTest Options** can be used to override the default configuration by providing a second argument to the stroopTest function as an object.
<code>
Qualtrics.SurveyEngine.addOnReady(function() {
	stroopTest(this,{/* options object */});
});
</code>
==== colors ====
**colors** is an object used to specify the words, colors, and keys of the four choices.  **colors** has 4 children named c1, c2, c3 and c4 for each word, color, and key combination. This option is crucial in making the stroopTest translation friendly because the key and word parameters can be piped in from a translated question so they appear in the currently selected language.

Use the css class .buttons to change the style of the virtual (i.e., touchscreen) keys.\\
Use the css class .word to change the style of the displayed word (color cannot be changed).\\ 

Default:\\
c1:{key:"R",word:"RED",color:"#FF0000"},\\
c2:{key:"G",word:"GREEN",color:"#3CFC00"},\\
c3:{key:"B",word:"BLUE",color:"#003CFF"},\\
c4:{key:"Y",word:"YELLOW",color:"#FFF600"}\\
==== correct ====
**correct** is text or an image that should be shown when the task result is correct. This parameter can be piped in from a translated question to appear in the currently selected language.

Use the css class .result to change the result (correct/wrong) style.

Default: %%"CORRECT"%%
==== debug ====
**debug** is a boolean. When true, the form fields that capture the task results are visible.

Default: false
==== hideClass ====
**hideClass** is the class name of the div to be hidden after the question loads.

Default: %%"padTopHide"%%
==== msFocus ====
**msFocus** is the number of milliseconds the respondent has to focus (display of '+") before each Stroop task. Must be a whole number.

Use the css class .focus to change the focus style.

Default: %%parseInt("${e://Field/stroopMsFocus}")%%
==== msResult ====
**msResult** is the number of milliseconds the task result (e.g., Correct) will be displayed before moving to the next task. Must be a whole number.

Use the css class .result to change the result style.

Default: %%parseInt("${e://Field/stroopMsResult}")%%
==== msTimeout ====
**msTimeout** is the number of milliseconds the respondent has to complete each Stroop task. If set to zero, there is no time limit. Must be a whole number.

Default: %%parseInt("${e://Field/stroopMsTimeout}")%%
==== tasks ====
**tasks** is the number of tasks in the test. __Must__ be a whole number and should __always__ match the number of loops. It is used to force the correct number of congruent and incongruent tasks when **[[strooptest#useQuotas|useQuotas]]** is true.

Default: %%parseInt("${e://Field/stroopTasks}")%%
==== useQuotas ====
useQuotas is a boolean.  When true, 25% of the tasks are forced to be congruent and 75% of tasks are forced to be incongruent. The number of congruent tasks is rounded if 25% of **[[strooptest#tasks|tasks]]** is not a whole number. The number of incongruent tasks is (tasks - congruent tasks). When useQuotas is false, the number of congruent and incongruent tasks are random.

Default: true
==== wrong ====
**wrong** is text or an image that should be shown when the task result is incorrect. This parameter can be piped in from a translated question to appear in the currently selected language.

Use the css class .result to change the result (correct/wrong) style.

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