4.4.1 Studies and Steps
| (require congame/components/study) | package: congame-core |
procedure
(make-study name steps [ #:requires requires #:provides provides #:transitions transitions #:view-handler view-handler #:failure-handler failure-handler]) → study? name : string? steps : (listof step?) requires : (listof symbol?) = null provides : (listof symbol?) = null transitions : (or/c #f (hash/c symbol? any/c)) = #f view-handler : (or/c #f (-> request? response?)) = #f failure-handler : (or/c #f (-> step? any/c step-id/c)) = #f
The #:transitions argument has to be a transition-graph that provides all the transitions between the steps. See transition-graph for details.
procedure
s : study? req : request? = (current-request) bindings : (hash/c symbol? any/c) = (hasheq)
4.4.1.1 Steps
procedure
(make-step id handler [ transition #:view-handler view-handler #:for-bot bot-handler]) → step? id : symbol? handler : (-> step-page?) transition : transition/c = (lambda () next) view-handler : (or/c #f (-> request? response?)) = #f bot-handler : (or/c #f procedure?) = #f
procedure
(make-step/study id s [ transition #:require-bindings require-bindings #:provide-bindings provide-bindings]) → step? id : symbol? s : study? transition : transition/c = (lambda () next) require-bindings : (listof binding/c) = null provide-bindings : (listof binding/c) = null
The #:require-bindings argument maps identifiers required by s to identifiers available in the current study context if the name is different – otherwise it assumes that required identifers share names and attempts to set them accordingly.
The #:provide-bindings argument maps identifiers in the current study that should be mapped to some subset of the identifiers provided by s upon completion. When #:provide-bindings is null?, no values are assigned.
For example:
(make-step/study 'required-tasks task-study #:require-bindings '([n task-treatment]) #:provide-bindings '([root-success? success?]))
Here, n in task-study will take on the value of task-treatment, and after running, root-success? will be assigned the value of success? in the parent.
procedure
(step-page? v) → boolean?
v : any/c
syntax
(page maybe-validator expr ...+)
maybe-validator =
| #:validator validator-expr
validator-expr : (-> any/c xexpr?)
For example:
(define (step-with-setup-and-form) (perform-a-once) (perform-b-once) (page (begin (perform-c-again) (haml (:h1 "The Form") ;; some form ;; ... ))))
When the user lands on step-with-setup-and-form the first time, resumes there, or refreshes the page, perform-a-once and perform-b-once will be called. If the user submits the form and it fails validation, the page will be reloaded showing the error messages and the fields filled with the inputs that were valid. However, neither perform-a-once nor perform-b-once will be run again, while perform-c-again will be run again.
It is possible to pass a custom validator for xexprs to page to provide better error messages.
4.4.1.2 Step Widgets
procedure
(button action label [ #:id id #:to-step-id to-step-id]) → xexpr? action : (-> void?) label : xexpr? id : string? = "" to-step-id : (or/c #f symbol?) = #f
The #:id argument is useful for identifying the button within bot handlers.
procedure
(form f action render [ #:id id #:enctype enctype]) → xexpr? f : form? action : (-> void?) render : (-> (widget-renderer/c) xexpr?) id : string? = "" enctype : string? = "multipart/form-data"
The #:id argument is the same as for button.