finish mixin docs, deprecated frame docs

lookit · Nov 3, 2020 · fb2aebd · fb2aebd
1 parent d51e344
commit fb2aebd
Show file tree

Hide file tree

Showing 20 changed files with 608 additions and 137 deletions.
diff --git a/app/components/exp-lookit-change-detection/doc.rst b/app/components/exp-lookit-change-detection/doc.rst
@@ -1,3 +1,5 @@
+.. _exp-lookit-change-detection:
+
 exp-lookit-change-detection
 ==============================================
 

diff --git a/app/components/exp-lookit-composite-video-trial/doc.rst b/app/components/exp-lookit-composite-video-trial/doc.rst
@@ -1,75 +1,11 @@
 exp-lookit-composite-video-trial
 ==============================================
 
-Composite video display for typical looking measures trials (e.g. preferential looking,
-looking time). (Previously called exp-lookit-video.)
+This frame is deprecated and will not be included in release 2.x.
+Please see `the old docs <https://lookit.github.io/lookit-frameplayer-docs/classes/Exp-lookit-composite-video-trial.html>`__.
 
-Overview of phases
+Consider instead
 ------------------
 
-The trial consists of four phases, each of which is optional.
-
-1. **Announcement:** The audio in audioSources is played while the attnSources video is played centrally, looping as needed. This lasts for announceLength seconds or the duration of the audio, whichever is longer. To skip this phase, set announceLength to 0 and do not provide audioSources.
-
-2. **Intro:** The introSources video is played centrally until it ends. To skip this phase, do not provide introSources.
-
-3. **Calibration:** The video in calibrationVideoSources is played (looping as needed) in each of the locations specified in calibrationPositions in turn, remaining in each position for calibrationLength ms. At the start of each position the audio in calibrationAudioSources is played once. (Audio will be paused and restarted if it is longer than calibrationLength.) Set calibrationLength to 0 to skip calibration.
-
-4. **Test:** The video in sources and audio in musicSources (optional) are played until either: testLength seconds have elapsed (with video looping if needed), or the video has been played testCount times. If testLength is set, it overrides testCount - for example if testCount is 1 and testLength is 30, a 10-second video will be played 3 times. If the participant pauses the study during the test phase, then after restarting the trial, the video in altSources will be used again (defaulting to the same video if altSources is not provided). To skip this phase, do not provide sources.
-
-Display
--------
-
-This frame is displayed fullscreen. If the previous frame is not fullscreen, then that frame
-needs to include a manual "next" button so that there's a user interaction
-event to trigger fullscreen mode. (Browsers don't allow us to switch to fullscreen mode
-without a user event.)
-
-
-Specifying media locations
----------------------------
-
-For any parameters that expect a list of audio/video sources, you have two options:
-
-1. You can provide a list of src/type pairs with full paths, like this:
-
-.. code:: javascript
-
-    [
-        {
-            'src': 'http://.../video1.mp4',
-            'type': 'video/mp4'
-        },
-        {
-            'src': 'http://.../video1.webm',
-            'type': 'video/webm'
-        }
-    ]
-
-2. You can provide a single string 'stub', which will be expanded based on the parameter ``baseDir`` and the media types expected (either ``audioTypes`` or
-``videoTypes`` as appropriate).
-
-For example, if you provide the audio source
-```intro```, ``baseDir`` is ``https://mystimuli.org/mystudy/``, and ``audioTypes`` is ``['mp3', 'ogg']``, then this
-will be expanded to:
-
-.. code:: javascript
-
-     [
-            {
-                src: 'https://mystimuli.org/mystudy/mp3/intro.mp3',
-                type: 'audio/mp3'
-            },
-            {
-                src: 'https://mystimuli.org/mystudy/ogg/intro.ogg',
-                type: 'audio/ogg'
-            }
-    ]
-
-This allows you to simplify your JSON document a bit and also easily switch to a
-new version of your stimuli without changing every URL. You can mix source objects with
-full URLs and those using stubs within the same directory. However, any stimuli
-specified using stubs MUST be
-organized as expected under ``baseDir/MEDIATYPE/filename.MEDIATYPE``.
-
-
+- :ref:`exp-lookit-video` to play a video and optional audio, with more configurability & better timing precision for the recording
+- :ref:`exp-lookit-calibration` to show a calibration stimulus at specific locations, again with more configurability and better timing precision
diff --git a/app/components/exp-lookit-dialogue-page/doc.rst b/app/components/exp-lookit-dialogue-page/doc.rst
@@ -0,0 +1,10 @@
+exp-lookit-dialogue-page
+==============================================
+
+This frame is deprecated and will not be included in release 2.x.
+Please see `the old docs <https://lookit.github.io/lookit-frameplayer-docs/classes/Exp-lookit-dialogue-page.html>`__.
+
+Consider instead
+------------------
+
+- :ref:`exp-lookit-images-audio`, which should be able to do everything this frame can, but more reliably and with more options!
diff --git a/app/components/exp-lookit-geometry-alternation-open/doc.rst b/app/components/exp-lookit-geometry-alternation-open/doc.rst
@@ -0,0 +1,11 @@
+exp-lookit-geometry-alternation-open
+==============================================
+
+This frame is deprecated and will not be included in release 2.x. 
+Please see `the old docs <https://lookit.github.io/lookit-frameplayer-docs/classes/Exp-lookit-geometry-alternation-open.html>`__.
+
+Consider instead
+------------------
+
+The more general-purpose :ref:`exp-lookit-change-detection` frame which shows streams of images on each side, or
+:ref:`exp-lookit-video` if you'd rather provide premade videos.
diff --git a/app/components/exp-lookit-geometry-alternation/doc.rst b/app/components/exp-lookit-geometry-alternation/doc.rst
@@ -0,0 +1,11 @@
+exp-lookit-geometry-alternation
+==============================================
+
+This frame is deprecated and will not be included in release 2.x.
+Please see `the old docs <https://lookit.github.io/lookit-frameplayer-docs/classes/Exp-lookit-geometry-alternation.html>`__.
+
+Consider instead
+------------------
+
+The more general-purpose :ref:`exp-lookit-change-detection` frame which shows streams of images on each side, or
+:ref:`exp-lookit-video` if you'd rather provide premade videos.
diff --git a/app/components/exp-lookit-images-audio/doc.rst b/app/components/exp-lookit-images-audio/doc.rst
@@ -443,7 +443,7 @@ Parameters
         be shown at a delay, or specify times to highlight particular images.
 
         :id: [String]
