lookit · becky-gilbert · Nov 14, 2024 · Nov 4, 2024 · Nov 5, 2024 · Nov 7, 2024
diff --git a/docs/source/index.rst b/docs/source/index.rst
@@ -62,6 +62,16 @@ Families may take part in studies from multiple labs over time. Having one centr
    researchers-lag-issues
    Releases <researchers-runner-releases>
 
+.. toctree::
+   :maxdepth: 2
+   :hidden:
+   :glob:
+   :caption: jsPsych studies
+
+   researchers-jspsych-intro
+   Limitations <researchers-jspsych-limitations>
+   Releases <researchers-jspsych-releases>
+
 .. toctree::
    :maxdepth: 2
    :hidden:

diff --git a/docs/source/researchers-edit-design.rst b/docs/source/researchers-edit-design.rst
@@ -31,7 +31,7 @@ jsPsych
 jsPsych Experiment Code
 =============================
 
-This is where you enter your jsPsych experiment code. This is the JavaScript code used to generate a jsPsych study, not the surrounding HTML. Please see our CHS jsPsych documentation and :ref:`tutorial <jspsych-tutorial-first-study>` for more information about what jsPsych plugins and versions are automatically loaded for you to use, and how to load stimuli files.
+This is where you enter your jsPsych experiment code. This is the JavaScript code used to generate a jsPsych study, not the surrounding HTML. Please see our :ref:`CHS jsPsych documentation <jspsych-intro>` and :ref:`tutorial <jspsych-tutorial-first-study>` for more information about what jsPsych plugins and versions are automatically loaded for you to use, and how to load stimuli files.
 
 .. _`Building an Experiment`: researchers-create-experiment.html
 

diff --git a/docs/source/researchers-jspsych-intro.rst b/docs/source/researchers-jspsych-intro.rst
@@ -0,0 +1,68 @@
+.. _jspsych-intro:
+
+====================================
+jsPsych studies on CHS
+====================================
+
+`jsPsych <https://www.jspsych.org/latest/>`__ is an open source library for creating a wide range of behavioral experiments that run in a web browser. It consists of a core library and "plugins". Plugins are the components that make up the experiment. Each plugin lets you define different kinds of events (e.g. presenting an image or text) and it collects different kinds of data (e.g. responses and response times). The jsPsych library also supports a wide range of features that are commonly used in behavioral experiments, like looping over sets of trials, randomizing, sampling, and conditional behavior.
+
+To get a feel for how to build a jsPsych experiment, you can check out the jsPsych `Hello World tutorial <https://www.jspsych.org/v8/tutorials/hello-world/>`__ and `RT task tutorial <https://www.jspsych.org/v8/tutorials/rt-task/>`__. We also have our own :ref:`CHS jsPsych Hello World tutorial <jspsych-tutorial-first-study>`, which demonstrates the CHS-specific features (:ref:`detailed in this section <chs-jspsych-packages>`) that we've added for jsPsych studies running on the CHS platform.
+
+To learn more about jsPsych features, some other great places to start are the jsPsych documentation about `timelines <https://www.jspsych.org/v8/overview/timeline/>`__ and `dynamic parameters <https://www.jspsych.org/v8/overview/dynamic-parameters/>`__.
+
+
+.. _jspsych-packages:
+
+jsPsych packages
+==============================
+
+The CHS jsPsych experiment runner automatically loads a set of packages from the standard jsPsych library for researchers to use. These are:
+
+- `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``
+- `Preload plugin <https://www.jspsych.org/v8/plugins/preload/>`__ v2.0.0: ``jsPsychPreload``
+
+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.
+
+
+.. _chs-jspsych-packages:
+
+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. 
+
+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-jspsych-plugins:
+
+Plugins
+---------------------
+
+- `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``
+
+.. _chs-jspsych-extensions:
+
+Extensions
+--------------------------
+
+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>`__ 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. 
diff --git a/docs/source/researchers-jspsych-limitations.rst b/docs/source/researchers-jspsych-limitations.rst
@@ -0,0 +1,20 @@
+.. _jspsych-limitations:
+
+====================================
+Limitations to CHS jsPsych studies
+====================================
+
+While building your jsPsych study on the CHS platform, you may run into problems because of certain limitations to the CHS jsPsych experiment runner. This is especially likely if you're an experienced jsPsych user with experiments that you want to move onto CHS, or if you're referencing other (non-CHS) jsPsych tutorials/examples to build your study on CHS. 
+
+Here are some things you should keep in mind when creating jsPsych studies on CHS.
+
+- **All of the code needed to run your experiment must be provided in the CHS JavaScript editor.** 
+    * Unlike many other jsPsych hosting options, on CHS you do not write an HTML file. CHS provides your study's HTML file and loads the JavaScript and CSS files. You can think of the CHS JavaScript editor as the main ``script`` element that you'll see in most jsPsych tutorials/examples.
+    * You do not have the option to load additional files, including stimuli files or custom plugins/extensions.
+    * Your stimuli files must be hosted online and loaded from an external URL, for instance via institutional storage, cloud storage, or Github (see our documentation about :ref:`hosting your stimuli online <putting-stimuli-online>`).
+
+- **The CHS jsPsych experiment runner supports a limited set of jsPsych package/versions.**
+    * Please refer to our list of available :ref:`jsPsych packages/versions <jspsych-packages>`, and our list of :ref:`custom CHS jsPsych packages <chs-jspsych-packages>`.
+    * If you're trying to use a jsPsych plugin that is not available on CHS, you will see the following console error when you try to run the study: "Uncaught ReferenceError: <PLUGIN NAME> is not defined".
+    * If your jsPsych study uses plugins that are not available on CHS, you may be able to replace them with plugins that we do support. For instance, instructions that are presented with the ``instructions`` plugin could be presented via HTML keyboard/button response trials.
+    * If you have existing study code that uses a different version of the jsPsych core library or plugins, you may be able to update/modify your jsPsych code so that it's compatible with the versions we support. The jsPsych documentation offers version migration guides in their "Support" section, and all jsPsych packages contain release notes with detailed explanations of changes.
diff --git a/docs/source/researchers-jspsych-releases.rst b/docs/source/researchers-jspsych-releases.rst
@@ -0,0 +1,7 @@
+.. _jspsych-releases:
+
+====================================
+jsPsych experiment runner updates
+====================================
+
+No updates yet. Watch this space!
diff --git a/docs/source/tutorial-jspsych/tutorial-jspsych-first-study.rst b/docs/source/tutorial-jspsych/tutorial-jspsych-first-study.rst
@@ -333,7 +333,7 @@ Check out the jsPsych "hello world" tutorial if you want to start from the basic
 
 There are also lots of examples on the jsPsych plugin documentation pages (e.g. `html-button-response plugin <https://www.jspsych.org/latest/plugins/html-button-response/>`__, `survey plugin <https://www.jspsych.org/latest/plugins/survey/>`__), as well as in the `jsPsych repository "examples" folder <https://github.com/jspsych/jsPsych/tree/main/examples>`__.
 
-Keep in mind that our internal CHS jsPsych experiment runner offers a limited set of jsPsych packages (core library and plugins/extensions) and package versions. In the future, we plan to expand this set. Please see our CHS jsPsych limitations page for information on what jsPsych packages are currently available.
+Keep in mind that our internal CHS jsPsych experiment runner offers a limited set of jsPsych packages (core library and plugins/extensions) and package versions. In the future, we plan to expand this set. Please see our :ref:`CHS jsPsych limitations page <jspsych-limitations>` for information on what jsPsych packages are currently available.
 
 
 Bonus: Translate your experiment into another language