====== Timer: Go Onto Next Page Automatically ======

This chapter describes how to limit the dwell time on a page -- or how to define exactly when the "next" button should be hidden in parallel to this. After the given amount of time has expired, the participant will be forwarded automatically onto the next page. 

The solution is based on [[:en:glossary#javascript|JavaScript]]. In the (rare) event that the participant has specifically disabled JavaScript, the timer will not start. In this instance, the amount of time spent working through the page can be checked post-hoc with the dwell time ([[:en:results:variables#dwell_times|Additional Variables in the Data Set: Dwell Times]]).




===== Function =====

  - The first time the questionnaire page was visited is saved in a PHP variable. This means the timer cannot go onto the next page by the page being reloaded or when the Back button is used.
  - If necessary, the Next button (if applicable, the Back button as well) can be hidden.
  - A timer then starts that calls up the function to forward onto the next page after a certain amount of time.
  - After the timer has expired, the current questionnaire page will be submitted automatically. The function is comparable (but not identical) with pressing the "next" button. 

**Note:** The participant cannot restart the timer by reloading the questionnaire page ("Reload", "Refresh", F5 button). If you want to test this, do __not__ start the questionnaire from the page with the timer, otherwise a new interview will begin every time the page is reloaded . Simply start the questionnaire on the page before -- or on the first page as normal. 

**Tip:** If your questionnaire offers a "Back" button (**Compose Questionnaire** -> //Settings//), it could make sense to hide the button on the page __after__ the timer (see PHP function ''[[:en:create:functions:option#buttons_in_the_questionnaire|option()]]'').


===== Implementation =====

Start by generating the time the questionnaire page was first visited with the help of the PHP function ''time()''. Filtering with ''isset()'' ensures that this time is only saved the first time the page is called up.

<code php>
if (!isset($time0)) {
  $time0 = time();
  registerVariable('$time0');  // store variable $time0 after the end of the PHP code as well 
}
// Check if time has already expired
// (e.g. because the participant reloaded the page)
$timer = 60;  // participant has 1 minute (60 seconds) to work through the page
if (time() >= $time0 + $timer) {
  goToPage('next');
}
// JavaScript code has to be told the time remaining
$remain = $time0 + $timer - time();
replace('%remain%', $remain);
</code>

**Note:** If you want to use multiple, independent timers in the questionnaire, the variable ''$time0'' in the PHP code has to be called something different each time. The name of the variable also has to be changed in the ''registerVariable()'' command -- therefore, a total of 5 times. 

**Different language versions:** Use the translation support tool and copy-paste the suppression of the "next" button into the different language versions.

If the participant is able to restart the timer by reloading the page or using the "Back" button, you can reduce the PHP code to one line (not recommended). However, this variant will not work if you want to let the timer to run over several pages. 

<code php>
replace('%remain%', 60);  // participant has 1 minute (60 seconds) to work through the page
</code>

For the actual timer, create a new text module in the **Question catalog** in a section with **New text** __or__ under **Text modules and labeling**.

For the //Display//, please set "HTML code". Then insert the following content.

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

// Function to forward
function goNext() {
  // Display message (optional)
  alert("Time's up.");
  // Forward participant onto the next page
  SoSciTools.submitPage();
}
 
// Hide next button (optional)
SoSciTools.submitButtonsHide();

// Initialization of forwarding
SoSciTools.attachEvent(window, "load", function(evt) {
  
  // Start timer to forward automatically
  window.setTimeout(goNext, %remain% * 1000);
});
// -->
</script>
</code>

Some of the JavaScript sections are marked as //optional//. These sections can be removed where necessary.

After saving, drag this text module directly below the PHP code onto the questionnaire page.

**Note:** If you want to display a message after the timer has expired using ''alert()'', the time taken to close the message will appear in the dwell time in the data record. The dwell time that is saved is therefore higher than the timer actually for the participant to be on the page.


Initialization of the forwarding will only be carried out once the questionnaire page has been fully loaded (''onload''). There are two reasons for this: first of all, the loading time is considered in the actual dwell time, and the reason being that the "next" button can only be hidden once the page has been fully loaded.


**Note:** Please remember to drag the text element with the JavaScript onto the questionnaire page -- and do so below the PHP code.

Now insert text elements and/or questions to be shown in the questionnaire underneath the PHP and JavaScript codes. Positioning them below the PHP code is important to ensure the filter works properly if time has already expired.

**Multilingual versions:** If you use different languages for the questionnaire, use the translation help tool (under language versions) and copy the code for the timer into the different language versions.

===== Display Countdown =====

You can show the participant how much time they have left to work through the page. Insert the following HTML code onto the questionnaire page to do so (either in a text element, directly in a question or in a HTML code element). 


<code html>
<p>Remaining time: <span id="remain"></span></p>
</code>

Expanding the JavaScript code a little also has to be done in addition to this.

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

// Function to forward
function goNext() {
  // Display message (optional)
  alert("Time's up.");
  // Forward participant onto the next page
  SoSciTools.submitPage();
}

// Display countdown
var date0 = new Date();
var timeout = date0.getTime() + %remain% * 1000;
function updateCountdown() {
  // Calculate time
  var date = new Date();
  var time = Math.ceil((timeout - date.getTime() - 50) / 1000);  // remaining time in seconds
  // Display time
  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);
}

// Hide Next button (optional)
  SoSciTools.submitButtonsHide();
  
// Initialize forwarding
SoSciTools.attachEvent(window, "load", function(evt) {
  
  // Additional timer to update the countdown
  window.setInterval(updateCountdown, 1000);
  updateCountdown();
  // Start timer to forward automatically
  window.setTimeout(goNext, %remain% * 1000);
});

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


===== Timer Across Several Pages =====

The above code -- it does not matter whether it has a visible countdown or not -- is also suitable for letting a timer run across several pages in the questionnaire. The "next" button, however, must not be hidden. Where required, remove the following lines from the JavaScript:

  // Hide Next button (optional)
  SoSciTools.submitButtonsHide();

You can omit the ''isset()'' part from the PHP code on the following pages, although this does not interfere with anything.

<code php>
// Check whether time has already expired
$timer = 60;  // participant has 1 minute (60 seconds) to work through the page
if (time() >= $time0 + $timer) {
  goToPage('next');
}
// The JavaScript code has to be told the time remaining
$remain = $time0 + $timer - time();
replace('%remain%', $remain);
</code>

Place the text element with the JavaScript on the second page below the PHP code, and the questions beneath this.

**Restriction:** Loading times occured between questionnaire pages are deducted from the participant's dwell time. Conversely, the participant gets given a maximum of one second due to rounding errors.