6.2.2 Formular: forms and fields

6.2.2 Formular: forms and fields🔗

(require congame/components/formular)
	package: congame-core

A field is a special value that, when used inside a study form, renders as an input element. When the user submits the form, the field yields whatever value the user has entered as a Racket value.

procedure
(formular-field? v) → boolean?
v : any/c

Returns #t if v is a field, #f otherwise.

procedure
(formular-autofill bot-id) → void?
bot-id : any/c

⏳Autofills elements on the page for the bot with bot-id.

procedure
(input-list fields) → formular-field?
fields : (listof formular-field?)

Returns a field that is a collection of fields, and which will provide all values in fields as a single list when the form is submitted.

For example, the following code creates two input-number fields:

(set! myvals (input-list (list (input-number) (input-number))))

When the user enters two numeric values (say, -3 and 9) and submits the form, myvals will contain '(-3 9).

procedure
(input-number [ label
#:min min
#:max max
#:step step
#:required? req]
#:validators validators
[ #:attributes attribs]) → formular-field?
  label : (or/c #f string?) = #f
  min : real? = -inf.0
  max : real? = +inf.0
  step : integer? = 1
  req : (or/c string? boolean?) = #t
  validators : '()
  attribs : (listof (list/c symbol? string?)) = '()
procedure
(input-range [ label
#:min min
#:max max
#:step step
#:required? req]
#:validators validators
[ #:attributes attribs]) → formular-field?
  label : (or/c #f string?) = #f
  min : real? = -inf.0
  max : real? = +inf.0
  step : integer? = 1
  req : (or/c string? boolean?) = #t
  validators : '()
  attribs : (listof (list/c symbol? string?)) = '()

Returns a field that ensures its input is numeric and falls between min and max (inclusive). Use input-number field to get a textbox with spinner arrow buttons for incrementing/decrementing the value, or input-range to get a horizontal slider.

If step is provided, then using the stepper arrows or slider will increase or decrease the value by that amount (though the value is not guaranteed to be a multiple of step).

If required? is not #f, the field must contain data before the form can be submitted.

procedure
(checkbox label
[ #:required? required?
#:attributes attrs]) → formular-field?
  label : (or/c #f string?)
  required? : any/c = #t
  attrs : (listof (list/c symbol? string?)) = null

Returns a field that renders as a single checkbox. If required? is not #f, the checkbox must be selected before the form can be submitted. Any attrs will be used as HTML attributes in the checkbox’s <input> tag.

procedure
(input-text [ label
#:required? req]
#:validators validators
[ #:attributes attrs]) → formular-field?
  label : (or/c #f string?) = #f
  req : (or/c string? boolean?) = #t
  validators : '()
  attrs : (listof (list/c symbol? string?)) = '()

Returns a field that renders as a single-line text input. If required? is not #f, the checkbox must be selected before the form can be submitted. Any attrs will be used as HTML attributes in the text box’s <input> tag.

procedure
(textarea label
[ #:required? req]
#:validators validators
[ #:attributes attrs]) → formular-field?
  label : (or/c #f string?)
  req : (or/c string? boolean?) = #t
  validators : '()
  attrs : (listof (list/c symbol? string?)) = '()

Returns a field that renders as a multi-line text input area. If required? is not #f, the text box must contain text before the form can be submitted. Any attrs will be used as HTML attributes in the field’s <input> tag.

Use attrs to specify the size of the text box in rows and columns:

(textarea "Label" #:attributes '((rows "5") (cols "33")))

procedure
(input-date label
[ #:required? req]
#:validators validators
[ #:attributes attrs]) → formular-field?
  label : (or/c #f string?)
  req : (or/c string? boolean?) = #t
  validators : '()
  attrs : (listof (list/c symbol? string?)) = '()
procedure
(input-time label
[ #:required? req]
#:validators validators
[ #:attributes attrs]) → formular-field?
  label : (or/c #f string?)
  req : (or/c string? boolean?) = #t
  validators : '()
  attrs : (listof (list/c symbol? string?)) = '()

Return fields for entering date and time values, respectively.

Date values are returned in strings of the form "yyyy-mm-dd". Time values are returned as strings of the form "hh:mm" (24-hour format).

If required? is not #f, the field must contain text before the form can be submitted. Any attrs will be used as HTML attributes in the field’s <input> tag.

syntax
(input-file arg)

arg : any/c

input-file form

syntax
(make-checkboxes arg)

arg : any/c

make-checkboxes form

syntax
(make-radios arg)

arg : any/c

make-radios form

syntax
(make-radios-with-other arg)

arg : any/c

make-radios-with-other form

syntax
(make-sliders arg)

arg : any/c

make-sliders form

syntax
(select/inline arg)

arg : any/c

select/inline form

procedure
(map-result arg) → any/c
arg : any/c

map-result proc

syntax
(map-result* arg)

arg : any/c

map-result* form

}

6.2.2.1 Form tools🔗

(require (submod congame/components/formular tools))

value
submit-button : xexpr?
procedure
(submit-button/label label) → xexpr?
label : string?

Returns a representation of an HTML button that submits a form. The label argument is used as the button’s label.

contents ← prev up next →

1	Introduction: a quick tour using Conscript
2	Installing Congame and Conscript
3	Overview
4	Conscript
5	The Congame Server
6	Module Reference
7	(Original Docs)

6.1	Conscript Reference
6.2	Congame Reference

6.2.1	Studies and Steps
6.2.2	Formular: forms and fields
6.2.3	Transition Graphs
6.2.4	Bots