====== countdownTimer -  Set and display a time limit across pages and blocks ======
The **countdownTimer** function allows the setting of a time limit across pages and blocks. It displays the time remaining in the survey header. Once the time expires the remaining questions are skipped. The countdown timer can be turned on or off, allowing for timed and untimed survey sections and multiple timed sections in a survey. Configuration is done by setting values of embedded data fields in the survey flow. **countdownTimer** keeps accurate timing info even if the browser window is closed.

New updated version works with Simple AND non-Simple layouts!  

{{ ::countdowntimer.mp4?650 |countdownTimer Demo}}

This function is available for a reasonable fee. Contact **[[https://community.qualtrics.com/inbox/conversation?with=373|TomG]]** on the Qualtrics Community to learn more.
===== Set-up Instructions =====
==== Survey Header ====
=== Add Timer HTML ===
Add the timer display html to the survey header. Go to Look & Feel -> General -> Header edit -> {{::icon_source.jpg?20|}} and paste the following html:
<code>
<div id="timerDiv">Time Remaining: <span id="timer">0:00</span></div>
</code>
=== Add jQuery if using Simple Layout ===
If using Simple layout add jQuery to the header. While still editing the survey header in html mode, add:
<code>
<script src="https://cdn.jsdelivr.net/npm/jquery@3.7.1/dist/jquery.min.js"></script>
</code>
=== Add countdownTimer Function ==
Add the countdownTimer JS function to the header. While still editing the survey header in html mode, add the provided function below the timer html:
<code>
<script>
/*Paste countdownTimer function JS here*/
</script>
</code>
=== Run the countdownTimer Function ===
To run the countdown timer add the countdownTimer function call to the Qualtrics addOnload function. While still editing the survey header in html mode, add the addOnload function inside the script tag added above:
<code>
<script>
/*Paste countdownTimer function JS here*/

Qualtrics.SurveyEngine.addOnload(function() {
    countdownTimer();
});
</script>
</code>

To override the default options, specify the desired **[[countdownTimer#options|options]]** in a function argument as an object. For example:
<code>
countdownTimer({timerSecsVar:"timerSecs1"});
</code>
==== Custom CSS ====
Use CSS to style the timer display. Go to Look & Feel -> Style -> Custom CSS edit and paste the following CSS:
<code>
#timerDiv { /*style the timer display */
	display: none;
	text-align: right;
}
</code>
Styling can be changed or added to as needed. Do NOT remove display:none;
==== Survey Flow ====
=== Timer On/Off ===
Set the timer on/off embedded data field by setting the field to 1 (on) or 0 (off) at the appropriate places in the survey flow. For example, to turn the countdownTimer on:
<code>
timerOn = 1
</code>
=== Timer Seconds ===
Set the timer seconds embedded data field(s) by setting the field value in seconds at the appropriate places in the survey flow. Timer seconds is the amount of time allowed to complete a timed section of the survey. The timer secs embedded data field must be prefixed by "%%__js_%%" in the survey flow, display logic, and piping since it will be updated by the countdownTimer JS function. For example, to set the time limit to one hour:
<code>
__js_timerSecs = 3600
</code>
If multiple timers are used in a survey, each timer seconds embedded field should have a unique name (e.g., timerSecs1, timerSecs2, etc.). The default field name is timerSecs, but this can be overridden in the function **[[countdownTimer#options|options]]**.
=== Initialization Block ===
Add a question block immediately after setting **[[countdowntimer#timer on off|Timer On/Off]]** and **[[countdowntimer#timer seconds|Timer Seconds]]** embedded fields in the survey flow to initialize the countdown timer. The purpose of the initialization block is to make sure the timer is set so that if the browser window is closed the timer will be accurate when the respondent returns to the survey. The initialization block should contain a single Text/Graphic question with the following JavaScript:
<code>
Qualtrics.SurveyEngine.addOnReady(function() {
	var qobj = this;
	setTimeout(function() { qobj.clickNextButton(); },0);
});
</code>
The initialization question will flash by very quickly and in many cases barely be visible. The suggested question text is "Setting up countdown timer...". If a survey has multiple timed sections, the same block can be used at the start of each timed survey section.
==== Question Configuration ====
=== Display Logic ===
Add display logic based on the **[[countdowntimer#timer seconds|Timer Seconds]]** embedded data field to ALL questions in the timed section so they only display if there is time remaining.  For example:
<code>
if __js_timerSecs Is Greater Than 0
</code>
=== Response Requirements ===
Do NOT require response or add custom validation to any questions in the timed blocks. You may use request response. When using request response, once time expires the respondent will only be able to 'Continue without answering'.
===== Options =====
In general, the default options should work for the vast majority of implementations.
==== on ====
**on** is a binary value that turns the timer on or off: 1=on and 0=off.

Default: <nowiki>${e://Field/timerOn}</nowiki>
==== showRawSecs ====
**showRawSecs** is a boolean to show the time remaining in raw seconds instead of hh:mm:ss format

Default: false
==== timerSecsVar ====
**timerSecsVar** is the name of the embedded field that contains the **[[countdowntimer#timer seconds|Timer Seconds]]**. 

Default: %%"timerSecs"%%
==== timerSelector ====
**timerSelector** is the css style selector for the time remaining display span.

Default: %%"#timer"%%
==== updateSecs ====
**updateSecs** specifies how often the timer should be updated and checked in seconds.

Default: 1
===== Pausing the Timer =====
To pause a timer (have a timed section, pause, then start the timer where it left off), turn **[[countdowntimer#Timer On/Off|Timer On/Off]]** off at the end of the first timed section, then when it is turned back on set the new **[[countdowntimer#Timer Seconds|Timer Seconds]]** equal to the previous Timer Seconds.  For example if the function call is:
<code>
countdownTimer({timerSecsVar: "${e://Field/timerSecsVar}"});
</code>
Then the survey flow would be:
<code>
Set Embedded Data:
  timerOn = 0
  __js_timerSecs1 = 3600
  timerSecsVar = timerSecs1
Block: Timed section
Set Embedded Data:
  timerOn = 0
Block: Untimed section
Set Embedded Data:
  timerOn = 1
  __js_timerSecs2 = ${e://Field/__js_timerSecs1}
  timerSecsVar = timerSecs2
Block: Initialization Block
Block: Continue timed section 
</code>
====== Qualtrics Wiki ======
[[start|Qualtrics Wiki]]