2 How Tos🔗

2.1 How to add a new study🔗

The simplest case is when you add a new study from a package that is not yet installed. In that case, define the new study and provide it: say the file that provides it is "package/new-studies.rkt" and the name of the new study is test-study. Then in the "info.rkt" file for the package, include the following:

(define congame-studies

'((the-package/new-studies test-study)))

You then should install this new package, and upon the next launch, congame should pick up this new study.

If this does not work, you may have to remove the "compiled" folder in "congame-web/studies/" so that the cache (which contains the installed studies) gets refreshed.

To add a new study from an already installed package, you should update the "info.rkt" file of the package, recompile the package via raco setup <package-name>, and then refresh the cache.

2.2 How to bulk archive study instances🔗

If you create lots of study instances, your dashboard may get cluttered with all the study instances. To archive them, click on “Admin” and then on “Bulk Archive”. This brings up a multi-select, that lists in bold all your studies followed by the active study instances for this type of study. You can then select all the instances you want to archive (hold Ctrl or Cmd before clicking to select several), and then on “Archive”.

2.3 How to pass values from a substudy to its caller🔗

When running a study with make-step/study, then the values put can not be retrieved anywhere with get except in this substudy. To pass some variables up to the calling study, we can use the #:provides mechanism. For example, consider the following block of code from "congame-example-study/multi-review":

(define (submit-research-ideas [n 2])

; ...

(make-study

"research-ideas-study"

#:requires '()

#:provides '(research-ideas)

(list

(make-step 'initialize initialize next-or-done/transition)

(make-step 'submit-research-idea submit-research-idea next-or-done/transition))))

(define (review-study)

(make-study

"review-study"

#:requires '()

#:provides '()

(list

(make-step/study

'submit

(submit-research-ideas)

#:provide-bindings '([submission research-ideas]))

(make-step 'update-submissions update-submissions)

(make-step 'lobby lobby)

(make-step 'review-1 review)

(make-step 'review-2 review)

(make-step 'final final))))

The study submit-research-ideas puts a value with the key 'research-ideas, which it provides via #:provides '(research-ideas). This means that this value can be used by the parent study, if so desired. The parent study turns the study into a substudy via (make-step/study 'submit submit-research-ideas) #:provide-bindings '([submission research-ideas]). The magic happens in #:provide-bindings '([submissions research-ideas]), which means that the value of key 'research-ideas for the substudy should be made available (via put) to the parent study under the key 'submission. If the parent study did not want to use the provided value, then it can do so by providing an empty list of #:provide-bindings.

2.4 Scheduling tasks at most once🔗

See "omnitrack/track-physical.rkt" for an example.

Within a step and before the page form is used, compute a unique random value – the nonce – store it in the step scope, and call your desired task with that nonce and the participant id as arguments. When the task runs, it should look up the nonce from step scope and, if it matches, perform its duties and then remove the nonce. Otherwise, it should do nothing.

2.5 Conscript Style Guide🔗