====== Timer: Automatisch weiter zur nächsten Seite ======

Dieses Kapitel beschreibt, wie man die Bearbeitungszeit (Anzeigedauer) für eine Seite begrenzen kann -- oder exakt festlegen, wenn man parallel dazu den Weiter-Knopf ausblendet. Nach Ablauf der vorgegeben Zeit wird der Teilnehmer automatisch auf die nächste Seite weitergeleitet.

Die Lösung basiert auf [[:de:glossary#javascript|JavaScript]]. In dem (seltenen) Fall, dass der Teilnehmer JavaScipt gezielt deaktiviert hat, startet der Timer gar nicht erst. Die Bearbeitungszeit kann in diesem Fall zumindest post-hoc anhand der Bearbeitungszeit kontrolliert werden ([[:de:results:variables#antwortzeiten|Zusätzliche Variablen in der Datenausgabe: Antwortzeiten]]).


===== Funktion =====

  - Zunächst wird in einer PHP-Variable gespeichert, wann die Fragebogenseite erstmals aufgerufen wurde. So lässt sich der Timer nicht einfach durch Neu-Laden der Seite oder durch Verwendung des Zurück-Knopfes auf der nächsten Seite umgehen.
  - Je nach Bedarf wird der Weiter-Knopf (ggf. sofern vorhanden auch der Zurück-Knopf) ausgeblendet.
  - Dann wird ein Timer gestartet, der nach einer vorgegebenen Zeit die Funktion zur Weiterleitung aufruft.
  - Nach Ablauf des Timers wird die aktuelle Fragebogen-Seite automatisch abgeschickt. Die Funktion ist vergleichbar (allerdings nicht identisch) mit dem Drücken des "Weiter"-Knopfes.

**Hinweis:** Der Teilnehmer kann den Timer nicht neu starten, indem er die Fragebogenseite neu lädt ("Neu Laden", "Aktualisieren", Taste F5). Wenn Sie das testen möchten, starten Sie den Fragebogen __nicht__ ab der Seite mit dem Timer, sonst wird bei jedem Neu-Laden ein neues Interview begonnen. Starten Sie den Fragebogen einfach eine Seite vorher -- oder ganz regulär auf der ersten Seite.

**Tipp:** Falls Ihr Fragebogen einen "Zurück"-Knopf anbietet (**Fragebogen zusammenstellen** -> //Einstellungen//), könnte es sinnvoll sein, diesen auf der Seite __nach__ dem Timer auszublenden (s. PHP-Funktion ''[[:de:create:functions:option#knoepfe_im_fragebogen|option()]]'').


===== Umsetzung =====

Zunächst wird mithilfe der PHP-Funktion ''time()'' ermittelt, wann die Fragebogen-Seite erstmals aufgerufen wurde. Der Filter mit ''isset()'' stellt sicher, dass diese Zeit wirklich nur beim ersten Aufruf gespeichert wird.

<code php>
if (!isset($time0)) {
  $time0 = time();
  registerVariable($time0);  // Die Variable $time0 auch nach Ende des PHP-Codes aufbewahren
}
// Prüfung, ob die Zeit schon abgelaufen ist
// (z.B. weil der Teilnehmer die Seite neu geladen hat)
$timer = 60;  // Der Teilnehmer hat 1 Minute (60 Sekunden) Zeit zur Bearbeitung
if (time() >= $time0 + $timer) {
  goToPage('next');
}
// Die verbleibende Zeit muss auch dem JavaScript-Code bekannt gemacht werden
$remain = $time0 + $timer - time();
replace('%remain%', $remain);
</code>

**Wichtig:** Falls Sie im Fragebogen mehrere, voneinander unabhängige Timer einsetzen möchten, müssen Sie die Variable ''$time0'' im PHP-Code jedes Mal anders benennen. Der Name der Variable muss auch im Befehl ''registerVariable()'' ausgetauscht werden -- insgesamt also 5 Mal.

Falls der Teilnehmer den Timer durch Neu-Laden oder Verwendung des "Zurück"-Knopfes neu starten darf, können Sie den PHP-Code auf eine Zeile reduzieren (nicht empfohlen). Diese Variante funktioniert allerdings nicht, wenn Sie den Timer über mehrere Seiten laufen lassen möchten.

<code php>
replace('%remain%', 60);  // Der Teilnehmer hat 60 Sekunden für die Bearbeitung
</code>

Für den eigentlichen Timer legen Sie im **Fragenkatalog** in einer Rubrik mit **Neuer Text** __oder__ unter **Textbausteine u. Beschriftung** einen neuen Textbaustein an.

Für die //Darstellung// legen Sie bitte "HTML-Code" fest. Fügen Sie anschließend folgenden Inhalt ein.

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

// Funktion zur Weiterleitung
function weiter() {
  // Eine Meldung anzeigen (optional)
  alert("Die Zeit ist vorbei.");
  // Den Teilnehmer zur nächsten Seite weiterleiten
  SoSciTools.submitPage();
}

// Weiter-Knopf ausblenden (optional)
SoSciTools.submitButtonsHide();

// Initialisierung der Weiterleitung
SoSciTools.attachEvent(window, "load", function(evt) {
  // Timer für automatische Weiterleitung starten
  window.setTimeout(weiter, %remain% * 1000);
});

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

Einige Abschnitte im JavaScript sind als //optional// markiert. Diese Abschnitte kann man bei Bedarf einfach entfernen.

Nach dem Speichern ziehen Sie diesen Textbaustein direkt unter den PHP-Code auf die Fragebogen-Seite.

**Hinweis:** Wenn Sie nach Ablauf des Timers mittels ''alert()'' einen Hinweis anzeigen, so wird die Zeit bis zum Wegklicken des Hinweise in der Bearbeitungszeit im Datensatz auftauchen. Die gespeicherte Bearbeitungszeit liegt dann höher als der Timer tatsächlich für die Bearbeitung erlaubt.

Die Initialisierung der Weiterleitung wird erst durchgeführt, wenn die Fragebogen-Seite vollständig geladen wurde (''onload''). Das hat zwei Gründe: Zum einen wird die Ladezeit in der tatsächlichen Bearbeitungszeit berücksichtigt, zum anderen kann der Weiter-Knopf erst ausgeblendet werden, wenn die Seite vollständig geladen wurde.

**Hinweis:** Denken Sie daran, den Textbaustein mit dem JavaScript in die Fragebogenseite zu ziehen -- und zwar unter dem PHP-Code.

Unter dem PHP- und JavaScript-Code fügen Sie nun die Textbausteine und/oder Fragen ein, welche die Fragebogenseite zeigen soll. Die Platzierung unter dem PHP-Code ist wichtig, damit der Filter korrekt funktioniert, sollte die Zeit bereits abgelaufen sein.

**Mehrsprachige Versionen:** Sollten Sie verschiedene Sprachen für den Fragebogen verwenden, benutzen Sie das Übersetzungshilfe Tool (unter Sprachversionen) und kopieren Sie den Code für den Timer in die unterschiedlichen Sprachversionen.
===== Countdown anzeigen =====

Sie können dem Teilnehmer anzeigen, wie viel Zeit ihm noch zur Bearbeitung bleibt. Fügen Sie dafür auf der Fragebogen-Seite zunächst folgenden HTML-Code ein (entweder in einem Textbaustein, direkt in einer Frage oder via HTML-Code Element).

<code html>
<p>Verbleibende Zeit: <span id="remain"></span></p>
</code>

Zusätzlich müssen Sie den JavaScript-Code noch ein wenig ergänzen.

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

// Funktion zur Weiterleitung
function weiter() {
  // Eine Meldung anzeigen (optional)
  alert("Die Zeit ist vorbei.");
  // Den Teilnehmer zur nächsten Seite weiterleiten
  SoSciTools.submitPage();
}

// Countdown anzeigen
var date0 = new Date();
var timeout = date0.getTime() + %remain% * 1000;
function updateCountdown() {
  // Zeit berechnen
  var date = new Date();
  var time = Math.ceil((timeout - date.getTime() - 50) / 1000);  // Verbleibende Zeit in Sekunden
  // Zeit anzeigen
  var out = document.getElementById("remain");
  if (!out) {
    return;
  }
  while (out.lastChild) {
    out.removeChild(out.lastChild);
  }
  var minutes = Math.floor(time / 60);
  var seconds = String(time - 60 * minutes);
  if (seconds.length < 2) seconds = "0" + seconds;
  var display = String(minutes) + ":" + seconds;
  var displayNode = document.createTextNode(display);
  out.appendChild(displayNode);
}

// Weiter-Knopf ausblenden (optional)
SoSciTools.submitButtonsHide();

// Initialisierung der Weiterleitung
SoSciTools.attachEvent(window, "load", function(evt) {
  // Zusätzlicher Timer für die Aktualisierung des Countdowns
  window.setInterval(updateCountdown, 1000);
  updateCountdown();
  // Timer für automatische Weiterleitung starten
  window.setTimeout(weiter, %remain% * 1000);
});

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


===== Timer über mehrere Seiten =====

Der obige Code -- egal ob mit oder ohne sichtbarem Countdown -- ist auch dafür geeignet, einen Timer über mehrere Seiten des Fragebogens laufen zu lassen. Sie dürfen nur nicht den "Weiter"-Knopf ausblenden. Entfernen Sie also ggf. folgende Zeilen aus dem JavaScript:

  // Weiter-Knopf ausblenden (optional)
  SoSciTools.submitButtonsHide();

Den ''isset()''-Teil im PHP-Code können Sie auf den Folgeseiten weglassen, aber er stört auch nicht.

<code php>
// Prüfung, ob die Zeit schon abgelaufen ist
$timer = 60;  // Der Teilnehmer hat 1 Minute (60 Sekunden) Zeit zur Bearbeitung
if (time() >= $time0 + $timer) {
  goToPage('next');
}
// Die verbleibende Zeit muss auch dem JavaScript-Code bekannt gemacht werden
$remain = $time0 + $timer - time();
replace('%remain%', $remain);
</code>

Unter dem PHP-Code platzieren Sie auch auf der zweiten Seite den Textbaustein mit dem JavaScript und darunter die Fragen.

**Einschränkung:** Ladezeiten, die zwischen den Fragebogen-Seiten auftreten, werden dem Teilnehmer von der Bearbeitungszeit abgezogen. Umgekehrt bekommt der Teilnehmer durch Rundungsfehler maximal eine Sekunde zusätzlich geschenkt.