Move changes to master

docs/source/_static/css/lookit.css

@@ -94,7 +94,7 @@ ul.tutorial-participants {
     column-count: 2;
 }
 
-ul.tutorial-participants li {
+ul.tutorial-participants li, ul.jspsych-plugins-extensions li {
     padding: 0;
 }
 

docs/source/index.rst

@@ -70,7 +70,6 @@ Families may take part in studies from multiple labs over time. Having one centr
 
    researchers-jspsych-intro
    Limitations <researchers-jspsych-limitations>
-   Releases <researchers-jspsych-releases>
 
 .. toctree::
    :maxdepth: 2

docs/source/researchers-jspsych-intro.rst

@@ -16,20 +16,77 @@ To learn more about jsPsych features, some other great places to start are the j
 jsPsych packages
 ==============================
 
-The CHS jsPsych experiment runner automatically loads a set of packages from the standard jsPsych library for researchers to use. These are:
+The CHS jsPsych experiment runner automatically loads a set of packages from the standard jsPsych library for researchers to use. The set of jsPsych packages/versions loaded by CHS is below, along with links to documentation and change logs (version history).
 
-- `Core jsPsych library <https://www.jspsych.org/v8/>`__ v8.0.3
-- `HTML keyboard response plugin <https://www.jspsych.org/v8/plugins/html-keyboard-response/>`__ v2.0.0: ``jsPsychHtmlKeyboardResponse``
-- `Image keyboard response plugin <https://www.jspsych.org/v8/plugins/image-keyboard-response/>`__ v2.0.0: ``jsPsychImageKeyboardResponse``
-- `HTML button response plugin <https://www.jspsych.org/v8/plugins/html-button-response>`__ v2.0.0: ``jsPsychHtmlButtonResponse``
-- `Image button response plugin <https://www.jspsych.org/v8/plugins/image-button-response/>`__ v2.0.0: ``jsPsychImageButtonResponse``
-- `Video button response plugin <https://www.jspsych.org/v8/plugins/video-button-response/>`__ v2.0.0: ``jsPsychVideoButtonResponse``
-- `Preload plugin <https://www.jspsych.org/v8/plugins/preload/>`__ v2.0.0: ``jsPsychPreload``
-- `Survey text plugin <https://www.jspsych.org/latest/plugins/survey-text/>`__ v2.1.0: ``jsPsychSurveyText``
-- `Survey multi-choice plugin <https://www.jspsych.org/latest/plugins/survey-multi-choice/>`__ v2.1.0: ``jsPsychSurveyMultiChoice``
-- `Fullscreen plugin <https://www.jspsych.org/latest/plugins/fullscreen/>`__ v2.1.0: ``jsPsychFullscreen``
+.. rst-class:: jspsych-plugins-extensions
 
-We will likely add more options in the future. If there are any specific jsPsych plugins/extensions that your experiment needs, please let us know! The best way to request access to a standard jsPsych package is by creating a ``lookit-api`` `Github issue <https://github.com/lookit/lookit-api/issues>`__, but you can also let us know on Slack.
+- `Core jsPsych library <https://www.jspsych.org/v8/>`__
+
+  - v8.0.3 (`see changelog <https://github.com/jspsych/jsPsych/blob/main/packages/jspsych/CHANGELOG.md>`__)
+
+- `HTML keyboard response plugin <https://www.jspsych.org/v8/plugins/html-keyboard-response/>`__
+
+  - v2.0.0 (`see changelog <https://github.com/jspsych/jsPsych/blob/main/packages/plugin-html-keyboard-response/CHANGELOG.md>`__)
+  - ``jsPsychHtmlKeyboardResponse``
+
+- `Image keyboard response plugin <https://www.jspsych.org/v8/plugins/image-keyboard-response/>`__
+
+  - v2.0.0 (`see changelog <https://github.com/jspsych/jsPsych/blob/main/packages/plugin-image-keyboard-response/CHANGELOG.md>`__)
+  - ``jsPsychImageKeyboardResponse``
+
+- `Video keyboard response <https://www.jspsych.org/latest/plugins/video-keyboard-response/>`__
+
+  - v2.1.0 (`see changelog <https://github.com/jspsych/jsPsych/blob/main/packages/plugin-video-keyboard-response/CHANGELOG.md>`__)
+  - ``jsPsychVideoKeyboardResponse``
+
+- `HTML button response plugin <https://www.jspsych.org/v8/plugins/html-button-response>`__
+
+  - v2.0.0 (`see changelog <https://github.com/jspsych/jsPsych/blob/main/packages/plugin-html-button-response/CHANGELOG.md>`__)
+  - ``jsPsychHtmlButtonResponse``
+
+- `Image button response plugin <https://www.jspsych.org/v8/plugins/image-button-response/>`__
+
+  - v2.0.0 (`see changelog <https://github.com/jspsych/jsPsych/blob/main/packages/plugin-image-button-response/CHANGELOG.md>`__)
+  - ``jsPsychImageButtonResponse``
+
+- `Video button response plugin <https://www.jspsych.org/v8/plugins/video-button-response/>`__
+
+  - v2.0.0 (`see changelog <https://github.com/jspsych/jsPsych/blob/main/packages/plugin-video-button-response/CHANGELOG.md>`__)
+  - ``jsPsychVideoButtonResponse``
+
+- `Image hotspots <https://github.com/jspsych/jspsych-contrib/blob/main/packages/plugin-image-hotspots/docs/plugin-image-hotspots.md>`__
+
+  - v1.0.0 (`see changelog <https://github.com/jspsych/jspsych-contrib/blob/main/packages/plugin-image-hotspots/CHANGELOG.md>`__)
+  - ``jsPsychImageHotspots``
+
+- `Video hotspots <https://github.com/jspsych/jspsych-contrib/blob/main/packages/plugin-video-hotspots/docs/plugin-video-hotspots.md>`__
+
+  - v1.0.0 (`see changelog <https://github.com/jspsych/jspsych-contrib/blob/main/packages/plugin-video-hotspots/CHANGELOG.md>`__)
+  - ``jsPsychVideoHotspots``
+
+- `Preload plugin <https://www.jspsych.org/v8/plugins/preload/>`__
+
+  - v2.0.0  (`see changelog <https://github.com/jspsych/jsPsych/blob/main/packages/plugin-preload/CHANGELOG.md>`__)
+  - ``jsPsychPreload``
+
+- `Survey text plugin <https://www.jspsych.org/latest/plugins/survey-text/>`__
+
+  - v2.1.0 (`see changelog <https://github.com/jspsych/jsPsych/blob/main/packages/plugin-survey-text/CHANGELOG.md>`__)
+  - ``jsPsychSurveyText``
+
+- `Survey multi-choice plugin <https://www.jspsych.org/latest/plugins/survey-multi-choice/>`__
+
+  - v2.1.0 (`see changelog <https://github.com/jspsych/jsPsych/blob/main/packages/plugin-survey-multi-choice/CHANGELOG.md>`__)
+  - ``jsPsychSurveyMultiChoice``
+
+- `Fullscreen plugin <https://www.jspsych.org/latest/plugins/fullscreen/>`__
+
+  - v2.1.0 (`see changelog <https://github.com/jspsych/jsPsych/blob/main/packages/plugin-fullscreen/CHANGELOG.md>`__)
+  - ``jsPsychFullscreen``
+
+.. admonition:: Need something else?
+
+   If there are any specific jsPsych plugins/extensions that your experiment needs, please let us know! The best way to request access to a standard jsPsych package is by creating a ``lookit-api`` `Github issue <https://github.com/lookit/lookit-api/issues>`__, but you can also let us know on Slack.
 
 
 .. _chs-jspsych-packages:
@@ -39,34 +96,56 @@ Custom CHS jsPsych packages
 
 In addition to the jsPsych packages listed above, the CHS jsPsych experiment runner also automatically loads some custom packages. These custom plugins/extensions were designed to "fill in the gaps" in the sort of functionality that CHS researchers typically need for child development studies. This functionality includes: standardized webcam/mic configuration steps, video-recorded consent, trial/session recording, and standardized exit surveys.
 
-The `CHS jsPsych documentation <https://lookit.readthedocs.io/projects/chs-jspsych/en/latest/>`__ contains more information about all of the parameters available in the CHS jsPsych plugins/extensions listed below. 
+The custom CHS-jsPsych packages/versions are listed below, along with links to documentation and change logs (version history). The `CHS jsPsych documentation <https://lookit.readthedocs.io/projects/chs-jspsych/en/latest/>`__ contains more information about all of the parameters available in the CHS-jsPsych plugins/extensions.
 
-Do you need any types of trials (Lookit EFP "frames") or features that are not listed here, and are not available through the standard jsPsych library? Let us know! The best way to request a custom (CHS-specific) jsPsych plugin/extension or feature is by creating a ``lookit-jspsych`` `Github issue <https://github.com/lookit/lookit-jspsych/issues>`__, but you can also let us know on Slack.
+**CHS Record package**
 
-.. _chs-jspsych-plugins:
+Current version: 4.1.0 (`see changelog <https://github.com/lookit/lookit-jspsych/blob/main/packages/record/CHANGELOG.md>`__)
 
-Plugins
----------------------
+.. rst-class:: jspsych-plugins-extensions
 
-- `Video config plugin <https://lookit.readthedocs.io/projects/chs-jspsych/en/latest/record/#video-configuration>`__ in the CHS Record package: ``chsRecord.VideoConfigPlugin``
-- `Video consent plugin <https://lookit.readthedocs.io/projects/chs-jspsych/en/latest/record/#video-consent>`__ in the CHS Record package: ``chsRecord.VideoConsentPlugin``
-- `Start session recording plugin <https://lookit.readthedocs.io/projects/chs-jspsych/en/latest/record/#session-recording>`__ in the CHS Record package: ``chsRecord.StartRecordPlugin``
-- `Stop session recording plugin <https://lookit.readthedocs.io/projects/chs-jspsych/en/latest/record/#session-recording>`__ in the CHS Record package: ``chsRecord.StopRecordPlugin``
-- `Consent survey plugin <https://lookit.readthedocs.io/projects/chs-jspsych/en/latest/surveys/#consent-survey>`__ in the CHS Surveys package: ``chsSurveys.ConsentSurveyPlugin``
-- `Exit survey plugin <https://lookit.readthedocs.io/projects/chs-jspsych/en/latest/surveys/#exit-survey>`__ in the CHS Surveys package: ``chsSurveys.ExitSurveyPlugin``
+- `Video config plugin <https://lookit.readthedocs.io/projects/chs-jspsych/en/latest/record/#video-configuration>`__
 
-.. _chs-jspsych-extensions:
+  - ``chsRecord.VideoConfigPlugin``
 
-Extensions
---------------------------
+- `Video consent plugin <https://lookit.readthedocs.io/projects/chs-jspsych/en/latest/record/#video-consent>`__
+
+  - ``chsRecord.VideoConsentPlugin``
+
+- `Start session recording plugin <https://lookit.readthedocs.io/projects/chs-jspsych/en/latest/record/#session-recording>`__
+
+  - ``chsRecord.StartRecordPlugin``
+
+- `Stop session recording plugin <https://lookit.readthedocs.io/projects/chs-jspsych/en/latest/record/#session-recording>`__
+
+  - ``chsRecord.StopRecordPlugin``
 
-jsPsych extensions are packages that extend the functionality of a plugin.
+- `Trial recording extension <https://lookit.readthedocs.io/projects/chs-jspsych/en/latest/record/#trial-recording>`__
+
+  - ``chsRecord.TrialRecordExtension``
+
+**CHS Surveys package**
+
+Current version: v4.0.1 (`see changelog <https://github.com/lookit/lookit-jspsych/blob/main/packages/surveys/CHANGELOG.md>`__)
+
+.. rst-class:: jspsych-plugins-extensions
+
+- `Consent survey plugin <https://lookit.readthedocs.io/projects/chs-jspsych/en/latest/surveys/#consent-survey>`__
+
+  - ``chsSurveys.ConsentSurveyPlugin``
+
+- `Exit survey plugin <https://lookit.readthedocs.io/projects/chs-jspsych/en/latest/surveys/#exit-survey>`__
+
+  - ``chsSurveys.ExitSurveyPlugin``
 
-- `Trial recording extension <https://lookit.readthedocs.io/projects/chs-jspsych/en/latest/record/#trial-recording>`__ in the CHS Record package: ``chsRecord.TrialRecordExtension``
 
 .. _chs-jspsych-translations:
 
 Translations
 --------------------------
 
 All of these plugins/extensions support the automatic translation of hard-coded text through a ``locale`` parameter. 
+
+.. admonition:: Need something else?
+
+    Do you need any types of trials (Lookit EFP "frames") or features that are not listed here, and are not available through the standard jsPsych library? Let us know! The best way to request a custom (CHS-specific) jsPsych plugin/extension or feature is by creating a ``lookit-jspsych`` `Github issue <https://github.com/lookit/lookit-jspsych/issues>`__, but you can also let us know on Slack.

docs/source/tutorial-contributing.rst

@@ -368,6 +368,9 @@ List of tutorial participants
 - Sarah Kiefer (Brown University)
 - Olivia Maltz (Temple University)
 - Madeline Ephraim (University of Rochester)
+- Emma Reddy (University of Maryland, College Park)
+- Wilder Hartwell (University of California, San Diego)
+- Kaitlin Dobkowski (Boston University)
 
 Checking for and creating issues on Github
 -------------------------------------------

docs/source/tutorial-jspsych/tutorial-jspsych-first-study.rst

@@ -199,7 +199,12 @@ The full code so far:
 Step 6: Add session recording
 -------------------------------------------------
 
-We now have a bare-bones CHS experiment structure: webcam/mic configuration, video-recorded consent, our "experiment" (hello world trial), and an exit survey. The only thing we're missing for typical CHS experiments is webcam recordings that are captured during the experiment. We can do that using either: (a) session recording, where a webcam recording starts at a specified point in the experiment's trial sequence and ends at another point, with any number of experimental trials in between, or (b) trial recording, where a webcam recording is created at the start of a particular trial and ends when that trial finishes.
+We now have a bare-bones CHS experiment structure: webcam/mic configuration, video-recorded consent, our "experiment" (hello world trial), and an exit survey. The only thing we're missing for typical CHS experiments is webcam recordings that are captured during the experiment. We can do that using either:
+
+.. rst-class:: jspsych-plugins-extensions
+
+- **session recording**, where a webcam recording starts at a specified point in the experiment's trial sequence and ends at another point, with any number of experimental trials in between, or 
+- **trial recording**, where a webcam recording is created at the start of a particular trial and ends when that trial finishes.
 
 .. admonition:: When should/shouldn't I use trial and session recording?
 
@@ -258,6 +263,17 @@ Here's the full experiment code now:
 
     jsPsych.run([video_config, video_consent, start_rec, hello_trial, stop_rec, exit_survey]);
 
+Now when you save your code and preview the experiment, your experiment will run as it did before, but you will also get a video recording that captures the duration between your ``start_rec`` and ``stop_rec`` trials. To see your recording, you will need to approve your own consent statement: from the study details page, click "Review Consent", find your most recent session, change it from "pending" to "accept", then click "Submit Rulings & Comments". Then go back to your study details page, click "Study Responses", click "Individual Responses", and find your most recent session in the table. With that response selected, you should see two videos listed in the "Download videos" box - one is your consent video and the other is your session recording.
+
+**Bonus step**: Use the ``wait_for_upload_message`` parameter to override the ``stop_rec`` trial's default message ("uploading video, please wait...") and present some custom HTML content instead. The example below will display some text and play a video.
+
+.. code:: javascript
+
+    const stop_rec = {
+        type: chsRecord.StopRecordPlugin,
+        wait_for_upload_message: "<p style='font-size: 30px; color: blue;'>Please wait while we upload your video!</p><video src='https://www.mit.edu/~kimscott/placeholderstimuli/webm/attentiongrabber.webm' autoplay />",
+    };
+
 
 Step 7: Switch to trial recording
 -------------------------------------------------
@@ -271,7 +287,7 @@ We now we'll switch to trial-level recording during our hello world trial. To do
         jsPsych.run([video_config, video_consent, hello_trial, exit_survey]);
 
 
-2. Add the `chsRecord.TrialRecordExtension` to the parameters that are passed into ``initJsPsych``. This is the `jsPsych initialization function <https://www.jspsych.org/latest/reference/jspsych/#initjspsych>`__, which takes an optional settings object and parameters. So far we haven't needed any of these setting parameters, but now we do need to tell jsPsych that we're planning to use the trial recording extension at some point during the experiment.
+2. Add the ``chsRecord.TrialRecordExtension`` to the parameters that are passed into ``initJsPsych``. This is the `jsPsych initialization function <https://www.jspsych.org/latest/reference/jspsych/#initjspsych>`__, which takes an optional settings object and parameters. So far we haven't needed any of these setting parameters, but now we do need to tell jsPsych that we're planning to use the trial recording extension at some point during the experiment.
 
     .. code:: javascript
 
@@ -280,8 +296,7 @@ We now we'll switch to trial-level recording during our hello world trial. To do
         });
 
 
