add examples

docs/markdown_docs/plugins/jspsych-reconstruction.md

@@ -0,0 +1,45 @@
+# jspsych-reconstruction plugin
+
+This plugin allows a subject to interact with a stimulus by modifying a parameter of the stimulus and observing the change in the stimulus in real-time.
+
+The stimulus must be defined through a function that returns an HTML-formatted string. The function should take a single value, the parameter that can be modified by the subject. The value can only range from 0 to 1. See the example at the bottom of the page for a sample function.
+
+## 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
+----------|------|---------------|------------
+stim_function | function | *undefined* | A function with a single parameter that returns an HTML-formatted string representing the stimulus.
+starting_value | array | [0.5] | The starting values of the stimulus parameter. Each element in the array will be a different trial.
+step_size | numeric | 0.05 | The change in the stimulus parameter caused by pressing one of the modification keys.
+key_increase | key code | 'h' | The key to press for increasing the parameter value.
+key_decrease | key code | 'g' | The key to press for decreasing the parameter value.
+
+## Data Generated
+
+In addition to the [default data collected by all plugins](), this plugin collects the following data for each trial.
+
+Name | Type | Value
+-----|------|------
+start_value | numeric | The starting value of the stimulus parameter.
+final_value | numeric | The final value of the stimulus parameter.
+rt | numeric | The length of time, in milliseconds, that the trial lasted.
+
+## Examples
+
+```javascript
+var sample_function = function(param){
+	var size = 50 + Math.floor(param*250);
+	var html = '<div style="display: block; margin: auto; height: 300px;">'+
+	'<div style="display: block; margin: auto; background-color: #000000; '+
+	'width: '+size+'px; height: '+size+'px;"></div></div>';
+	return html;
+}
+
+var block = {
+	type: 'reconstruction',
+	stim_function: sample_function,
+	starting_value: [0.25, 0.5, 0.75]
+}
+```

docs/markdown_docs/plugins/jspsych-single-audio.md

@@ -0,0 +1,52 @@
+# jspsych-single-audio plugin
+
+This plugin plays audio files and records responses generated with the keyboard.
+
+Audio files are played using the [WebAudio API](https://developer.mozilla.org/en-US/docs/Web/API/Web_Audio_API). This allows for reasonably precise timing of the playback. The timing of responses generated is measured against the WebAudio specific clock, improving the measurement of response times.
+
+Audio files are automatically preloaded by jsPsych.
+
+## 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
+----------|------|---------------|------------
+stimuli | array | *undefined* | Each element of the array is a stimulus. A stimulus is a path to an audio file. Each stimulus will be presented in its own trial, and thus the length of this array determines the total number of trials.
+choices | array | [ ] | This array contains the keys that the subject is allowed to press in order to respond to the stimulus. 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'`). The default value of an empty array means that all keys will be accepted as valid responses.
+prompt | string | "" | This string can contain HTML markup. Any content here will be displayed on the screen. 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_response | numeric | -1 | How long to wait for the subject to make a response before ending the trial in milliseconds. If the subject fails to make a response before this timer is reached, the the subject's response will be recorded as -1 for the trial and the trial will end. If the value of this parameter is -1, then the trial will wait for a response indefinitely.
+continue_after_response | boolean | true | If true, then the trial will end whenever the subject makes a response (assuming they make their response before the cutoff specified by the `timing_response` parameter). If false, then the trial will continue until the value for `timing_response` is reached. You can use this parameter to force the subject to view a stimulus for a fixed amount of time, even if they respond before the time is complete.
+
+## Data Generated
+
+In addition to the [default data collected by all plugins](), this plugin collects the following data for each trial.
+
+Name | Type | Value
+-----|------|------
+stimulus | string | The path to the file that was played during the 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 audio file began playing.
+
+## Examples
+
+These examples show how to define a block using the single-stim plugin to achieve various goals.
+
+#### Playing a sound
+
+```javascript
+var block = {
+	type: 'single-audio',
+	stimuli: ['sound/sound.mp3']
+}
+```
+
+#### Restricting which keys the subject can use to respond
+
+```javascript
+var block = {
+	type: 'single-stim',
+	stimuli: ['sound/sound.mp3'],
+	choices: ['h','s']
+}
+```

docs/mkdocs.yml

@@ -30,8 +30,10 @@ pages:
 - ['plugins/jspsych-html.md', 'Plugins', 'jspsych-html']
 - ['plugins/jspsych-multi-stim-multi-response.md', 'Plugins', 'jspsych-multi-stim-multi-response']
 - ['plugins/jspsych-palmer.md', 'Plugins', 'jspsych-palmer']
+- ['plugins/jspsych-reconstruction.md', 'Plugins', 'jspsych-reconstruction']
 - ['plugins/jspsych-same-different.md', 'Plugins', 'jspsych-same-different']
 - ['plugins/jspsych-similarity.md', 'Plugins', 'jspsych-similarity']
+- ['plugins/jspsych-single-audio.md', 'Plugins', 'jspsych-single-audio']
 - ['plugins/jspsych-single-stim.md', 'Plugins', 'jspsych-single-stim']
 - ['plugins/jspsych-survey-likert.md', 'Plugins', 'jspsych-survey-likert']
 - ['plugins/jspsych-survey-text.md', 'Plugins', 'jspsych-survey-text']

tests&examples/jspsych-reconstruction.html

@@ -0,0 +1,34 @@
+<!doctype html>
+<html>
+  <head>
+    <script src="js/jquery.min.js"></script>
+    <script src="../jspsych.js"></script>
+    <script src="../plugins/jspsych-reconstruction.js"></script>
+    <link rel="stylesheet" href="../css/jspsych.css"></link>
+  </head>
+  <body>
+    <div id="jspsych-target"></div>
+  </body>
+  <script>
+
+  var sample_function = function(param){
+    var size = 50 + Math.floor(param*250);
+    var html = '<div style="display: block; margin: auto; height: 300px;">'+
+      '<div style="display: block; margin: auto; background-color: #000000; '+
+      'width: '+size+'px; height: '+size+'px;"></div></div>';
+    return html;
+  }
+
+  var block_1 = {
+    type: 'reconstruction',
+    stim_function: sample_function,
+    starting_value: [0.25, 0.5, 0.75]
+  }
+
+  jsPsych.init({
+    display_element: $('#jspsych-target'),
+    experiment_structure: [block_1]
+  });
+
+  </script>
+</html>

tests&examples/jspsych-single-audio.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-single-audio.js"></script>
+    <link rel="stylesheet" href="../css/jspsych.css"></link>
+  </head>
+  <body>
+    <div id="jspsych-target"></div>
+  </body>
+  <script>
+
+  /*
+  this demo will only work if run online or with special permissions enable offline
+  for chrome, launch the browser from the command-line:
+  chrome --allow-file-access-from-files
+  */
+
+  var block_1 = {
+    type: 'single-audio',
+    stimuli: ['sound/sound.mp3']
+  }
+
+  jsPsych.init({
+    display_element: $('#jspsych-target'),
+    experiment_structure: [block_1]
+  });
+
+  </script>
+</html>