====== Assignment ======

Different stimuli are shown in an assignment question, which the participant has to assign to one of two (or more: max. 10) categories. The categories or options (e.g. "good" or "bad") are the same for each stimulus. Stimuli are assigned by clicking on the option or with a single keystroke. The latter is useful if the response time should be recorded.

{{:en:create:questions:exp.assignment.png?nolink|Assignment Example}}

  * Assigning items works in a similar way to a single block in the [[:en:create:questions:iat|Implicit Association Test (IAT)]].
  * Response time is measured in milliseconds with an accuracy of approx. 10 ms. [[:en:glossary#javascript|JavaScript]] is used to achieve this level of accuracy -- this means loading times between stimuli are omitted.
  * An introduction will be shown before the first stimulus. Selecting one of the options begins the assignment.
  * The "Next" button is hidden while working through the question. After the last stimulus has been categorized -- depending on the settings in the question -- the Next button will be displayed or the questionnaire will switch automatically to the next page.
  * Depending on previous responses, stimuli can be skipped by using a little bit of JavaScript (see below).

**Tip:** Graphics can also be used as options (e.g. thumbs up/down, emoticons). HTML code to integrate the graphic is used as the text for the option ([[:en:create:images|Images in the Questionnaire]]).

===== Operating with Keys =====

Selection keys differ depending on the number of options: 

  * Two options:\\ Left-hand option:  D, F, G, V, B, 1, 2, 3, 4, 5, <-, Num4, Num1\\ Right-hand option: K, J, H, N, M, 6, 7, 8, 9, 0, ->, Num3, Num6
  * Three options:\\ Left-hand option: 1, Num1, Num4, <-\\ Middle option: 2, Num2, Num5, Arrow down, Arrow up\\ Right-hand option: 3, Num3, Num6, ->  
  * Four to ten options:\\ Numerical keys 1 to 10 (depending on the number of options)


===== Filtering =====

The different stimuli are loaded onto the same page in the questionnaire and shown in succession by using JavaScript -- responses are not transmitted to the server until the question has been completed. Classic [[en:create:filters|filters]] using PHP code therefore cannot be implemented in order to skip individual stimuli (items), or to end assigning of items prematurely. 

Nevertheless, this question type offers an opportunity for filters to be used. A Javascript function is defined in order to this. After this function is applied in the question through ''setCallbackSelect()'', it will be invoked during each assignment (selection). The function is informed each time as to which stimulus was just assigned and which option was selected. Depending on what the function returns, the response will be ignored, the question will jump to another stimulus, or the question will be terminated.

The callback function can return the following numerical values:

  * ''-1'' Terminate assignment question
  * ''-2'' Ignore keystroke, show selection again
  * <number> Jump to the stimulus with the corresponding ID
  * ''0'' or ''false'' Resume with the next stimulus, as if there was no filter

**Caution:** If the participant jumps to a stimulus that has already been assigned, it will be shown again and the old assignment and measured response time will be overwritten.



==== An Example of a Filter ====

The following Javascript code can be saved as a text element. Drag the text element into the questionnaire below the question. The function ''selFilter()'' included provides the following filtering:

  - If the first (left-hand) option is selected for the first stimulus, the second item will be skipped, and it will continue directly to item 3.
  - The second stimulus can only be assigned to the right-hand (second) category. Selecting the left-hand option will be ignored.
  - If the second option is selected for a later stimulus (third, fourth, ...), the assignment will be terminated immediately.

<code javascript>
<script type="text/javascript">
<!--

// Filter function
function selFilter(item, option) {
  // The first filter responds when the left-hand option (1) was selected for the first stimulus
  if ((item == 1) && (option == 1)) {
    // Continue with item no. 3
    return 3;
  }
  // Ignore left-hand category (1) in the second stimulus
  if ((item == 2) && (option == 1)) {
    // Ignore
    return -2;
  }
  // The third filter should only respond from stimulus no. 3 onwards
  if (item >= 3) {
    // If the right-hand category (2) is clicked on, the question is over
    if (option == 2) {
      // End
      return -1;
    }
  }
}

// Assignment of items will only be activated once the page has been fully loaded.
// Therefore, attachEvent() has to be used in order to allocate the callback function only once
// loading is complete. 
// 
// Note: Instead of assignmentAB01, "assignment" plus the question ID has to be used here.

SoSciTools.attachEvent(window, "load", function() {
    assignmentAB01.setCallbackSelect(selFilter);
});

// -->
</script>
</code>

===== JavaScript Connection =====

The JavaScript function ''setCallbackSelect()'' (see above) is primarily designed for filter guidance. In addition, the assignment task supports events, which allow JavaScript to intervene directly. The following events are triggered by the container of the question:

  * ''fixation'' -- A pause is placed between two stimuli (items), e.g. a fixation cross. This event is only triggered if a pause is set between the stimuli. The following attributes are available in the ''detail'' property of the event:
    * ''evt.detail.question'' -- Identification of the question
    * ''evt.detail.item'' -- Identification (ID) of the item, which is displayed after the pause
    * ''evt.detail.node'' -- The HTML element that is displayed in the pause
    * ''evt.detail.duration'' -- The duration of the pause [ms].
  * ''prime'' -- A prime that may be displayed before a stimulus. This event is only triggered if a prime has been defined for the item. The following attributes are available:
    * ''evt.detail.question'' -- Identification of the question
    * ''evt.detail.item'' -- Identification (ID) of the item, which is displayed after the prime
    * ''evt.detail.node'' -- The HTML element that is displayed as Prime
    * ''evt.detail.duration'' -- The duration for which the Prime is displayed [ms].
  * ''present'' -- The actual stimulus or a text is displayed.
    * ''evt.detail.question'' -- Identification of the question
    * ''evt.detail.type'' -- Type of display (''"intro"''=text at the beginning, ''"outro"''=text after the last item, ''"item"''=one item/stimulus is displayed)
    * ''evt.detail.item'' -- Identification (ID) of the displayed item/stimulus, ''null'' if a text is displayed
    * ''evt.detail.node'' -- The HTML element that is displayed as stimulus or text
  * ''select'' -- The respondent has selected a category. If this event is caught with ''evt.preventDefault()'', the item will be displayed again (possibly including Prime) and a function registered with ''setCallbackSelect()'' will not be called. The following attributes are available:
    * ''evt.detail.question'' -- Identification of the question
    * ''evt.detail.item'' -- Identification (ID) of the stimulus
    * ''evt.detail.option'' -- The selected category (starting with 1)

The function ''setPrimeTimes()'' can be used to individually set the presentation duration for primes (if defined for stimuli/items).

The function ''setPauseTimes()'' can be used to set the duration of the pause between items individually, during which the fixation is displayed if necessary.

The ''selectOption()'' function triggers the same reaction as clicking on a response option. The number of the option (starting with 1) is entered in brackets. 





==== Playing Audio ====

If the stimuli (also) contain an audio file, the ''present'' event can be used to play it at the right time. For example, stimuli 1 and 2 would have the following content:

<code html>
audio sample 1
<audio id="audio1" preload="auto" style="position: absolute; left: -5000px;">
  <source src="example_foo.mp3" type="audio/mpeg" />
</audio>
</code>

<code html>
audio sample 2
<audio id="audio2" preload="auto" style="position: absolute; left: -5000px;">
  <source src="example_bar.mp3" type="audio/mpeg" />
</audio>
</code>

The following HTML/JavaScript code is placed under the question (here e.g. ''AB01''):

<code javascript>
<script type="text/javascript">
<!--
var question = document.getElementById("AB01_qst");
question.addEventListener("present", function(evt) {
  var item = evt.detail.item;
  var audio = document.getElementById("audio" + item);
  if (audio) {
    audio.play();
  }
});
// -->
</script>
</code>

Note that the HTML IDs for the ''<audio>''-elements are ''audio1'' and ''audio2''. This can easily be composed of ''"audio"'' and the item ID. If they were other identifiers, the function would have to use an IF-filter:

<code javascript>
<script type="text/javascript">
<!--
var question = document.getElementById("AB01_qst");
question.addEventListener("present", function(evt) {
  var item = evt.detail.item;
  var audio = null;
  if (item == 1) {
    var audio = document.getElementById("audio1");
  } else if (item == 2) {
    var audio = document.getElementById("audio2");
  }
  if (audio) {
    audio.play();
  }
});
// -->
</script>
</code>


==== Vary times for primes ====

The following JavaScript changes the presentation duration for the primes defined in items 1, 2 and 3. The number behind the item number indicates the display duration in milliseconds (ms).

<code html>
<script type="text/javascript">
window.addEventListener("load", function() {
    s2.AB01.setPrimeTimes({
        1: 2000,
        2: 500,
        3: 1000
    });
});
</script>
</code>


If the display times for the primes are to be varied dynamically, the list of prime display times can also be created in the PHP code and then transferred to the JavaScript code using placeholders. The JavaScript-Code would be stored as text (representation: "HTML-Code") with placeholder (''%primeTimes%'') in the question catalog.

<code html>
<script type="text/javascript">
window.addEventListener("load", function() {
    s2.%question%.setPrimeTimes(%randomTimes%);
});
</script>
</code>

The PHP code could then look like this. It would store the randomly chosen times in the internal variables of the question "AB03".

<code php>
$times = [];
for ($i=1; $i<=20; $i++) {
  $randomTime = random(100, 1000);
  put(id('AB03', $i), $randomTime);
  $times[$i] = $randomTime;
}

// Include text module AB02 and thereby
// use the placeholders for question identifier and times
show('AB02', [
    '%question%' => 'AB01',
    '%randomTimes%' => json_encode($times)
]);
</code>


==== Vary Time Limit ====

In the assignment task, a //time limit per stimulus// can be defined. If the respondent does not select an answer within this period, the item is skipped. This time limit initially applies to all items in the question.

With the JavaScript method ''setTimeouts()'' the time limit for each item can be adjusted individually. The syntax corresponds to that of ''setPrimeTimes()''.

The following JavaScript sets a time limit of 1200 milliseconds (ms) for the third item in the assignment task "AB01" and a time limit of 2000 ms for the fifth item.


<code html>
<script type="text/javascript">
window.addEventListener("load", function() {
    s2.AB01.setTimeouts({
        3: 1200,
        5: 2000
    });
});
</script>

</code>
===== Automatic start =====

There are situations where the switch from the introduction text to the first stimulus should be timed. The following JavaScript code triggers this change 2 seconds after the page is fully loaded. The identifier "AB01" must be exchanged for the identifier of the assignment task.

<code javascript>
window.addEventListener("load", function() {
    window.setTimeout(function() {
        s2.AB01.selectOption(1);
    }, 1000);
});
</code>


===== Multi-stage priming =====

By default, the assignment task can display a fixation cross (same for all items, to be set in the question) and a prime (to be set in the respective item) for the actual stimulus (items). But for some designs this is insufficient. With a little JavaScript it is also possible to display several contents before the actual stimulus. The time slot that is actually reserved for the fixation cross is used for this.

The following example deals with the following presentation sequence:
  - Display of a fixation cross (750ms)
  - Display of the text "HE" or "SHE" (500ms)
  - Display a number between 1 and 3 (500ms)
  - Display of the item -- with selection option "Yes" or "No"

In the question of type "Assignment task" (e.g. "ZA01") are set for this:

  * A //text before the first stimulus//, e.g. "Click to start".
  * A // fixed height for stimuli//, in this case 120 pixels, so that the display does not "jump" between the fixation cross and the narrower text
  * In the tab //answer categories// the categories are labeled with "Yes" and "No" and
  * the checkmark at //allow selection of an option via keyboard// is removed, because the respondents should only click (optional)
  * In the tab //flow control// the //pause between stimuli// is set to 1750ms, so that fixation cross (750ms) plus two text primes (500ms) can be placed in it.
  * The //time limit per stimulus// can be set if necessary.

After saving the question "ZA01" a text "ZA02" is created in the question catalog (// Description// e.g. "JavaScript to ZA01"). As //display// "HTML-Code" is chosen here. The following content now ensures that the pause with the fixation cross is replaced by the above sequence. The replacement is done by setting ''pause.innerHTML''.

<code javascript>
<script type="text/javascript">
<!--

function AssignmentPlus(qstID, contents) {
  // First we need the HTML element that shows the fixation cross
  var outer = document.getElementById(qstID + "_pause");
  var pause = outer.getElementsByTagName("td").item(0);
  // A minimum height would be helpful so that the buttons do not "jump".
  pause.style.height = "120px";

  function showContent(evt) {
    // Determine which item is shown immediately
    var item = evt.detail.item;
    // Use corresponding part from the list
    var show = contents["i" + item];

    // Display content according to schedule
    // First (direct) a fixation cross (750ms)
    pause.innerHTML = '<img src="../images/fixation.default.png" alt="+">';
    // After 750ms then the first part of the content (for 500ms)
    window.setTimeout(function() {
      pause.innerHTML =  show[0];
    }, 750);
    // After another 500ms (in total after 1250ms) the second part of the contents (for 500ms)
    window.setTimeout(function() {
      pause.innerHTML =  show[1];
    }, 1250);
    // Further to the item it goes then after 1250+500 = 1750ms
    // This is the total duration for fixation (to be set in the question)
  }

  // Call of the method at each fixation pause
  %qst%_qst.addEventListener("fixation", showContent);
}

// Initializing the AssignmentPlus instance
SoSciTools.attachEvent(window, "load", function() {
    // Contents to be shown with the individual items
    // (placeholders can also be used here)
    new AssignmentPlus("%qst%", {
      i1 : ["HE", "2"],
      i2 : ["HE", "1"],
      i3 : ["SHE", "3"],
    });
});

// -->
</script>
</code>

At the end of the JavaScript code an array is defined, which content should be displayed for each item. Here are exemplarily only the contents for 3 items. If necessary, placeholders can also be used here, e.g. if randomization or rotation is required.

Finally, a little PHP code is required to provide the placeholder ''%qst%'' with the identification of the assignment task ("ZA01"). There are different ways to do this -- the following PHP code includes both elements (the question and the HTML/JavaScript code) and fills the placeholder:

<code php>
show('ZA01');
show('ZA02', array(
  '%qst%' => 'ZA01'
));
</code>

The PHP-Code stands alone on a questionnaire page. The two elements must not (!) be dragged into the page in addition.