Differences

This shows you the differences between two versions of the page.

--- countdowntimer [2022/09/07 09:10] – admin
+++ countdowntimer [2024/06/12 08:28] (current) – [Pausing the Timer] admin
@@ Line 1: / Line 1: @@
 ====== 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.
+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/XMcommunity/messages/add/TomG|TomG]] on the Qualtrics Community to learn more.
+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 ====
@@ Line 11: / Line 13: @@
 <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 ==
@@ Line 31: / Line 38: @@
 </code>
-To override the default options, specify the desired [[countdownTimer#options|options]] in a function argument as an object. For example:
+To override the default options, specify the desired **[[countdownTimer#options|options]]** in a function argument as an object. For example:
 <code>
 countdownTimer({timerSecsVar:"timerSecs1"});
@@ Line 51: / Line 58: @@
 </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.
+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:
-For example, to set the time limit to one hour:
 <code>
-timerSecs = 3600
+__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]].
+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 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:
+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() {
@@ Line 68: / Line 74: @@
 ==== 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:
+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 timerSecs Is Greater Than 0
+if __js_timerSecs Is Greater Than 0
 </code>
 === Response Requirements ===
@@ Line 85: / Line 91: @@
 Default: false
 ==== timerSecsVar ====
-**timerSecsVar** is the name of the embedded field that contains the [[countdowntimer#timer seconds|Timer Seconds]].
+**timerSecsVar** is the name of the embedded field that contains the **[[countdowntimer#timer seconds|Timer Seconds]]**.
-Default: "timerSecs"
+Default: %%"timerSecs"%%
 ==== timerSelector ====
 **timerSelector** is the css style selector for the time remaining display span.
-Default: "#timer"
+Default: %%"#timer"%%
 ==== updateSecs ====
 **updateSecs** specifies how often the timer should be updated and checked in seconds.
@@ Line 97: / Line 103: @@
 Default: 1
 ===== Pausing the Timer =====
-To pause a timer (have a timed section, pause, then start the timer where it left off), turn the timer off at the end of the first timed section, then when it is turned back on set the new Timer Seconds equal to the previous Timer Seconds.  For example:
+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:
@@ Line 105: / Line 119: @@
 Set Embedded Data:
   timerOn = 1
-  timerSecs2 = ${e://Field/timerSecs1}
+  __js_timerSecs2 = ${e://Field/__js_timerSecs1}
+  timerSecsVar = timerSecs2
 Block: Initialization Block
-Block: Timed section
+Block: Continue timed section
 </code>
 ====== Qualtrics Wiki ======
 [[start|Qualtrics Wiki]]