Timer: Countdown across multiple pages

If your participants should complete a task within a given time, you can use a countdown. This chapter helps you create one.

Advice: If your countdown neither needs to be displayed nor does it count the time across multiple pages, you might rather look at this page: Timer: Go Onto Next Page Automatically

The following components are necessary for the countdown:

Start by defining how much time the participant gets. Save it in form of a unix-timestamp and make it accessible for the following pages by using registerVariable(). The isset() command makes sure the end of the countdown will not change in case the page gets reloaded.

// Save the timeout into the variable $timeout
if (!isset($timeout)) {
  $timeout = strtotime('+30 seconds');
  registerVariable($timeout);
}

Place this PHP-code once on the page the countdown starts.

When the time is up, the questionnaire should not display the page(s) inside the countdown area but jump to the next part of the questionnaire. You have to place the following php-code at the top of every (!) page that should be affected by the countdown. The page following the countdown needs to have the ID partNext.

// Filter: Is the time up?
if (time() > $timeout) {
  goToPage('partNext');
}

This code bit should be placed right at the top of the pages. Except for the first countdown page which needs the time definition code bit first (see above).

While the participant fills out the pages inside the countdown, you might want them to see the remaining time. Additionally, it is needet to check whether the time is up when the page is being loaded. This is realized by JavaScript.

Save the JavaScript code as text (Heading → Add text). For the content to be interpreted as JavaScript code, select “HTML code” as the representation.

<!-- HTML-element to display the remaining time -->
<div id="timeDisplay" style="font-size: 200%; margin: 16px 0; text-align: center">&ndash;</div>
 
<script type="text/javascript">
<!--
 
// Get the remaining time from the php code
var timeLeft = %timeLeft%;
var timeStart = new Date();
 
// Refresh the time display and check whether the time is up
function updateCountdown() {
  // calculate the remaining time
  var now = new Date();
  var timePage = Math.floor((now.getTime() - timeStart.getTime()) / 1000);  // Time passed in seconds
  var remain = timeLeft - timePage;
 
  // Is the time up?
  if (remain <= 0) {
    remain = 0;
    // Stop the timer
    window.clearInterval(timerInterval);
    // Display a message (optional)
    alert(„The time is up.“);
    // Redirect the participant to the next page (optional)
    SoSciTools.submitPage();
  }
 
  // Display the time
  var display = document.getElementById("timeDisplay");
  if (!display) {
    return;
  }
  while (display.lastChild) {
    display.removeChild(display.lastChild);
  }
  var minutes = Math.floor(remain / 60);
  var seconds = String(remain - 60 * minutes);
  if (seconds.length < 2) {
    seconds = "0" + seconds;
  }
  var displayText = String(minutes) + ":" + seconds;
  var displayNode = document.createTextNode(displayText);
  display.appendChild(displayNode);
}
 
// Initialize
var timerInterval = window.setInterval(updateCountdown, 250);
updateCountdown();
 
// -->
</script>

Tip: If you do not want to display a message after the countdown has expired or do not want to automatically forward the participant, simply remove the corresponding lines.

Tip: Also note the first two lines, which do not yet contain JavaScript, but simply HTML code. This HTML code or another HTML element with the HTML ID “timeDisplay” can in principle also be placed elsewhere in the HTML code (e.g. in a question). In this case, place the above PHP code, which embeds the JavaScript code, at the bottom of the page. Otherwise, where you want the countdown to be displayed.

To integrate the JavaScript code, a little PHP code is again required on the questionnaire page. The following PHP code passes the remaining time as placeholder %timeLeft%.

// JavaScript to display remaining time
$timeLeft = $timeout - time();
// Instead of JS01 the identifier of the text must be entered here
show('JS01', array(
  '%timeLeft%' => $timeLeft
));

This code is also needed on every page where the countdown should be displayed.

Note: For show() to work correctly, please do not save the JavaScript code as Text Element but as Text in a section in the List of Questions. Please select “HTML code” as the display mode for the text.