====== Zuordnungsaufgabe ======

Eine Zuordnungsaufgabe zeigt unterschiedliche Stimuli und der Teilnehmer muss diese einer von zwei (oder mehr, max. 10) Kategorien zuordnen. Die Kategorien bzw. Auswahloptionen (z.B. "gut" und "schlecht") sind für jeden Stimulus dieselben. Die Zuordnung erfolg via Klick oder per Tastendruck. Letzteres ist sinnvoll, wenn die Reaktionszeit aufgezeichnet werden soll.

{{:de:create:questions:exp.assignment.png?nolink|Beispiel für Zuordnungsaufgabe}}

  * Die Zuordnungsaufgabe funktioniert ähnlich wie ein einzelner Testblock im [[:de:create:questions:iat|Impliziten Assoziationstest (IAT)]].
  * Die Reaktionszeit wird in Millisekunden mit einer Genauigkeit von ca. 10 ms aufgezeichnet. Um diese Genauigkeit zu erreichen, wird [[:de:glossary#javascript|JavaScript]] eingesetzt -- so fallen Ladezeiten zwischen den einzelnen Stimuli weg.
  * Vor dem ersten Stimulus wird ein Erklärungstext angezeigt. Durch Auswahl einer der Optionen startet die Zuordnungsaufgabe.
  * Während die Frage bearbeitet wird, ist der "Weiter"-Knopf ausgeblendet. Nach Zuordnung des letzten Stimulus wird -- je nach Einstellung in der Frage -- der Weiter-Knopf angezeigt oder automatisch zur nächsten Seite gewechselt.
  * Mit ein wenig JavaScript können Stimuli in Abhängigkeit der vorhergehenden Antworten übersprungen werden (s. unten).

**Tipp:** Für die Auswahloptionen kann man auch Grafiken verwenden (z.B. Daumen hoch/runter, Smilie). Dafür wird als Text der Auswahloption einfach der HTML-Code zum Einbinden der Grafik verwendet ([[:de:create:images|Bilder im Fragebogen]]).


===== Bedienung mit Tasten =====

Die Auswahltasten unterscheiden sich je nach Anzahl der Auswahloptionen:

  * Zwei Auswahltoptionen:\\ Linke Option: D, F, G, V, B, 1, 2, 3, 4, 5, <-, Num4, Num1\\ Rechte Option: K, J, H, N, M, 6, 7, 8, 9, 0, ->, Num3, Num6
  * Drei Auswahloptionen:\\ Linke Option: 1, Num1, Num4, <-\\ Mittlere Option: 2, Num2, Num5, Pfeil unten, Pfeil oben\\ Rechte Option: 3, Num3, Num6, ->
  * Vier bis zehn Auswahloptionen:\\ Zahlentasten 1 bis 10 (je nach Anzahl der Optionen)


===== Filterführung =====

Die unterschiedlichen Stimuli werden auf derselben Fragebogen-Seite geladen und mittels JavaScript nacheinander angezeigt  -- die Antworten werden erst nach Abschluss der Frage an den Server übermittelt. Klassische [[de:create:filters|Filter]] mittels PHP-Code sind daher nicht möglich, um einzelne Stimuli (Items) zu überspringen oder die Zuordnung vorzeitig zu beenden.

Dennoch biete die Frage eine Möglichkeit zur Filterführung. Hierfür wird eine JavaScript-Funktion definiert. Nach Anmeldung dieser Funktion in der Frage mittels ''setCallbackSelect()'' wird sie bei jeder Zuordnung (Auswahl) aufgerufen. Die Funktion bekommt jeweils mitgeteilt, welcher Stimulus gerade zugeordnet wurde und welche Option ausgewählt wurde. Je nachdem, was die Funktion antwortet, wird die Antwort ignoriert, springt die Frage zu einem anderen Stimulus oder die Frage wird beendet.

Die Callback-Funktion kann folgende Zahlenwerte zurückgeben:

  * ''-1'' Zuordnungsaufgabe beenden
  * ''-2'' Tastendruck ignorieren, Auswahl erneut anbieten
  * <Zahl> Zum Stimulus mit der entsprechenden Kennung springen
  * ''0'' oder ''false'' Regulär mit den nächsten Stimulus fortfahren

**Vorsicht:** Springt man zu einem Stimulus, der bereits zugeordnet wurde, so wird dieser erneut angezeigt und die alte Zuordnung und die gemessene Reaktionszeit werden überschrieben.


==== Beispiel für einen Filter ====

Folgender JavaScript-Code kann als Textbaustein gespeichert werden. Den Textbaustein zieht man unter der Frage in den Fragebogen. Die enthaltene Funktion ''selFilter()'' sorgt für folgende Filterung:

  - Wird beim ersten Stimulus (Item) die erste (linke) Option ausgewählt, wird das zweite Item übersprungen, also direkt weiter zu Item 3.
  - Der zweite Stimulus kann nur der rechten (zweiten) Kategorie zugeordnet werden, eine Auswahl der linken Option wird ignoriert.
  - Wird bei einem späteren Stimulus (dritter, vierter, ...) die zweite Option ausgewählt, so wird die Zuordnungsaufgabe sofort beendet.

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

// Filterfunktion
function selFilter(item, option) {
  // Der erste Filter reagiert, wenn bei Stimulus 1 die Option links (1) ausgewählt wurde
  if ((item == 1) && (option == 1)) {
    // Weiter mit Item Nr. 3
    return 3;
  }
  // Linke Kategorie (1) beim zweiten Stimulus ignorieren
  if ((item == 2) && (option == 1)) {
    // Ignorieren
    return -2;
  }
  // Der dritte Filter soll erst ab Stimulus Nr. 3 reagieren
  if (item >= 3) {
    // Wird die rechte Kategorie (2) angeklickt, ist die Frage zu Ende
    if (option == 2) {
      // Ende
      return -1;
    }
  }
}

// Die Zuordnungsaufgabe wird erst aktiviert, wenn die Seite vollständig geladen ist.
// Daher muss man attachEvent() verwenden, um die Callback-Funktion erst nach Abschluss
// des Ladevorgangs zuzuweisen.
//
// Wichtig: Statt assignmentAB01 muss hier "assignment" plus die Kennung der Frage verwendet werden

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

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


===== JavaScript-Anbindung =====

Die JavaScript-Funktion ''setCallbackSelect()'' (siehe oben) ist primär für die Filterführung ausgelegt. Daneben unterstützt die Zuordnungsaufgabe noch Ereignisse (Events), mit denen JavaScript direkt eingreifen kann. Die folgenden Ereignisse werden vom Container der Frage ausgelöst:

  * ''fixation'' -- Zwischen zwei Stimuli (Items) wird eine Pause gesetzt, welche z.B. ein Fixationskreuz anzeigt. Dieses Ereignis wird nur ausgelöst, wenn zwischen den Stimuli eine Pause eingestellt wurde. In der ''detail''-Eigenschaft des Ereignises stehen folgende Attribute zur Verfügung:
    * ''evt.detail.question'' -- Kennung der Frage
    * ''evt.detail.item'' -- Kennung (ID) des Items, welches nach der Pause angezeigt wird
    * ''evt.detail.node'' -- Das HTML-Element, welches in der Pause angezeigt wird
    * ''evt.detail.duration'' -- Die Dauer der Pause [ms]
  * ''prime'' -- Ein Prime, der eventuell vor einem Stimulus angezeigt wird. Dieses Ereignis wird nur ausgelöst, wenn für das Item ein Prime definiert wurde. Folgende Attribute sind verfügbar:
    * ''evt.detail.question'' -- Kennung der Frage
    * ''evt.detail.item'' -- Kennung (ID) des Items, welches nach dem Prime angezeigt wird
    * ''evt.detail.node'' -- Das HTML-Element, welches als Prime angezeigt wird
    * ''evt.detail.duration'' -- Die Dauer, für welche der Prime angezeigt wird [ms]
  * ''present'' -- Der eigentliche Stimulus oder ein Text wird angezeigt.
    * ''evt.detail.question'' -- Kennung der Frage
    * ''evt.detail.type'' -- Art der Anzeige (''"intro"''=Text zu Beginn, ''"outro"''=Text nach dem letzten Item, ''"item"''=Ein Item/Stimulus wird angezeigt)
    * ''evt.detail.item'' -- Kennung (ID) des angezeigten Items/Stimulus, ''null'' falls ein Text angezeigt wird
    * ''evt.detail.node'' -- Das HTML-Element, welches als Stimulus oder Text angezeigt wird
  * ''select'' -- Der Befragte hat eine Kategorie ausgewählt. Falls dieses Ereignis mittels ''evt.preventDefault()'' abgefangen wird, wird das Item erneut angezeigt (ggf. inkl. Prime) und eine mittels ''setCallbackSelect()'' registrierte Funktion wird nicht aufgerufen. Folgende Attribute stehen zur Verfügung:
    * ''evt.detail.question'' -- Kennung der Frage
    * ''evt.detail.item'' -- Kennung (ID) des Stimulus
    * ''evt.detail.option'' -- Die ausgewählte Kategorie (beginnend mit 1)

Mit der Funktion ''setPrimeTimes()'' kann die Darbietungsdauer für Primes (sofern diese für Stimuli/Items definiert wurden) individuell festgelegt werden.

Mit der Funktion ''setPauseTimes()'' kann die Dauer der Pause zwischen den Items individuell festgelegt werden, in welcher ggf. die Fixation angezeigt wird.

Die Funktion ''selectOption()'' löst dieselbe Reaktion aus wie der Klick auf eine Antwortoption. In Klammern wird die Nummer der Option (beginnend mit 1) eingetragen.


==== Audio abspielen ====

Falls die Stimuli (auch) eine Audio-Datei enthalten, kann diese über das ''present''-Ereignis zum richtigen Zeitpunkt abgespielt werden. Stimuli 1 und 2 hätte beispielsweise folgenden Inhalt:

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

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

Unter der Frage (hier z.B. ''AB01'') wird der folgende HTML-/JavaScript-Code platziert:

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

Beachten Sie, dass als HTML-IDs für die ''<audio>''-Elemente ''audio1'' und ''audio2'' gewählt wurden. Dies lässt sich einfach aus ''"audio"'' und der Item-Kennung zusammensetzen. Wären es andere Kennungen, müsste die Funktion einen IF-Filter verwenden:

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


==== Zeiten für Primes variieren ====

Das folgende JavaScript verändert die Darbietungsdauer für die Primes, welche in den Items 1, 2 und 3 definiert wurden. Die Zahl hinter der Item-Nummer gibt dabei die Anzeigedauer in Millisekunden (ms) an.

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

Falls die Anzeigezeiten für die Primes dynamisch variiiert werden sollen, kann die Liste der Prime-Anzeigedauern auch im PHP-Code erstellt und anschließend mittels Platzhalter in den JavaScript-Code übernommen werden. Der JavaScript-Code würde dabei als Text (Darstellung: "HTML-Code") mit Platzhalter (''%primeTimes%'') im Fragenkatalog abgelegt.

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

Der PHP-Code könnte dann wie folgt aussehen. Er würde die zufällig gewählten Zeiten in den internen Variablen der Frage "AB03" speichern.

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

// Textbaustein AB02 einbinden und dabei
// die Platzhalter für Frage-Kennung und die Zeiten einsetzen
show('AB02', [
    '%question%' => 'AB01',
    '%randomTimes%' => json_encode($times)
]);
</code>


==== Zeitbegrenzung variieren ====

In der Zuordnungsaufgabe kann eine //Zeitbegrenzung pro Stimulus// definiert werden. Wenn die Befragte innerhalb dieses Zeitraums keine Antwort wählt, wird das Item übersprungen. Diese zeitliche Begrenzung gilt zunächst für alle Items der Frage.

Mit der JavaScript-Methode ''setTimeouts()'' kann die Zeitbegrenzung für jedes Item individuell angepasst werden. Die Syntax entspricht jener von ''setPrimeTimes()''.

Das folgende JavaScript legt für das dritte Item in der Zuordnungsaufgabe "AB01" eine Zeitbegrenzung von 1200 Millisekunden (ms) fest und für das fünfte Item eine Zeitbegrenzung von 2000 ms.

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

===== Automatischer Start =====

Es gibt Situationen, in welchen der der Wechsel vom Einführungstext zum ersten Stimulus zeitgesteuert erfolgen soll. Der folgende JavaScript-Code löst diesen Wechsel 2 Sekunden nach dem vollständigen Laden der Seite aus. Die Kennugn "AB01" muss gegen die Kennung der Zuordnungsaufgabe getauscht werden.

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


===== Mehrstufiges Priming =====

Standardmäßig kann die Zuordnungaufgabe for dem eigentlichen Stimulus (Items) ein Fixationskreuz (bei allen Items gleich, einzustellen in der Frage) und einen Prime (einzustellen im jeweiligen Item) anzeigen. Für manche Designs ist dies jedoch unzureichend. Mit ein wenig JavaScript lassen sich auch mehrere Inhalte vor dem eigentlichen Stimulus darstellen. Dafür wird der Zeitslot genutzt, der eigentlich dem Fixationskreuz vorbehalten ist.

Das folgende Beispiel befasst sich mit folgender Präsentations-Abfolge:

  - Anzeige eines Fixationskreuzes (750ms)
  - Anzeige des Textes "ER" oder "SIE" (500ms)
  - Anzeige einer Zahl zwischen 1 und 3 (500ms)
  - Anzeige des Items -- mit Auswahloption "Ja" oder "Nein"

In der Frage vom Typ "Zuordnungsaufgabe" (z.B. "ZA01") werden dafür eingestellt:

  * Ein //Text vor dem ersten Stimulus//, z.B. "Zum Starten bitte klicken".
  * Eine //Feste Höhe für Stimuli//, in diesem Fall 120 Pixel, damit die Anzeige zwischen Fixationskreuz und dem schmaleren Text nicht "springt".
  * Im Karteireiter //Antwortkategorien// werden die Kategorien mit "Ja" und "Nein" beschriftet und
  * das Häkchen bei //Auswahl einer Option mittels Tastatur erlaubt// wird entfernt, da die Teilnehmer nur Klicken sollen (optional).
  * Im Karteireiter //Ablaufkontrolle// wird die //Pause zwischen den Stimuli// auf 1750ms gesetzt, damit Fixationskreuz (750ms) plus zwei Text-Primes (500ms) darin Platz finden.
  * Die //Zeitbegrenzung pro Stimulus// kann festgelegt werden, falls erforderlich.

Nach dem Speichern der Frage "ZA01" wird im Fragenkatalog noch ein Text "ZA02" angelegt (//Beschreibung// z.B. "JavaScript zu ZA01"). Als //Darstellung// wird hier "HTML-Code" gewählt. Der folgende Inhalt sorgt nun dafür, dass die Pause mit dem Fixationskreuz durch die o.g. Abfolge ersetzt wird. Das Ersetzen erfolgt durch Setzen von ''pause.innerHTML''.

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

function AssignmentPlus(qstID, contents) {
  // Zunächst benötigen wir das HTML-Element, welches das Fixationskreuz zeigt
  var outer = document.getElementById(qstID + "_pause");
  var pause = outer.getElementsByTagName("td").item(0);
  // Eine Mindest-Höhe wäre hilfreich, damit die Knöpfe nicht "springen"
  pause.style.height = "120px";

  function showContent(evt) {
    // Ermitteln, welches Item gleich gezeigt wird
    var item = evt.detail.item;
    // Entsprechenden Teil aus der Liste verwenden
    var show = contents["i" + item];

    // Anzeigen der Inhalte nach Zeitplan
    // Zunächst (direkt) ein Fixationskreuz (750ms)
    pause.innerHTML = '<img src="../images/fixation.default.png" alt="+">';
    // Nach 750ms dann der erste Teil des Inhalts (für 500ms)
    window.setTimeout(function() {
      pause.innerHTML =  show[0];
    }, 750);
    // Nach weiteren 500ms (insg. also nach 1250ms) der zweite Teil des Inhalts (für 500ms)
    window.setTimeout(function() {
      pause.innerHTML =  show[1];
    }, 1250);
    // Weiter zum Item geht es dann nach 1250+500 = 1750ms
    // Das ist die Gesamtdauer für die Fixation (in der Frage einzustellen)
  }

  // Aufruf der Methode bei jeder Fixations-Pause
  %qst%_qst.addEventListener("fixation", showContent);
}

// Initialisieren der AssignmentPlus Instanz
SoSciTools.attachEvent(window, "load", function() {
    // Inhalte, welche bei den einzelnen Items gezeigt werden sollen
    // (auch hier können Platzhalter zum Einsatz kommen)
    new AssignmentPlus("%qst%", {
      i1 : ["ER", "2"],
      i2 : ["ER", "1"],
      i3 : ["SIE", "3"],
    });
});

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

Am Ende des JavaScript-Codes ist ein Array definiert, welche Inhalte bei den einzelnen Items angezeigt werden sollen. Hier sind exemplarisch nur die Inhalte für 3 Items angegeben. Nach Bedarf kann hier natürlich auch mit Platzhaltern gearbeitet werden, z.B. wenn eine Randomisierung oder Rotation erforderlich ist.

Zuletzt ist noch ein klein wenig PHP-Code erforderlich, um den Platzhalter ''%qst%'' mit der Kennung der Zuordnungsaufgabe ("ZA01") zu belegen. Hierfür sind unterschiedliche Varianten möglich -- der folgende PHP-Code bindet beide Elemente (die Frage und den HTML-/JavaScript-Code) ein und belegt den Platzhalter:

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

Der PHP-Code steht alleine auf einer Fragebogen-Seite. Die beiden Elemente dürfen nicht (!) zusätzlich dazu in die Seite gezogen werden.