From c2fec171f4027446aece3eee63db616214207548 Mon Sep 17 00:00:00 2001 From: Kim Scott Date: Sat, 21 Nov 2020 12:53:08 -0500 Subject: [PATCH] add info on restrictions on frame IDs and some tips on survey frames (#184) --- app/components/exp-lookit-survey/doc.rst | 95 +++++++++++++++++++++--- app/utils/protocol.rst | 22 ++++-- 2 files changed, 100 insertions(+), 17 deletions(-) diff --git a/app/components/exp-lookit-survey/doc.rst b/app/components/exp-lookit-survey/doc.rst index d9383c8b..01b8dd66 100644 --- a/app/components/exp-lookit-survey/doc.rst +++ b/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 `__ 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 `__. + +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 -> to list them in the order you define them. + Current limitations ~~~~~~~~~~~~~~~~~~~ @@ -135,7 +154,9 @@ 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 } } } @@ -143,6 +164,60 @@ Here is an example of a reasonably simple survey using this frame: "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 newline at end of file +No events are recorded specifically by this frame. diff --git a/app/utils/protocol.rst b/app/utils/protocol.rst index 2c8e5db8..8b10efc3 100644 --- a/app/utils/protocol.rst +++ b/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. \ No newline at end of file +purposes without altering any frame definitions.