Skip to content

Commit 3c1b09f

Browse files
gureckisgureckis
committed
docs: update to builtins documentation
1 parent 36cd7fd commit 3c1b09f

1 file changed

Lines changed: 64 additions & 62 deletions

File tree

‎docs/coding/views.md‎

Lines changed: 64 additions & 62 deletions
Original file line numberDiff line numberDiff line change
@@ -204,21 +204,20 @@ and more information can be found
204204

205205
## Overview of Built-in Views
206206

207-
| Name | Props | Description |
208-
| --------------------------------------------------- | :---- | :---------------------------------------------------------------------------------------------------------------------------------------- |
209-
| [Recruitment Ad](#recruitment-advertisement) | No | Landing page for participants |
210-
| [MTurk Ad](#mturk-recruitment) | Yes | Interacts with the MTurk system |
211-
| [Simple Informed Consent](#simple-informed-consent) | Yes | Collects informed consent using a simple checkbox |
212-
| [Window Sizer](#window-sizer) | Yes | Verifies a given area of the screen is visible (with a more aggressive option that hides page content if the window is resized too small) |
213-
| [Simple Instructions](#simple-instructions) | No | A simple sequence of pages for instructions |
214-
| [Instructions Quiz](#instructions-quiz) | No | A basic instructions quiz |
215-
| [Demographic Survey](#demographic-survey) | Yes | A survey which collects some demographic info |
216-
| [Device Survey](#device-survey) | No | A survey which collects some self-report about computer/device |
217-
| [Withdraw](#withdraw) | Yes | A survey which processes a participant's request to withdraw from study |
218-
| [Debrief](#debrief) | No | A simple text View which describes the purpose of study |
219-
| [Feedback](#feedback) | No | A survey for soliciting structured and unstructured feedback on the study |
220-
| [Thanks Page](#thanks) | Yes | A thank you page |
221-
| [Report Issue](#report-issue) | Yes | A form to report a bug/issue with the experiment |
207+
| Name | Props | Description |
208+
| -------------------------------------------- | :---- | :---------------------------------------------------------------------------------------------------------------------------------------- |
209+
| [Recruitment Ad](#recruitment-advertisement) | No | Landing page for participants |
210+
| [MTurk Ad](#mturk-recruitment) | Yes | Interacts with the MTurk system |
211+
| [Informed Consent](#simple-informed-consent) | Yes | Collects informed consent using a simple checkbox |
212+
| [Window Sizer](#window-sizer) | Yes | Verifies a given area of the screen is visible (with a more aggressive option that hides page content if the window is resized too small) |
213+
| [Simple Instructions](#simple-instructions) | No | A simple sequence of pages for instructions |
214+
| [Instructions Quiz](#instructions-quiz) | Yes | A basic instructions quiz |
215+
| [Demographic Survey](#demographic-survey) | No | A survey which collects some demographic info |
216+
| [Device Survey](#device-survey) | No | A survey which collects some self-report about computer/device |
217+
| [Withdraw](#withdraw) | No | A survey which processes a participant's request to withdraw from study |
218+
| [Debrief](#debrief) | Yes | A simple text View which describes the purpose of study |
219+
| [Feedback](#feedback) | No | A survey for soliciting structured and unstructured feedback on the study |
220+
| [Thanks Page](#thanks) | No | A thank you page |
222221

223222
These components are located in the `src/builtins` directory. In <SmileText/> a
224223
short-hand for the src folder is '@' so for instance '@/builtins' refers to the
@@ -240,7 +239,6 @@ Advertisement View is a simple page that contains a title and an invitation to
240239
participate. There is a animated button which will take the participant to the
241240
next View in the timeline.
242241

243-
- There are no side effects, and nothing is recorded.
244242
- The template can be edited to change the text.
245243
- The logo image imports from `@/user/assets/brain.svg`.
246244

@@ -337,13 +335,12 @@ this.registerView({
337335
})
338336
```
339337

340-
### Simple Informed Consent
338+
### Informed Consent
341339

342340
**Base Component**: `@/builtins/informedConsent/InformedConsentView.vue`
343341
**Code**: [source](https://github.com/NYUCCL/smile/blob/main/src/builtins/informedConsent/InformedConsentView.vue)
344-
**Side
345-
effects**: Sets the `consent` key in the `localStorage` to `true.`
346-
**Typical accessibility**: `{requiresConsent: false, requiresDone: false}`
342+
**Typical
343+
accessibility**: `{requiresConsent: false, requiresDone: false}`
347344

348345
Most studies require some type of informed consent from participants. This is
349346
usually a short piece of text describing the study and the participant's rights
@@ -381,9 +378,8 @@ timeline.pushSeqView({
381378

382379
**Base Component**: `@/builtins/windowSizer/WindowSizerView.vue`
383380
**Code**: [source](https://github.com/NYUCCL/smile/blob/main/src/builtins/windowSizer/WindowSizerView.vue)
384-
**Side
385-
effects**: Yes, sets the is verifiedVisibility key in the [API](/api) to true.
386-
**Typical accessibility**: `{requiresConsent: true, requiresDone: false}`
381+
**Typical
382+
accessibility**: `{requiresConsent: true, requiresDone: false}`
387383

388384
The window sizer is a small component
389385
`src/builtins/windowSizer/WindowSizerView.vue` that will display a box with a
@@ -429,9 +425,8 @@ if they do not pass the instructions quiz.
429425

430426
**Base Component**: `@/builtins/instructions/InstructionsView.vue`
431427
**Code**: [source](https://github.com/NYUCCL/smile/blob/main/src/builtins/instructions/InstructionsView.vue)
432-
**Side
433-
effects**: None **Typical accessibility**:
434-
`{requiresConsent: true, requiresDone: false}`
428+
**Typical
429+
accessibility**: `{requiresConsent: true, requiresDone: false}`
435430

436431
[TO DO: Add info about instructions]
437432

@@ -459,9 +454,10 @@ timeline.pushSeqView({
459454

460455
### Instructions Quiz
461456

462-
**Component**: `@/builtins/instructionsQuiz/InstructionsQuiz.vue`
463-
**Side effects**: Saves the data from the quiz
464-
**Typical accessibility**: Always
457+
**Base Component**: `@/builtins/instructionsQuiz/InstructionsQuiz.vue`
458+
**Code**: [source](https://github.com/NYUCCL/smile/blob/main/src/builtins/instructionsQuiz/InstructionsQuiz.vue)
459+
**Typical
460+
accessibility**: `{requiresConsent: true, requiresDone: false}`
465461

466462
The instructions quiz is a simple quiz that makes sure the participant has read
467463
and understood the experiment instructions. The user has to answer all the
@@ -529,15 +525,15 @@ questions will be randomized in the same way each time the quiz is taken.
529525

530526
```js
531527
// import the quiz questions
532-
import { QUIZ_QUESTIONS } from '/coding/components/quizQuestions'
528+
import { QUIZ_QUESTIONS } from './components/quizQuestions'
533529
// instructions quiz
534530
timeline.pushSeqView({
535531
name: 'quiz',
536532
component: InstructionsQuiz,
537533
props: {
538-
quizQuestions: QUIZ_QUESTIONS,
534+
questions: QUIZ_QUESTIONS,
539535
returnTo: 'instructions',
540-
randomizeQuestionsAndAnswers: true,
536+
randomizeQandA: true,
541537
},
542538
})
543539
```
@@ -546,16 +542,15 @@ timeline.pushSeqView({
546542

547543
**Base Component**: `@/builtins/demographicSurvey/DemographicSurveyView.vue`
548544
**Code**: [source](https://github.com/NYUCCL/smile/blob/main/src/builtins/demographicSurvey/DemographicSurveyView.vue)
549-
**Side
550-
effects**: Yes, saves the data from the form.
551-
**Typical accessibility**: `{requiresConsent: true, requiresDone: false}`
545+
**Typical
546+
accessibility**: `{requiresConsent: true, requiresDone: false}`
552547

553548
The demographic survey is a simple survey that asks participants to provide some
554549
information about themselves. This is important for many reasons. For example,
555550
it is often important to report information about the demographics of the
556551
participants in a study (age, gender, country, primary language, etc...). In
557552
addition, it is useful to know if a subject is color blind in case the studies
558-
relies on color information. The demongr
553+
relies on color information.
559554

560555
```js
561556
// put this at the top of the file
@@ -572,9 +567,8 @@ timeline.pushSeqView({
572567

573568
**Base Component**: `@/builtins/deviceSurvey/DeviceSurveyView.vue`
574569
**Code**: [source](https://github.com/NYUCCL/smile/blob/main/src/builtins/deviceSurvey/DeviceSurveyView.vue)
575-
**Side
576-
effects**: Yes, saves the data from the form.
577-
**Typical accessibility**: `{requiresConsent: true, requiresDone: false}`
570+
**Typical
571+
accessibility**: `{requiresConsent: true, requiresDone: false}`
578572

579573
The device survey askes participants to provide some information about their
580574
computer/tablet/etc... This is important because sometimes the information
@@ -613,11 +607,10 @@ timeline.pushSeqView({
613607

614608
### Withdraw
615609

616-
**Component**: `@/builtins/withdraw/WithdrawView.vue`
610+
**Base Component**: `@/builtins/withdraw/WithdrawView.vue`
617611
**Code**: [source](https://github.com/NYUCCL/smile/blob/main/src/builtins/withdraw/WithdrawView.vue)
618-
**Side
619-
effects**: Sets the `consent` key in the `localStorage` to `true.`
620-
**Typical accessibility**: `{ requiresWithdraw: true }`
612+
**Typical
613+
accessibility**: `{ requiresWithdraw: true }`
621614

622615
As part of most IRB protocols, participants should be able to withdraw from a
623616
study at any time for any reason. Online, this is as simple as closing the
@@ -654,10 +647,10 @@ timeline.registerView({
654647

655648
### Debrief
656649

657-
**Component**: `@/builtins/debrief/DebriefView.vue`
650+
**Base Component**: `@/builtins/debrief/DebriefView.vue`
658651
**Code**: [source](https://github.com/NYUCCL/smile/blob/main/src/builtins/debrief/DebriefView.vue)
659-
**Side
660-
effects**: None **Typical accessibility**: Always
652+
**Typical
653+
accessibility**: `{requiresConsent: true, requiresDone: false}`
661654

662655
The debrief page displays the text that explains the purpose of the experiment
663656
and provides the participant with any additional postfacto information about the
@@ -682,11 +675,10 @@ timeline.pushSeqView({
682675

683676
### Thanks
684677

685-
**Component**: `@/builtins/thanks/ThanksView.vue`
678+
**Base Component**: `@/builtins/thanks/ThanksView.vue`
686679
**Code**: [source](https://github.com/NYUCCL/smile/blob/main/src/builtins/thanks/ThanksView.vue)
687-
**Side
688-
effects**: Yes, saves the data from the form.
689-
**Typical accessibility**: `{requiresDone: true}`
680+
**Typical
681+
accessibility**: `{requiresDone: true}`
690682

691683
```js
692684
// put this at the top of the file
@@ -705,11 +697,10 @@ timeline.pushSeqView({
705697

706698
### Feedback Survey
707699

708-
**Component**: `src/builtins/taskFeedbackSurvey/TaskFeedbackSurveyView.vue`
700+
**Base Component**: `@/builtins/taskFeedbackSurvey/TaskFeedbackSurveyView.vue`
709701
**Code**: [source](https://github.com/NYUCCL/smile/blob/main/src/builtins/taskFeedbackSurvey/TaskFeedbackSurveyView.vue)
710-
**Side
711-
effects**: Yes, saves the data from the form.
712-
**Typical accessibility**: `{requiresConsent: true, requiresDone: false}`
702+
**Typical
703+
accessibility**: `{requiresConsent: true, requiresDone: false}`
713704

714705
The task survey asks some simple questions about the participant's experience in
715706
the task. The questions gauge how enjoyable and challenging the task was and
@@ -731,10 +722,6 @@ timeline.pushSeqView({
731722
})
732723
```
733724

734-
### Report Issue
735-
736-
Coming soon
737-
738725
## Navbars and Modals
739726

740727
In addition to these builtin Views, <SmileText/> also provides a few components
@@ -756,9 +743,24 @@ them as needed for your study.
756743
**Base Component**: `@/builtins/statusBar/StatusBar.vue`
757744
**Code**: [source](https://github.com/NYUCCL/smile/blob/main/src/builtins/statusBar/StatusBar.vue)
758745

746+
The Status Bar is a persistent navigation component that appears at the top of
747+
every view throughout the experiment. It provides essential study information
748+
and participant controls that are always accessible such as the lab logo
749+
(`src/user/assets/universitylogo.png`), the study code name, version information
750+
(i.e., the git commit hash for debugging purposes, along with the current mode
751+
(development, testing, presentation)), a shortened user ID. It also provides two
752+
buttons (After the user consents) which allow users to review the informed
753+
consent information, or to withdraw from the study. The Status Bar automatically
754+
adapts to different screen sizes, showing abbreviated labels on smaller screens
755+
and hiding certain information on very narrow displays.
756+
759757
### Withdraw Modal
760758

761-
**Base Component**: `@/builtins/withdraw/WithdrawFormModal.vue`
762-
**Code**: [source](https://github.com/NYUCCL/smile/blob/main/src/builtins/withdraw/WithdrawFormModal)
763-
**Side
764-
effects**: Yes
759+
**Base Component**: `@/builtins/withdraw/WithdrawModal.vue`
760+
**Code**: [source](https://github.com/NYUCCL/smile/blob/main/src/builtins/withdraw/WithdrawModal.vue)
761+
762+
The Withdraw Modal is a form that appears when participants click the "Withdraw"
763+
button in the Status Bar. It provides a structured way for participants to
764+
withdraw from the study while collecting valuable feedback about their
765+
experience. It is optional for users to complete but otherwise is automatically
766+
saved in the data store.

0 commit comments

Comments
 (0)