Merge pull request #266 from lookit/feature/225-checkbox-consent

add checkbox consent frame for ManyBabies-AtHome

app/components/exp-lookit-survey-consent/component.js

@@ -0,0 +1,120 @@
+import layout from './template';
+import ExpFrameBaseComponent from '../exp-frame-base/component';
+import Ember from 'ember';
+
+let {
+    $
+} = Ember;
+
+
+/*
+ * A frame to display text-only instructions, etc. to the user.
+ */
+
+export default ExpFrameBaseComponent.extend({
+    type: 'exp-lookit-survey-consent',
+    layout: layout,
+    frameType: 'CONSENT',
+
+    frameSchemaProperties: {
+        showPreviousButton: {
+            type: 'boolean',
+            default: true
+        },
+        multipleChoiceValidationText: {
+            type: 'string',
+            default: '* You must answer this question to participate'
+        },
+        checkboxValidationText: {
+            type: 'string',
+            default: '* You must agree to this item to participate'
+        },
+        formValidationText: {
+            type: 'string',
+            default: 'Some items were missing - please review your answers. If you do not want to participate, you can use the Back button on your browser or close this window.'
+        },
+        items: {
+            type: 'array',
+            items: {
+                type: 'object',
+                kind: {
+                    oneOf: ['multiple-choice', 'checkbox-item', 'text-block'],
+                    type: 'string'
+                }
+            },
+            default: []
+        }
+    },
+
+    meta: {
+        data: {
+            type: 'object',
+            properties: {
+                items: {
+                    type: 'array'
+                }
+            }
+        }
+    },
+
+    showValidation: false,
+
+    validate() {
+        let _this = this;
+        let formValid = true;
+        this.get('items').forEach((item) => {
+            if (['checkbox-item', 'multiple-choice'].includes(item.kind)) {
+                let answer = _this.get(`answer_${item.label}`);
+                Ember.set(item, 'showValidation', !answer);
+                if (!answer) {
+                    formValid = false;
+                }
+            }
+        });
+        this.set('showValidation', !formValid);
+        return formValid;
+    },
+
+    actions: {
+        finish() {
+            let formValid = this.validate();
+            if (formValid) {
+                this.send('next');
+            } else {
+                $('div.exp-lookit-survey-form').scrollTop(0);
+            }
+        }
+    },
+
+    didInsertElement() {
+        let used_labels = [];
+
+        this.get('items').forEach((item, index) => {
+            if (['checkbox-item', 'multiple-choice'].includes(item.kind)) { // Only process labels for questions, not text
+                // Turn the question label into a string, strip out any non-alphanumeric characters, make sure it's unique
+                let proposed_label = String(item.label ? item.label : index);
+                proposed_label = proposed_label.replace(/[^\w]+/g, "");
+                let repeat = 1;
+                while (used_labels.includes(proposed_label)) {
+                    proposed_label = `${proposed_label}_${repeat}`;
+                    repeat += 1;
+                }
+                Ember.set(item, 'label', proposed_label); // Update label in template
+                used_labels.push(proposed_label);
+                switch (item.kind) {
+                case 'checkbox-item':
+                    this.meta.data.properties[`answer_${proposed_label}`] = {type: 'boolean'};
+                    this.set(`answer_${proposed_label}`, false);
+                    Ember.set(item, 'validationText', this.get('checkboxValidationText'));
+                    break;
+                case 'multiple-choice':
+                    this.meta.data.properties[`answer_${proposed_label}`] = {type: 'string'};
+                    this.set(`answer_${proposed_label}`, '');
+                    Ember.set(item, 'validationText', this.get('multipleChoiceValidationText'));
+                    break;
+                }
+            }
+        });
+        this._super(...arguments);
+    }
+});

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

