====== 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>