-
-3. Add the `chsRecord.TrialRecordExtension` to the configuration for the trial that we want to be recorded. This tells jsPsych to run trial recording for that particular trial. Here we are just adding trial recording to the "hello_world" trial.
+3. Add the ``chsRecord.TrialRecordExtension`` to the configuration for the trial that we want to be recorded. This tells jsPsych to run trial recording for that particular trial. Here we are just adding trial recording to the "hello_world" trial.
 
     .. code:: javascript
 
@@ -323,8 +338,50 @@ Here's what the whole experiment looks like now:
 
     jsPsych.run([video_config, video_consent, hello_trial, exit_survey]);
 
+You can follow the instructions at the end of the previous step to see your session recordings. Now for your most recent session, you should still see two videos listed in the "Download videos" box - one is your consent video and the other is your trial recording. If you edit your study code to add another ``hello_trial``, then you will end up with three videos: a consent recording and two trial recordings.
+
+**Bonus step**: Use the ``wait_for_upload_message`` parameter to override the default uploading message ("uploading video, please wait...") that is shown at the end of the ``hello_trial``, and present some custom HTML content instead. To do this, we need to add a new property called "params" alongside the trial recording extension. The value of "params" is an object that contains the parameter names and values that should be passed to the extension.
+
+The example below will display some custom text and a video while the webcam recording is uploading at the end of the ``hello_trial``.
+
+.. code:: javascript
+
+    const hello_trial = {
+        type: jsPsychHtmlButtonResponse,
+        stimulus: 'Hello world!',
+        choices: ['Next'],
+        extensions: [{
+            type: chsRecord.TrialRecordExtension,
+            params: { wait_for_upload_message: "<p style='font-size: 30px; color: blue;'>Please wait while we upload your video!</p><video src='https://www.mit.edu/~kimscott/placeholderstimuli/webm/attentiongrabber.webm' autoplay />" }
+        }],
+    };
+
+Step 8: Move participants in and out of fullscreen
+------------------------------------------------------
+
+Typically you'll want your participant's browser to be in fullscreen mode during your experiment, which you can do using `jsPsych's fullscreen plugin <https://www.jspsych.org/latest/plugins/fullscreen/>`__. You can create a trial that will let participants know that they will enter fullscreen when they click the "Continue" button (with parameters that allow you to change the message and button label). You can also create a trial that will automatically exit fullscreen mode.
+
+.. code:: javascript
+
+    const enter_fullscreen = {
+        type: jsPsychFullscreen,
+        fullscreen_mode: true
+    };
+
+    const exit_fullscreen = {
+        type: jsPsychFullscreen,
+        fullscreen_mode: false,
+        delay_after: 0
+    };
+
+Once you've created these trials, you can put them anywhere in your experiment timeline.
+
+.. code:: javascript
+
+    jsPsych.run([enter_fullscreen, video_config, video_consent, hello_trial, exit_fullscreen, exit_survey]);
+
 
-Step 8: Learn more on the jsPsych website
+Step 9: Learn more on the jsPsych website
 -------------------------------------------------
 
 Well done! You've learned how to create a jsPsych experiment on CHS! You can use this tutorial code as a starting point for your real experiment, and replace the hello world trial with some actual jsPsych experiment code.