add instructions plugin

css/jspsych.css

@@ -75,10 +75,11 @@ input[type="text"] {
 }
 
 button {
-    padding: 0.5em;
+    padding: 0.8em;
     background-color: #eaeaea;
     border: 1px solid #eaeaea;
-    color: #333;
+    color: #555;
+    font-weight: bold;
     font-family: 'Open Sans', 'Arial', sans-serif;
     font-size: 14px;
     cursor: pointer;
@@ -198,6 +199,20 @@ button:hover {
   margin-top: 25px;
 }
 
+/*
+ *
+ * PLUGIN: jspsych-instructions
+ *
+ */
+
+ .jspsych-instructions-nav {
+   text-align: center;
+   margin-top: 2em;
+ }
+
+ .jspsych-instructions-nav button {
+   margin: 20px;
+ }
 /*
  *
  * PLUGIN: jspsych-multi-stim-multi-response

docs/markdown_docs/plugins/jspsych-instructions.md

@@ -0,0 +1,54 @@
+# jspsych-instructions plugin
+
+This plugin is for showing instructions to the subject. Navigation can be done using the mouse or keyboard.
+
+## Parameters
+
+This table lists the parameters associated with this plugin. Parameters with a default value of *undefined* must be specified. Other parameters can be left unspecified if the default value is acceptable.
+
+Parameter | Type | Default Value | Description
+----------|------|---------------|------------
+pages | array | *undefined* | Each element of the array is the content for a single page. Each page should be an HTML-formatted string.
+key_forward | key code | 'rightarrow' | This is the key that the subject can press in order to advance to the next page. Keys can be specified as their [numeric key code](http://www.cambiaresearch.com/articles/15/javascript-char-codes-key-codes) or as characters (e.g. `'a'`, `'q'`).
+key_backward | key code | 'leftarrow' | This is the key that the subject can press to return to the previous page.
+allow_backward | boolean | true | If true, the subject can return to previous pages of the instructions. If false, they may only advace to the next page.
+allow_keys | boolean | true | If true, the subject can use keyboard keys to navigate the pages. If false, they may not.
+show_clickable_nav | boolean | false | If true, then a `Previous` and `Next` button will be displayed beneath the instructions. Subjects can click the buttons to navigate.
+
+## Data Generated
+
+In addition to the [default data collected by all plugins](overview#datacollectedbyplugins), this plugin collects the following data for each trial.
+
+Name | Type | Value
+-----|------|------
+view_history | JSON string | A JSON string containing the order of pages the subject viewed (including when the subject returned to previous pages) and the time spent viewing each page.
+rt | numeric | The response time in milliseconds for the subject to view all of the pages.
+
+## Example
+
+#### Showing simple text instructions
+
+```javascript
+var block = {
+	type: 'instructions',
+	pages: [
+		'Welcome to the experiment. Click next to begin.',
+		'This is the second page of instructions.',
+		'This is the final page.'
+	],
+	show_clickable_nav: true
+}
+```
+
+#### Including images
+
+```javascript
+var block = {
+	type: 'instructions',
+	pages: [
+		'Welcome to the experiment. Click next to begin.',
+		'Here is a picture of what you will do: <img src="instruction_image.jpg"></img>'
+	],
+	show_clickable_nav: true
+}
+```

plugins/jspsych-instructions.js

@@ -0,0 +1,169 @@
+/* jspsych-text.js
+ * Josh de Leeuw
+ *
+ * This plugin displays text (including HTML formatted strings) during the experiment.
+ * Use it to show instructions, provide performance feedback, etc...
+ *
+ * documentation: docs.jspsych.org
+ *
+ *
+ */
+
+(function($) {
+    jsPsych.instructions = (function() {
+
+        var plugin = {};
+
+        plugin.create = function(params) {
+
+            params = jsPsych.pluginAPI.enforceArray(params, ['pages']);
+
+            var trials = new Array(1);
+
+            trials[0] = {};
+            trials[0].pages = params.pages;
+            trials[0].key_forward = params.key_forward || 'rightarrow';
+            trials[0].key_backward = params.key_backward || 'leftarrow';
+            trials[0].allow_backward = (typeof params.allow_backward === 'undefined') ? true : params.allow_backward;
+            trials[0].allow_keys = (typeof params.allow_keys === 'undefined') ? true : params.allow_keys;
+            trials[0].show_clickable_nav = (typeof params.show_clickable_nav === 'undefined') ? false : params.show_clickable_nav;
+
+            return trials;
+        };
+
+        plugin.trial = function(display_element, trial) {
+
+            // if any trial variables are functions
+            // this evaluates the function and replaces
+            // it with the output of the function
+            trial = jsPsych.pluginAPI.normalizeTrialVariables(trial);
+
+            var current_page = 0;
+
+            var view_history = [];
+
+            var start_time = (new Date()).getTime();
+
+            var last_page_update_time = start_time;
+
+            function show_current_page(){
+              display_element.html(trial.pages[current_page]);
+
+              if(trial.show_clickable_nav){
+
+                var nav_html = "<div class='jspsych-instructions-nav'>";
+                if(current_page != 0 && trial.allow_backward){
+                  nav_html += "<button id='jspsych-instructions-back'>&lt; Previous</button>";
+                }
+                nav_html += "<button id='jspsych-instructions-next'>Next &gt;</button></div>"
+
+                display_element.append(nav_html);
+
+                if(current_page != 0 && trial.allow_backward){
+                  $('#jspsych-instructions-back').on('click',function(){
+                    clear_button_handlers();
+                    back();
+                  });
+                }
+
+                $('#jspsych-instructions-next').on('click',function(){
+                  clear_button_handlers();
+                  next();
+                });
+
+              }
+            }
+
+            function clear_button_handlers() {
+              $('#jspsych-instructions-next').off('click');
+              $('#jspsych-instructions-back').off('click');
+            }
+
+            function next() {
+
+              add_current_page_to_view_history()
+
+              current_page++;
+
+              // if done, finish up...
+              if(current_page >= trial.pages.length) {
+                endTrial();
+              } else {
+                show_current_page();
+              }
+
+            }
+
+            function back() {
+
+              add_current_page_to_view_history()
+
+              current_page--;
+
+              show_current_page();
+            }
+
+            function add_current_page_to_view_history(){
+
+              var current_time = (new Date()).getTime();
+
+              var page_view_time = current_time - last_page_update_time;
+
+              view_history.push({
+                page_index: current_page,
+                viewing_time: page_view_time
+              });
+
+              last_page_update_time = current_time;
+            }
+
+            function endTrial() {
+
+              if(trial.allow_keys){
+                jsPsych.pluginAPI.cancelKeyboardResponse(keyboard_listener);
+              }
+
+              display_element.html('');
+
+              jsPsych.data.write($.extend({},{
+                "view_history": JSON.stringify(view_history),
+                "rt": (new Date()).getTime() - start_time
+              }, trial.data));
+
+              if (trial.timing_post_trial > 0) {
+                  setTimeout(function() {
+                      jsPsych.finishTrial();
+                  }, trial.timing_post_trial);
+              }
+              else {
+                  jsPsych.finishTrial();
+              }
+            }
+
+            var after_response = function(info) {
+
+                // check if key is forwards or backwards and update page
+                if(info.key === trial.key_forward || info.key === jsPsych.pluginAPI.convertKeyCharacterToKeyCode(trial.key_forward)){
+                  next();
+                }
+
+                if(info.key === trial.key_backward || info.key === jsPsych.pluginAPI.convertKeyCharacterToKeyCode(trial.key_backward)){
+                  if(current_page !== 0 && trial.allow_backward) {
+                    back();
+                  }
+                }
+
+                // have to reinitialize this instead of letting it persist to prevent accidental skips of pages by holding down keys too long
+                keyboard_listener = jsPsych.pluginAPI.getKeyboardResponse(after_response, [trial.key_forward, trial.key_backward]);
+            };
+
+            show_current_page();
+
+            if(trial.allow_keys){
+              var keyboard_listener = jsPsych.pluginAPI.getKeyboardResponse(after_response, [trial.key_forward, trial.key_backward]);
+            }
+        };
+
+        return plugin;
+    })();
+})(jQuery);

tests&examples/jspsych-instructions.html

@@ -0,0 +1,31 @@
+<!doctype html>
+<html>
+  <head>
+    <script src="js/jquery.min.js"></script>
+    <script src="../jspsych.js"></script>
+    <script src="../plugins/jspsych-instructions.js"></script>
+    <link rel="stylesheet" href="../css/jspsych.css"></link>
+  </head>
+  <body>
+    <div id="jspsych-target"></div>
+  </body>
+  <script>
+
+  var block = {
+    type: 'instructions',
+    pages: [
+      'Welcome to the experiment. Click next to begin.',
+      'This is the second page of instructions.',
+      'This is the final page.'
+    ],
+    show_clickable_nav: true
+  }
+
+  jsPsych.init({
+    display_element: $('#jspsych-target'),
+    experiment_structure: [block],
+    on_finish: function(){ jsPsych.data.displayData(); }
+  });
+
+  </script>
+</html>