-            unique ID for this image
+            unique ID for this image. This must not have any spaces or special characters and cannot start with a number.
         :src: [String]
             URL of image source. This can be a full
             URL, or relative to baseDir (see baseDir).

diff --git a/app/components/exp-lookit-preferential-looking/doc.rst b/app/components/exp-lookit-preferential-looking/doc.rst
@@ -0,0 +1,12 @@
+exp-lookit-preferential-looking
+==============================================
+
+This frame is deprecated and will not be included in release 2.x.
+Please see `the old docs <https://lookit.github.io/lookit-frameplayer-docs/classes/Exp-lookit-preferential-looking.html>`__.
+
+
+Consider instead
+------------------
+
+- :ref:`exp-lookit-video` to play a video and optional audio, with more configurability & better timing precision for the recording
+- :ref:`exp-lookit-calibration` to show a calibration stimulus at specific locations, again with more configurability and better timing precision
diff --git a/app/components/exp-lookit-stimuli-preview/doc.rst b/app/components/exp-lookit-stimuli-preview/doc.rst
@@ -1,3 +1,5 @@
+.. _exp-lookit-stimuli-preview:
+
 exp-lookit-stimuli-preview
 ==============================================
 

diff --git a/app/components/exp-lookit-story-page/doc.rst b/app/components/exp-lookit-story-page/doc.rst
@@ -0,0 +1,10 @@
+exp-lookit-story-page
+==============================================
+
+This frame is deprecated and will not be included in release 2.x.
+Please see `the old docs <https://lookit.github.io/lookit-frameplayer-docs/classes/Exp-lookit-story-page.html>`__.
+
+Consider instead
+------------------
+
+- :ref:`exp-lookit-images-audio`, which should be able to do everything this frame can, but more reliably and with more options!
diff --git a/app/components/exp-lookit-webcam-display/doc.rst b/app/components/exp-lookit-webcam-display/doc.rst
@@ -1,3 +1,5 @@
+.. _exp-video-webcam-display:
+
 exp-lookit-webcam-display
 ==============================================
 

