implements #191

docs/markdown_docs/plugins/jspsych-xab.md

@@ -9,13 +9,14 @@ This table lists the parameters associated with this plugin. Parameters with a d
 Parameter | Type | Default Value | Description
 ----------|------|---------------|------------
 stimuli | array | *undefined* | Array of arrays. Each interior array represents the stimuli for a single trial. Each interior array can be two or three elements. If it is two elements, then the plugin will show the first element as X and as the target during the A/B portion (the second element will be the foil). If it is three elements, then the first is X the second is the target (A) and the third is the foil (B). This is useful if X and A are not identical, but A is still the correct choice (e.g. a categorization experiment where the goal is to pick the item that is in the same category). Stimuli can be paths to images, or html strings.
-is_html | boolean | false | If the elements of the `stimuli` array are strings containing HTML content, then this parameter must be set to true. 
+is_html | boolean | false | If the elements of the `stimuli` array are strings containing HTML content, then this parameter must be set to true.
 left_key | numeric or string | 'Q' | Which key the subject should press to indicate that the target is on the left side.
 right_key | numeric or string | 'P' | Which key the subject should press to indicate that the target is on the right side.
 prompt | string | "" | This string can contain HTML markup. Any content here will be displayed below the stimulus. The intention is that it can be used to provide a reminder about the action the subject is supposed to take (e.g. which key to press).
-timing_x | numeric | 1000 | How long to show the X stimulus for in milliseconds. 
+timing_x | numeric | 1000 | How long to show the X stimulus for in milliseconds.
 timing_xab_gap | numeric | 1000 | How long to show a blank screen in between X and AB in milliseconds.
 timing_ab | numeric | -1 | How long to show A and B in milliseconds. If the value of this parameter is -1, then the stimuli will remain on the screen until a response is given.
+timing_response | numeric | -1 | The maximum duration to wait for a response, measured from the onset of the AB portion of the trial. If -1, then the trial will wait indefinitely for a response.
 
 ## Data Generated
 
@@ -27,7 +28,7 @@ stimulus_x | string | Either the path to the image file or the string containing
 stimulus_a | string | Either the path to the image file or the string containing the HTML formatted content that was the A stimulus on this trial.
 stimulus_b | string | Either the path to the image file or the string containing the HTML formatted content that was the B stimulus on this trial.
 key_press | numeric | Indicates which key the subject pressed. The value is the [numeric key code](http://www.cambiaresearch.com/articles/15/javascript-char-codes-key-codes) corresponding to the subject's response.
-rt | numeric | The response time in milliseconds for the subject to make a response. The time is measured from when the A and B stimuli first appear on the screen until the subject's response. 
+rt | numeric | The response time in milliseconds for the subject to make a response. The time is measured from when the A and B stimuli first appear on the screen until the subject's response.
 correct | boolean | True if the subject picks the correct answer.
 
 ## Examples
@@ -50,4 +51,4 @@ var block = {
 	stimuli: [['img/happy_joe_face.png', 'img/sad_joe_face.png', 'img/sad_fred_face.png']],
 	prompt: "Press Q if the person you just saw is on the left. Press P if the person you just saw is on the right."
 }
-```
+```

plugins/jspsych-xab.js

@@ -30,6 +30,7 @@
         trials[i].timing_x = params.timing_x || 1000; // defaults to 1000msec.
         trials[i].timing_xab_gap = params.timing_xab_gap || 1000; // defaults to 1000msec.
         trials[i].timing_ab = params.timing_ab || -1; // defaults to -1, meaning infinite time on AB. If a positive number is used, then AB will only be displayed for that length.
+        trials[i].timing_response = params.timing_response || -1; //
         // optional parameters
         trials[i].is_html = (typeof params.is_html === 'undefined') ? false : params.is_html;
         trials[i].prompt = (typeof params.prompt === 'undefined') ? "" : params.prompt;
@@ -134,14 +135,17 @@
           }, trial.timing_ab));
         }
 
+        // if timing_response > 0, then we end the trial after timing_response milliseconds
+        if (trial.timing_response > 0) {
+    			var t2 = setTimeout(function() {
+    				end_trial({rt: -1, correct: false, key: -1});
+    			}, trial.timing_response);
+    			setTimeoutHandlers.push(t2);
+    		}
+
         // create the function that triggers when a key is pressed.
         var after_response = function(info) {
 
-          // kill any remaining setTimeout handlers
-          for (var i = 0; i < setTimeoutHandlers.length; i++) {
-            clearTimeout(setTimeoutHandlers[i]);
-          }
-
           var correct = false; // true when the correct response is chosen
 
           if (info.key == trial.left_key) // 'q' key by default
@@ -156,11 +160,24 @@
             }
           }
 
+          info.correct = correct;
+
+          end_trial(info);
+
+        };
+
+        var end_trial = function(info) {
+          // kill any remaining setTimeout handlers
+          for (var i = 0; i < setTimeoutHandlers.length; i++) {
+            clearTimeout(setTimeoutHandlers[i]);
+          }
+
+          jsPsych.pluginAPI.cancelKeyboardResponse(keyboardListener);
 
           // create object to store data from trial
           var trial_data = {
             "rt": info.rt,
-            "correct": correct,
+            "correct": info.correct,
             "stimulus": JSON.stringify([trial.x_path, trial.a_path, trial.b_path]),
             "key_press": info.key
           };
@@ -168,14 +185,11 @@
 
           display_element.html(''); // remove all
 
-          xab_trial_complete = true;
-
           // move on to the next trial after timing_post_trial milliseconds
           jsPsych.finishTrial();
+        }
 
-        };
-
-        jsPsych.pluginAPI.getKeyboardResponse({
+        var keyboardListener = jsPsych.pluginAPI.getKeyboardResponse({
           callback_function: after_response,
           valid_responses: [trial.left_key, trial.right_key],
           rt_method: 'date',

tests&examples/jspsych-xab.html

@@ -14,16 +14,24 @@
   </body>
   <script>
 
-  var block = {
+  var block_1 = {
     type: 'xab',
     stimuli: [['img/happy_face_1.jpg', 'img/happy_face_2.jpg']],
-    prompt: "<p class='center-content'>Press Q if the face you just saw is on the left. Press P if the face you just saw is on the right.</p>"
+    prompt: "<p class='center-content'>Press Q if the face you just saw is on the left. Press P if the face you just saw is on the right.</p>",
+    timing_response: 2000
+  }
+
+  var block_2 = {
+    type: 'xab',
+    stimuli: [['img/happy_face_1.jpg', 'img/happy_face_2.jpg']],
+    prompt: "<p class='center-content'>Press Q if the face you just saw is on the left. Press P if the face you just saw is on the right.</p>",
+    timing_response: -1
   }
 
   function start(){
     jsPsych.init({
       display_element: $('#jspsych-target'),
-      experiment_structure: [block]
+      experiment_structure: [block_1, block_2]
     });
   }