doc.gno

 1// Package forms is a Google-Forms-shaped questionnaire realm: publish a form,
 2// collect responses on chain, read them back rendered — with gnoweb as the
 3// only UI.
 4//
 5// # How it works
 6//
 7// The realm renders each form with p/jeronimoalbi/mdform. gnoweb turns that
 8// markdown into a real HTML form whose submit builds a /vm.m_call to Submit,
 9// mapping every input to the Submit parameter of the same name. A respondent
10// fills the form in a browser, signs with their wallet, and the answers land
11// in realm state. No frontend, no backend, no indexer.
12//
13// # Slugs
14//
15// A form's ID is a slug chosen at creation — lowercase letters, digits and
16// single hyphens, 3 to 48 characters, unique per realm. It is the URL
17// segment: /r/<ns>/forms:valoper-questionnaire. Response IDs are sequential.
18//
19// # Field encoding
20//
21// Create takes four parallel, pipe-separated strings so it stays usable from
22// gnokey and gnoweb without structured arguments:
23//
24//	labels:   "Name|Why gno.land?|Server type"
25//	kinds:    "text|textarea|select"
26//	required: "1|1|0"
27//	options:  "||cloud,on-prem,data-center"
28//
29// Kinds are text, textarea, number and select. Options are comma-separated
30// and only read for select fields. A form has at most MaxFields (8) fields;
31// Submit accordingly takes eight answer slots, of which the form's field
32// count are read and the rest must be empty. gnoweb passes "" for any
33// parameter the form does not render an input for.
34//
35// # Who pays
36//
37// Respondents pay the storage deposit for their own answers, which is the
38// spam resistance. Withdraw deletes a response and the chain refunds the
39// deposit to the caller — which is why only the author may withdraw: a
40// deletion by the owner would refund the owner with the respondent's coins.
41//
42// # What is public
43//
44// Everything. Answers, who gave them, and when are all readable by anyone
45// from realm state and from the transactions themselves. This realm is for
46// information that can be public. Sealed responses would need encryption
47// on the respondent's side before the transaction exists, which gnoweb
48// cannot do on a realm's behalf; that is a deliberate non-goal of v1.
49//
50// # Routes
51//
52//	/r/<ns>/forms                     index
53//	/r/<ns>/forms:<id>                a form, fillable
54//	/r/<ns>/forms:<id>/responses      responses, paginated
55//	/r/<ns>/forms:<id>/responses.csv  responses as CSV in a code block
56package forms