diff --git a/app/components/exp-text-block/doc.rst b/app/components/exp-text-block/doc.rst
@@ -6,64 +6,175 @@ exp-text-block
 Overview
 ------------------
 
-This is a small utility for displaying text that is used by a variety of frames. If a parameter says it will be rendered
-using exp-text-block, see below for how to format that parameter.
+This is a small utility for displaying text that a variety of frames use. If the frame documentation said that some
+parameter would be rendered by exp-text-block, or that it should be a list of blocks each to be rendered by exp-text-block,
+you're in the right place to learn how to format that parameter.
 
 Examples
 ----------------
 
-This frame will play through a central video of Kim introducing an apple up to five times. Once the child looks away for more
-than 2 s total, as coded by the parent holding down the P key, it will proceed.
+Single block: title and text
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 .. code:: javascript
 
-    "play-video-five-times": {
-        "kind": "exp-lookit-video-infant-control",
-        "lookawayKey": "p",
-        "lookawayType": "total",
-        "lookawayThreshold": 2,
-        "endTrialKey": "q",
-        "lookawayTone": "noise",
-        "lookawayToneVolume": 0.25,
-
-        "audio": {
-            "loop": false,
-            "source": "peekaboo"
-        },
-        "video": {
-            "top": 10,
-            "left": 25,
-            "loop": true,
-            "width": 50,
-            "source": "cropped_apple"
-        },
-        "backgroundColor": "white",
-        "autoProceed": true,
-        "parentTextBlock": {
-            "text": "If your child needs a break, just press X to pause!"
-        },
-        "requiredDuration": 0,
-        "requireAudioCount": 0,
-        "requireVideoCount": 5,
-        "restartAfterPause": true,
-        "pauseKey": "x",
-        "pauseKeyDescription": "X",
-        "pauseAudio": "pause",
-        "pauseVideo": "attentiongrabber",
-        "pauseText": "(You'll have a moment to turn around again.)",
-        "unpauseAudio": "return_after_pause",
-        "doRecording": true,
-        "baseDir": "https://www.mit.edu/~kimscott/placeholderstimuli/",
-        "audioTypes": [
-            "ogg",
-            "mp3"
-        ],
-        "videoTypes": [
-            "webm",
-            "mp4"
+    "example-text-frame": {
+        "kind": "exp-lookit-text",
+        "blocks": [
+            {
+                "title": "Lorem ipsum",
+                "text": "Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Suscipit adipiscing bibendum est ultricies integer quis auctor. Imperdiet sed euismod nisi porta lorem mollis. Sollicitudin tempor id eu nisl nunc mi. Aliquet lectus proin nibh nisl condimentum. Ac tincidunt vitae semper quis lectus nulla at volutpat. Mauris sit amet massa vitae tortor condimentum lacinia. Tincidunt vitae semper quis lectus nulla at volutpat. Elementum curabitur vitae nunc sed. Pharetra convallis posuere morbi leo."
+            }
+        ]
+    }
+
+.. image:: /../images/Exp-text-block-1.png
+    :alt: Example screenshot of title and text
+
+
+Single block: text and image
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. code:: javascript
+
+    "example-text-frame": {
+        "kind": "exp-lookit-text",
+        "blocks": [
+            {
+                "text": "Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Suscipit adipiscing bibendum est ultricies integer quis auctor. Imperdiet sed euismod nisi porta lorem mollis. Sollicitudin tempor id eu nisl nunc mi. Aliquet lectus proin nibh nisl condimentum. Ac tincidunt vitae semper quis lectus nulla at volutpat.",
+                "image": {
+                    "src": "https://www.mit.edu/~kimscott/placeholderstimuli/img/apple.jpg",
+                    "alt": "Red apple"
+                }
+            }
+        ]
+    }
+
+.. image:: /../images/Exp-text-block-2.png
+    :alt: Example screenshot of text and image
+
+Note that there may be formatting applied to the image based on the particular frame.
+
+Single block: text and listblocks
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. code:: javascript
+
+    "example-text-frame": {
+        "kind": "exp-lookit-text",
+        "blocks": [
+            {
+                "text": "Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.",
+                "listblocks": [
+                    {
+                        "text": "Suscipit adipiscing bibendum est ultricies integer quis auctor."
+                    },
+                    {
+                        "text": "Imperdiet sed euismod nisi porta lorem mollis."
+                    },
+                    {
+                        "text": "Sollicitudin tempor id eu nisl nunc mi."
+                    }
+                ]
+            }
+        ]
+    }
+
+.. image:: /../images/Exp-text-block-3.png
+    :alt: Example screenshot of text and unordered list
+
+Note that there may be formatting applied to the image based on the particular frame.
+
+
+Three blocks
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+In many frames you can specify a list of blocks to be rendered by exp-text-block - here's an example:
+
+.. code:: javascript
+
+    "example-text-frame": {
+        "kind": "exp-lookit-text",
+        "blocks": [
+            {
+                "title": "Lorem ipsum",
+                "text": "Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.",
+                "listblocks": [
+                    {
+                        "text": "Suscipit adipiscing bibendum est ultricies integer quis auctor."
+                    },
+                    {
+                        "text": "Imperdiet sed euismod nisi porta lorem mollis."
+                    },
+                    {
+                        "text": "Sollicitudin tempor id eu nisl nunc mi."
+                    }
+                ]
+            },
+            {
+                "title": "Nulla porttitor",
+                "text": " Nulla porttitor massa id neque aliquam. Ac felis donec et odio pellentesque diam. Nisl vel pretium lectus quam id leo. "
+            },
+            {
+                "image": {
+                    "src": "https://www.mit.edu/~kimscott/placeholderstimuli/img/apple.jpg",
+                    "alt": "Red apple"
+                },
+                "listblocks": [
+                    {
+                        "text": "Est ante in nibh mauris cursus."
+                    },
+                    {
+                        "text": "Ut aliquam purus sit amet luctus venenatis lectus."
+                    },
+                    {
+                        "text": "Cras ornare arcu dui vivamus arcu felis bibendum ut."
+                    }
+                ]
+            }
+        ]
+    }
+
+.. image:: /../images/Exp-text-block-4.png
+    :alt: Example screenshot of three blocks - title, text, and listblocks; title and text; image and listblocks.
+
+Inserting a link
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. code:: javascript
+
+    "example-text-frame": {
+        "kind": "exp-lookit-text",
+        "blocks": [
+            {
+                "title": "Lorem ipsum",
+                "text": "Here is a link to <a href='https://lookit.mit.edu/' target='_blank' rel='noopener'>Lookit</a>."
+            }
         ]
     }
 
 Parameters
 ----------------
 
+All of the following are optional:
+
+.. glossary::
+
+    title [String]
+        Title text to display at the top of this block
+
+    text [String]
+        Main text of this block. You can use `\n` or `<br>` for paragraph breaks. You can use HTML inside the text,
+        for instance to include a link or an image.
+
+        :emph: whether to show this text in bold
+
+    image [Object]
+        Image to display along with this block. Needs two fields:
+
+        :src: URL of image
+        :alt: alt-text for image
+
+    listblocks [Array]
+        A list of items to display in bullet points. Each item is itself rendered with exp-text-block, so it is an
+        object that can have title, text, image, listblocks, etc.