@@ -0,0 +1,153 @@
+.. _exp-lookit-survey-consent:
+
+exp-lookit-survey-consent
+==============================================
+
+Overview
+------------------
+
+A frame to display a survey-style consent form (no video recording) to the participant. Can show blocks of text,
+checkbox items, and multiple-choice questions in any order. Participant must check all checkboxes and answer all
+multiple-choice questions to proceed.
+
+Note: in general, all studies on Lookit should use the :ref:`video consent<exp-lookit-video-consent>` frame for
+consent. This survey frame is provided for rare cases where, for legal reasons, it is not possible to collect video
+consent.
+
+What it looks like
+~~~~~~~~~~~~~~~~~~
+
+.. image:: /../images/Exp-lookit-survey-consent.png
+    :alt: Example screenshot from exp-lookit-survey-consent frame
+
+More general functionality
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Below is information specific to this particular frame. There may also be available parameters, events recorded,
+and data collected that come from the following more general sources:
+
+- the :ref:`base frame<base frame>` (things all frames do)
+
+Examples
+----------------
+
+.. code:: javascript
+
+    "survey-consent": {
+            "kind": "exp-lookit-survey-consent",
+            "title": "Informed Consent Form for Caregivers of Minors (Under 18) \n TITLE OF STUDY",
+            "items": [
+                {
+                    "kind": "text-block",
+                    "text": "Please contact the lead researcher (CONTACT INFO) if you have any questions regarding this form."
+                },
+                {
+                    "kind": "text-block",
+                    "title": "General"
+                },
+                {
+                    "kind": "checkbox-item",
+                    "text": "I confirm I have read and understood the Information Sheet for the above-named study. The information has been fully explained to me and I have been able to contact the researchers with enquiries.",
+                    "label": "read_sheet"
+
+                },
+                {
+                    "kind": "checkbox-item",
+                    "text": "I understand that participation in this study is entirely voluntary, and if I decide that I do not want my child to take part, they can stop taking part in this study at any time without giving a reason.",
+                    "label": "voluntary"
+                },
+                {
+                    "kind": "checkbox-item",
+                    "text": "I understand that I will be receiving a small remuneration of €XXX for participation in this study.",
+                    "label": "compensation"
+                },
+                {
+                    "kind": "checkbox-item",
+                    "text": "I know how to contact the research team if I need to.",
+                    "label": "contact"
+                },
+                {
+                    "kind": "checkbox-item",
+                    "text": "I agree to take part in this research study with my child having been fully informed of the risks, benefits and alternatives which are set out in full in the information leaflet which I have been provided with.",
+                    "label": "fully_informed"
+                },
+                {
+                    "kind": "text-block",
+                    "title": "Data processing"
+                },
+                {
+                    "kind": "checkbox-item",
+                    "text": "I give my permission for my data to be used in line with the aims of the research study, as outlined in the information sheet.",
+                    "label": "use_data"
+                },
+                {
+                    "kind": "checkbox-item",
+                    "text": "I understand that results from analysis of my child’s personal information will not be given to me.",
+                    "label": "no_personal_results"
+                },
+                {
+                    "kind": "checkbox-item",
+                    "text": "I understand that confidentiality may be breached in circumstances in which: <ol><li>The research team has a strong belief or evidence exists that there is a serious risk of harm or danger to either the participant or another individual.  This may relate to issues surrounding physical, emotional and/or sexual abuse, concerns for child protection, rape, self-harm, suicidal intent or criminal activity.</li><li>Disclosure is required as part of a legal process or Garda investigation. In such instances, information may be disclosed to significant others or appropriate third parties without permission being sought.  Where possible, a full explanation will be given to the participant regarding the necessary procedures and also the intended actions that may need to be taken.</li></ol>",
+                    "label": "confidentiality_limits"
+                },
+                {
+                    "kind": "multiple-choice",
+                    "question": "PUBLIC DATABASE: I give permission for my personal data, in the form of webcam recordings to be shared with the scientific community and the general public via a fully open database on the internet. <b>Agreeing to publicly sharing your data is NOT required for participation in this study.</b> This data will be de-identified as much as possible (that is, all efforts will be taken by the research team to remove any identifying features in the footage, and no names, dates of birth, addresses, etc will be provided with the data). I understand that data shared in this way will be accessible to researchers and members of the public anywhere in the world, not just the EEA, and thus may be transferred outside the EEA. I understand that by sharing data in this way, my data might be used for other, future research projects in addition to the study I am currently participating in. Those future projects can focus on any topic and might be completely unrelated to the goals of this study. <br><br>I understand that although the study team may destroy/withdraw the original dataset from the open database, once the data are shared, it cannot be guaranteed that no copy will remain. I understand that it is possible that some of the research conducted using my shared information eventually could lead to the development of new research methods, new diagnostic tests, new drugs, or other commercial products. I understand that should this occur, there is no plan to provide me, the study team, or TCD with any part of the profits generated from such products, nor will I, the study team, or TCD have any ownership rights in the products.",
+                    "answers": [
+                        "Yes",
+                        "No"
+                    ],
+                    "label": "public_database"
+                }
+            ]
+        }
+
+Parameters
+----------------
+
+showPreviousButton [Boolean | ``true``]
+    Whether to show a 'previous' button
+
+blocks [Array]
+    Array of text blocks to display, rendered using :ref:`exp-text-block`.
+
+multipleChoiceValidationText [String | ``'* You must answer this question to participate'``]
+    Text to show beneath multiple choice questions if the user tries to proceed without selecting an option
+
+checkboxValidationText [String | ``'* You must agree to this item to participate'``]
+    Text to show beneath checkbox items if the user tries to proceed without checking the box
+
+items [Array]
+    List of items in the consent form. Each one is an object (enclosed in `{}`). It should have "kind" set to
+    either ``"multiple-choice"``, ``"checkbox-item"``, or ``"text-block"``.
+
+    * If 'kind' is set to ``"text-block"``, the item will be rendered using :ref:`exp-text-block`. It can have fields
+      ``"text"``, ``"title"``, etc.
+    * If 'kind' is set to ``"checkbox-item"``, set ``"text"`` to the text of the question. This can include HTML.
+    * If 'kind' is set to ``"multiple-choice"``, set ``"question"`` to the text of the question (which can include HTML)
+      and ``"answers"`` to a list of possible answers.
+
+    Checkbox and multiple choice items can also have a field ``"label"`` which will be used to label the participant's
+    answer in the data collected. Labels should contain only characters, numbers, and underscores.
+
+
+Data collected
+----------------
+
+The fields added specifically for this frame type are:
+
+answer_<label> [String]
+    The answer to the question with label ``<label>``. E.g., if you set label to ``"public_database"`` the corresponding
+    answer will be called ``answer_public_database``. If a question does not have a label, it will be numbered
+    according to its zero-indexed position in ``items`` (the first item is ``answer_0``, the next is ``answer_1``, etc.)
+
+    For multiple-choice questions, the value of the answer is the same as one of the items in the ``answers`` list.
+    For checkbox questions, the value of a checked box is ``true`` and the value of an unchecked box is ``false``.
+    (You will only see ``true`` values because participants have to check all the boxes to proceed and save their data.)
+
+Events recorded
+----------------
+
+The events recorded specifically by this frame are:
+
+<None>

