====== LatencyTimer ======

Die JavaScript-Klasse LatencyTimer ist darauf ausgelegt, Sie bei der Messung von Reaktionszeiten im Fragebogen zu unterstützen.

**Tipp:** Sehen Sie sich vorher einmal die Fragetypen [[:de:create:questions:selclick]] und [[:de:create:questions:assignment]] an. Diese zeichnen die Reaktionszeit (Antwortzeit, response time) automatisch auf.

Die Messung von Reaktionszeiten basiert auf [[:de:create:javascript]], also Programmcode, welcher im Browser der Befragten läuft. Dieser Programmcode kann auf Eingaben der Befragten reagieren, zum Beispiel auf Mausklicks oder Tastaturanschläge. Diese lösen sogenannte JavaScript-Events aus.

Das Ziel der Klasse //LatencyTimer// ist es nun, die Differenz zwischen solchen Ereignissen zu messen. Sie können bei der Messung von Reaktionszeiten mittels JavaScript mit einer Genauigkeit <100 ms rechnen. Für die Differenz aus zwei Ereignissen entsprechend mit einer Genauigkeit <200 ms.

===== Vorbereitung ====

Machen Sie die Bibliothek auf der entsprechenden Seite im Fragebogen mittels ''[[:de:create:functions:library]]'' verfügbar.

<code php>
library('LatencyTimer');
</code>

Weiterhin benötigen Sie [[:de:create:questions:internal]] auf der Fragebogen-Seite. Und zwar so viele, wie Sie unterschiedliche Reaktionszeiten messen möchten. Ziehen Sie die entsprechende Frage vom Typ "interne Variablen" auf die Fragebogen-Seite.


===== Referenz =====

==== Timer-Instanz ====

Folgende Methoden stehen für eine Instanz der Klasse //LatencyTimer// zur Verfügung. Einige Parameter werden hier immer wieder verwendet:

  * //storage//\\ Eine interne Variable, spezifiziert durch ihre Kennung (z.B. ''"IV01_01"''), durch das HTML-Element oder durch das zur internen Variable gehörige ''SoSciTools.QuestionItem''.
  * //storeFirst//\\ Legt fest, ob die Reaktionszeit auch dann aufgezeichet werden soll, wenn es sich um den ersten Klick auf der Seite handelt. Standardmäig wird für den ersten Klick auf der Seite anstatt einer Reaktionszeit der Code ''-7'' gespeichert.
  * //multiStore//\\ Mit dieser Variable wird eine weitere interne Variable festgelegt, welche die Reaktionszeit für weitere Klicks auf das Element zählt. Wird sie verwendet, dann werden die einzelnen Reaktionszeiten addiert und in dieser Variable gespeichert. Standardmäßig wird die Reaktionszeit nur für den ersten Klick auf ein Element gezählt. Weitere Klicks ändern den Wert entweder nicht (wenn die Antwort unverändert bleibt) oder führen zur Speicherung des Codes ''-6'', wenn auf ein anderes Auswahlelement innerhalb des Items oder der Frage geklickt wird (z.B. eine andere Auswahloption einer Auswahlfrage).

