add info on restrictions on frame IDs and some tips on survey frames (#…

…185)

app/components/exp-lookit-survey/doc.rst

@@ -44,14 +44,6 @@ may be specified under options to populate a question's potential answers (e.g.,
 load a list of countries from some other source rather than hard-coding it, or to
 provide checkboxes with vocabulary items from an externally-defined inventory).
 
-You can also use alpacajs's "dependencies" and "conditional dependencies" functionality to
-set up fields that depend on other fields - e.g., asking if the child speaks any
-language besides English in the home and only if so displaying a dropdown to select the
-language(s), or asking if the child likes Elmo or Grover better and then asking a question
-specific to the preferred character. Or if you have questions only relevant to the
-birth mother of the child, you could ask if the participant is the birth mother and show
-those questions conditionally.
-
 Formatting
 ~~~~~~~~~~~
 
@@ -61,6 +53,33 @@ elements, and inline CSS.
 The form itself occupies a maximum of 800px horizontally and takes up 80% of the vertical
 height of the window (it will scroll to fit).
 
+Conditional questions
+~~~~~~~~~~~~~~~~~~~~~~
+
+You can use `alpacajs's "dependencies" functionality <http://www.alpacajs.org/docs/api/conditional-dependencies.html>`__ to
+set up fields that depend on other fields - e.g., asking if the child speaks any
+language besides English in the home and only if so displaying a dropdown to select the
+language(s), or asking if the child likes Elmo or Grover better and then asking a question
+specific to the preferred character. Or if you have questions only relevant to the
+birth mother of the child, you could ask if the participant is the birth mother and show
+those questions conditionally. See below for an example.
+
+
+
+
+Ordering questions
+~~~~~~~~~~~~~~~~~~
+
+By default, questions should be presented in the order they're defined in your schema.
+If they are not, you can use the "order" option to arrange them; see `the Alpaca docs <http://www.alpacajs.org/docs/api/ordering.html>`__.
+
+Ordering options
+~~~~~~~~~~~~~~~~
+
+By default, Alpaca sorts options alphabetically for fields with radio buttons or checkboxes.
+That's usually not what you want. Add ``"sort": false`` under formSchema -> options ->
+fields -> <your field> to list them in the order you define them.
+
 Current limitations
 ~~~~~~~~~~~~~~~~~~~
 
@@ -135,14 +154,70 @@ Here is an example of a reasonably simple survey using this frame:
                     "species": {
                         "type": "radio",
                         "message": "Seriously, what species??",
-                        "validator": "required-field"
+                        "validator": "required-field",
+                        "removeDefaultNone": true,
+                        "sort": false
                     }
                 }
             }
         },
         "nextButtonText": "Moving on..."
     }
 
+Conditional dependence: show a question based on the answer to another question
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. code:: javascript
+
+    "language-survey": {
+        "kind": "exp-lookit-survey",
+        "formSchema": {
+            "schema": {
+                "type": "object",
+                "properties": {
+                    "multilingual": {
+                        "type": "string",
+                        "title": "Is your child regularly exposed to any languages besides English?",
+                        "enum": [
+                            "Yes",
+                            "No"
+                        ]
+                    },
+                    "languages": {
+                        "type": "text",
+                        "title": "What other languages is he or she learning?"
+                    }
+                },
+                "dependencies": {
+                    "languages": [
+                        "multilingual"
+                    ]
+                }
+            },
+            "options": {
+                "fields": {
+                    "multilingual": {
+                        "type": "radio",
+                        "message": "Please select an answer",
+                        "validator": "required-field",
+                        "sort": false,
+                        "removeDefaultNone": true,
+                        "order": 1
+                    },
+                    "languages": {
+                        "type": "text",
+                        "message": "Please write in an answer",
+                        "validator": "required-field",
+                        "dependencies": {
+                            "multilingual": "Yes"
+                        },
+                        "order": 2
+                    }
+                }
+            }
+        }
+    }
+
 Reproducing the mood survey
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
@@ -577,4 +652,4 @@ formData [Object]
 Events recorded
 ----------------
 
-No events are recorded specifically by this frame.
+No events are recorded specifically by this frame.

app/utils/protocol.rst

@@ -3,7 +3,7 @@
 Protocol configuration
 ===================================
 
-Researchers specify how their Lookit study works by writing a "protocol configuration" for their study. This configuration is written in JSON, which stands for JavaScript Object Notation - this is just a special text format, not code. 
+Researchers specify how their Lookit study works by writing a "protocol configuration" for their study. This configuration is written in JSON, which stands for JavaScript Object Notation - this is just a special text format, not code.
 
 Your study protocol configuration tells the Lookit experiment runner what sequence of "frames" to use in your study, and set all the options for those frames like what pictures or videos to show and for how long.
 
@@ -20,7 +20,7 @@ human-readable text format for describing data. A JSON object is an unordered se
 - A key and value are separated by a colon.
 - Key-value pairs are separated by commas.
 
-A JSON value can be any of the following: 
+A JSON value can be any of the following:
 
 - a string (enclosed in double quotes)
 - a number
@@ -66,16 +66,24 @@ Study protocol structure
 --------------------------
 
 Studies on Lookit are broken into a set of fundamental units called
-**frames**, which can also be thought of as “pages” of the study. A
+**frames**, which can also be thought of as "pages" of the study. A
 single experimental trial (e.g. looking time measurement) would
-generally be one frame, as are the video consent procedure and exit survey. 
+generally be one frame, as are the video consent procedure and exit survey.
 Your JSON must have two keys: ``frames`` and
 ``sequence``. The ``frames`` value defines the frames used in this
 study: it must be a JSON object mapping frame nicknames (any unique
 strings chosen by the researcher) to frame objects (defined next). The
 ``sequence`` value must be an ordered list of the frames to use in this
-study; values in this list must be frame nicknames from the “frames”
-value. 
+study. Values in this list must be IDs from the “frames”
+value.
+
+.. admonition:: Frame IDs can't have underscores in them
+
+   Frame IDs must be made of only numbers, letters, and dashes (e.g., "motor-skills-survey-23" is fine, but "motor_skills_survey" is not).
+
+   You will see an error in the browser console if you try to use a frame ID with an underscore in it!
+
+   Frame IDs **also can't end with** ``-repeat-N`` (e.g., '-repeat-3'), because that suffix is used when the participant navigates back to repeat a frame.
 
 Here is the JSON for a very minimal Lookit study:
 
@@ -135,4 +143,4 @@ included in a study – for instance, test trials using different stimuli.
 The separation of frame definitions and sequence allows researchers to
 easily and flexibly edit and test study protocols – for instance, the
 order of frames may be altered or a particular frame removed for testing
-purposes without altering any frame definitions.
+purposes without altering any frame definitions.