app/components/exp-lookit-survey-consent/template.hbs

@@ -0,0 +1,55 @@
+<div class="row exp-lookit-survey-consent">
+    <div class="col-md-12 exp-lookit-survey-form">
+        {{#if title}}
+            <p class="exp-text-medium title">{{exp-format title}}</p>
+        {{/if}}
+        {{#bs-form}}
+            {{#each items as |item|}}
+                {{#with (concat "answer_" item.label) as |answer-label|}}
+                    {{#if (eq item.kind "text-block")}}
+                        {{exp-text-block block=item}}
+                    {{else}}
+                        {{#if (eq item.kind "checkbox-item")}}
+                            <label class={{if (and (not (get this answer-label)) showValidation) "text-danger" ""}}>
+                                <div class="checkbox-container">{{input type="checkbox" checked=(get this answer-label) name=answer-label}}</div>
+                                <div class="label-container">{{exp-format item.text}}</div>
+                            </label>
+                        {{else if (eq item.kind "multiple-choice")}}
+                            <label> {{exp-format item.question}} </label>
+                            {{#each item.answers as |answer|}}
+                                <div class={{if (and (not (get this answer-label)) showValidation) "text-danger radio" "radio"}}>
+                                    <label>
+                                        {{radio-button value=answer checked=(get this answer-label) name=answer-label}}
+                                        {{answer}}
+                                    </label>
+                                </div>
+                            {{/each}}
+                        {{/if}}
+                        {{#if (and (not (get this answer-label)) showValidation)}}
+                            <p class="text text-danger"> {{exp-format item.validationText}} </p>
+                        {{/if}}
+                    {{/if}}
+                {{/with}}
+            {{/each}}
+        {{/bs-form}}
+    </div>
+</div>
+
+<div class="row exp-controls exp-lookit-survey-consent">
+    {{#if showValidation}}
+        <p class="text text-danger pull-right form-validation"> {{exp-format formValidationText}} </p>
+    {{/if}}
+</div>
+
+<div class="row exp-controls exp-lookit-survey-consent">
+    <div class="col-md-12">
+        {{#if showPreviousButton}}
+            <button type="button" class="btn btn-default pull-left" {{ action "previous" }}>
+                {{ t "Previous" }}
+            </button>
+        {{/if}}
+        <button type="button" id="nextbutton" class="btn btn-success pull-right" {{ action "finish" }}>
+            {{ t "Submit" }}
+        </button>
+    </div>
+</div>

app/index.rst

@@ -62,6 +62,7 @@ The documentation will tell you how each frame works, what data it collects, and
    components/exp-lookit-stimuli-preview/doc.rst
    components/exp-lookit-stop-recording/doc.rst
    components/exp-lookit-survey/doc.rst
+   components/exp-lookit-survey-consent/doc.rst
    components/exp-lookit-text/doc.rst
    components/exp-lookit-video/doc.rst
    components/exp-lookit-video-assent/doc.rst

app/styles/app.scss

@@ -23,6 +23,7 @@
 @import "components/exp-lookit-calibration";
 @import "components/exp-lookit-start-stop-recording";
 @import "components/exp-lookit-instruction-video";
+@import "components/exp-lookit-survey-consent";
 
 #experiment-player {
     font-size: large;

app/styles/components/exp-lookit-survey-consent.scss

@@ -0,0 +1,51 @@
+.exp-lookit-survey-consent {
+
+    max-width: 800px;
+    margin-left: auto !important;
+    margin-right: auto !important;
+    display: block;
+
+    label {
+        width: 100%;
+        font-weight: normal;
+    }
+
+    .checkbox-container {
+        display: inline-block;
+        width: 5%;
+    }
+
+    p.text-danger {
+        margin-left: 5%;
+        font-weight: bold;
+
+        &.form-validation {
+            width: 75%;
+            text-align: right;
+        }
+    }
+
+    .radio {
+        margin-left: 5%;
+    }
+
+    .label-container {
+        font-weight: normal;
+        display: inline-block;
+        width: 90%;
+        vertical-align: top;
+    }
+
+    .exp-lookit-survey-form {
+        margin-top: 5vh;
+        margin-bottom: 5vh;
+        padding: 0;
+        height: 80vh;
+        overflow-y: auto;
+    }
+
+    p.title {
+        text-align: center;
+    }
+
+}