''void **latencyTimer.registerElement**(Element //element//, mixed //storage//, boolean //storeFirst//)''

Mit ''registerElement()'' wird die Reaktionszeit zum Klick auf ein HTML-Element ''//element//'' aufgezeichnet.

''void **latencyTimer.registerItem**(SoSciTools.QuestionItem|Question //item//, mixed //storage//, boolean //storeFirst//, mixed //multiStore//)''

Mit ''registerItem()'' wird die Reaktionszeit zur Antwort auf eine (Auswahl-)Frage oder ein Item in einer Fragebatterie aufgezeichnet.

''void **latencyTimer.registerRadio**(String //prefix//, mixed //storage//, boolean //storeFirst//)''

Mit ''registerRadio()'' wird die Reaktionszeit zum Klick auf Radio-Buttons ausgezeichnet, welche das angegeben Präfix und eine fortlaufende Nummer verwenden. Das Präfix ''"SK01_01"'' würde z.B. die Auswahlfelder ''"SK01_011"'', ''"SK01_012"'' u.s.w. überwachen. Meist ist die Verwendung von ''latencyTimer.registerItem()'' einfacher.

''void **latencyTimer.registerSelection**(String //auswahlID//, mixed //storage//, boolean //storeFirst//)''

Mit ''registerSelection()'' wird die Reaktionszeit zum Klick auf eine einfache Auswahlfrage mit der Kennung ''//auswahlID//'' aufgezeichnet. Meist ist die Verwendung von ''latencyTimer.registerItem()'' einfacher.

''void **latencyTimer.registerSlider**(String //sliderID//, mixed //storage//, boolean //storeFirst//, mixed //multiStore//)''

Mit ''registerSlider()'' wird die Reaktionszeit zur Auswahl eines Wertes auf einem Schieberegler aufgezeichnet. Da der Wert auf einem Schieberegler womöglich noch einmal geändert wird, muss in ''//multiStore//'' festgelegt werden, wo weitere Änderungen des Wertes gespeichert werden sollen.

''Function **latencyTimer.eventHandler**(mixed //storage//, boolean //storeFirst//, mixed //multiStore//)''

Die Methode ''eventHandler()'' liefert eine Funktion, welche direkt in ''Element.addEventListener()'' verwendet werden kann. So können auch Reaktionszeiten für Ereignisse gespeichert werden, die keine Klicks sind.


==== Statische Methoden ====

Folgende Methoden stehen unabhängig von der Instanz zur Verfügung.

''Element **LatencyTimer.getInternal**(string //FrageKennung//, int //VariablenNummer//)''

Mittels ''getInternal()'' kann eine interne Variable angesprochen werden.

Allgemein ist die Verwendung von ''s2.//FrageKennung//.item(//VariablenNummer//)'' allerdings einfacher.


===== Anwendung =====

Die Bibliothek //LatencyTimer// basiert darauf, dass Sie Paare bilden, und zwar aus (1) Items, Fragen oder Auswahlfeldern und (2) internen Variablen. Wann immer auf ein Items etc. geklickt wird, speichert der //LatencyTimer// dann die Zeit (in Millisekunden), welche seit dem letzten Klick auf ein anderes Element vergangen ist. Der Knackpunkt dabei ist, dass Sie als Referenz einen vorhergehenden Klick benötigen.

**Hinweis:** Optional können Sie zulassen, dass auch die Zeit seit dem Laden der Seite als Referenz verwendet wird. Allerdings beinhaltet Ihre erste Messung dann das Lesen der Frage u.s.w., ist also deutlich verzerrt gegenüber den weiteren Messungen.

Die eigentlich Verwendung besteht nun darin, mittels ''new LatencyTimer()'' eine Instanz des //LatencyTimer// zu erstellen und dann Paare aus Eingabeoption und interner Variable zu definieren. Die dafür verfügbaren Funktionen sind unten aufgeführt. Für eine Skala "SK01" mit 10 Items, und Speicherung der Reaktionszeiten in die 10 Variablen der internen Variablen Frage "IV01" könnte der Code wie folgt aussehen:

<code html>
<script type="text/javascript">
window.addEventListener("load", function() {
    var timer = new LatencyTimer();
    for (var i=1; i<=10; i++) {
        var item = s2.SK01.item(i);
        var internal = s2.IV01.item(i);
        timer.registerItem(item, internal);
    }
}
</script>
</code>

Durch ''%%window.addEventListener("load", ...)%%'' wird dieser Code erst ausgeführt, wenn die Seite vollständig geladen ist. Zu diesem Zeitpunkt können die Skala über ''s2.SK01'' und die internen Variablen ''s2.IV01'' angesprochen werden.

In diesem Beispiel wird die Methode ''LatencyTimer.registerItem()'' verwendet, welche die interne Repräsentation der Items in SoSci Survey nutzt ([[:de:create:soscitools]]). Dadurch muss man die Auswahlfelder der Skala nicht einzeln zusammensuchen.

Anstatt in der FOR-Schleife zu zählen, kann man die Items auch direkt aus dem Objekt abfragen, welches die Skala repäsentiert.

<code javascript>
window.addEventListener("load", function() {
    var timer = new LatencyTimer();
    for (var i=1; i<=s2.SK01.length; i++) {
        var item = s2.SK01.item(i);
        var internal = s2.IV01.item(i);
        timer.registerItem(item, internal, true);
    }
});
</code>



===== Auswahlfragen =====

In diesem Beispiel sollen die Klicks auf drei Auswahlfragen (einfache Auswahl) "AF01", "AF02" und "AF03" gespeichert werden.

<code javascript>
window.addEventListener("load", function() {
    var timer = new LatencyTimer();
    timer.registerItem(s2.AF01, "IV01_01");
    timer.registerItem(s2.AF02, "IV01_02");
    timer.registerItem(s2.AF03, "IV01_03");
}
</code>

Hier werden die internen Variablen über ihre Kennung angesprochen -- natürlich wäre ''s2.IV01.item(1)'' ebenso möglich.

Falls die Reaktionszeit auch aufgezeichnet werden soll, wenn die Befragten ihre Meinung ändern, sind zwei interne Variablen pro Auswahlfrage erforderlich.

<code javascript>
window.addEventListener("load", function() {
    var timer = new LatencyTimer();
    timer.registerItem(s2.AF01, "IV01_01", false, "IV01_02");
    timer.registerItem(s2.AF02, "IV01_03", false, "IV01_04");
    timer.registerItem(s2.AF03, "IV01_05", false, "IV01_06");
}
</code>

In der ersten Variable wird die Reaktionszeit für den ersten Klick gespeichert. In der zweiten Variable wird die gesamte Reaktionszeit (inkl. jener für den ersten Klick) gespeichert.


===== Sonstige Ereignisse aufzeichnen =====

Die Methode ''eventHandler()'' erlaubt das Speichern von Reaktionszeiten für beliebige Ereignisse.

<code html>
<div id="button01" style="width: 50px; height: 20px; border: 1px solid red; display: inline-block"></div>
<div id="button02" style="width: 50px; height: 20px; border: 1px solid blue; display: inline-block"></div>

<script type="text/javascript">
window.addEventListener("load", function() {
    var timer = new LatencyTimer();
    document.getElementById("button01").addEventListener("click", timer.eventHandler("IV01_01"));
    document.getElementById("button02").addEventListener("click", timer.eventHandler("IV01_02"));
});
</script>
</code>

Die Methode ''eventHandler()'' kann etwa auch genutzt werden, um von einem offenen Texteingabefeld (im Beispiel "OT01_01") die Reaktionszeiten bis zum ersten und bis zum letzten Tastenanschlag aufzuzeichnen.

<code javascript>
window.addEventListener("load", function() {
    var timer = new LatencyTimer();
    document.getElementById("OT01_01").addEventListener(
        "keydown",
        timer.eventHandler("IV01_01", false, "IV01_02")
    );
});
</code>

Möchte man diese Aufzeichnung für eine größere Anzahl Eingabefelder realisieren, bietet es sich an, zwei Fragen vom Typ "interne Variablen" anzulegen, eine (im Beispiel "IV01") für den ersten, eine für den letzten Tastenanschlag ("IV02").

<code javascript>
window.addEventListener("load", function() {
    var timer = new LatencyTimer();
    for (var i=1; i<=s2.OT01.length; i++) {
        var item = s2.OT01.item(i);
        var internalA = s2.IV01.item(i);
        var internalB = s2.IV02.item(i);
        item.input.addEventListener(
            "keydown",
            timer.eventHandler(internalA, false, internalB)
        );
    }
});
</code>

Das Abschicken der aktuellen Seite im Fragebogen kann zum Beispiel über das ''submit''-Event des Formulars erfasst werden. In Verbindung mit ''latencyTimer.eventHandler()'' erfasst folgendes Script die Zeit vom (vollständigen) Laden der Seite bis zum Abschicken, und speichert diese Zeit in die interne Variable "IV01_01" (diese muss natürlich auf die Fragebogen-Seite gezogen werden).

<code javascript>
window.addEventListener("load", function() {
    var timer = new LatencyTimer();
    var qnrForm = document.getElementById("questionnaireForm");
    qnrForm.addEventListener("submit", timer.eventHandler("IV01_01", true));
});
</code>