@@ -0,0 +1,129 @@
1++++
2+
3+title = "Urbit Forms"
4+date = "2022-05-10"
5+
6+[taxonomies]
7+grant_type = ["Proposal"]
8+grant_category = ["App Dev"]
9+
10+[extra]
11+image = ""
12+description = "Create forms and surveys with multiple question types"
13+reward = "2 stars"
14+assignee = "~nallux-dozryl"
15+champion = "~lagrev-nocfep"
16+grant_id = "P0135"
17+completed = false
18+canceled = false
19+link = ""
20+
21++++
22+
23+# Introduction
24+This document will be split into 2 parts. The agent, which is the hoon code and the view, the glob for displaying the app.
25+I have made the decision to work mostly in json, including the state, as this is the easiest way to keep the front end and back end as similar as possible.
26+In its state, there are no separation between your own surveys and surveys you have received from other people. Instead, we put the author of the survey along side the survey itself. This also applies to responses.
27+# Agent
28+## Types
29+On the top level:
30+`surveys`: the survey store, all forms goes here.
31+`responses`: the response store, all responses goes here.
32+### $surveys
33+This is a map of `author=ship` and a mop of `survey-id` and `survey` sorted by
34+`gth`.
35+`+$ surveys (map author ((mop survey-id survey) gth))`
36+### $responses
37+This is a map of `survey-id` and a map of `author` and mop of `response-id` and `response`
38+sorted by `gth` sorted by `lth`. _sorry for this description_
39+`+$ responses ((mop survey-id (map author ((mop response-id response) gth))) lth)`
40+### $survey
41+A survey is a json object containing:
42+- `title`: `@t -> %s`
43+- `description`: `@t -> %s`
44+- `visibility`: `?(%public %private %team) -> %s`
45+- `slug`: `@ta -> %s`
46+- `questions`: `((mop question-id question) gth) -> %o`
47+_Note: As of right now, `%team` doesn't do anything. This is for future functionality._
48+### $response
49+A response is a json object containing a map of `question-id` and answer sorted by `gth`
50+`((mop question-id answer) gth) -> %o`
51+### $question
52+A question is a json object containing:
53+- `title`: this is the question itself `@t -> %s`
54+- `options`: these are the choices provided `set -> %a of %s`. If no options are required, (text etc), options will be omitted.
55+- `front`: the component type that gets rendered in the view `@tas -> %s`
56+- `back`: the type of value the agent accepts for this question `@tas -> %s`
57+- `required`: whether or not this question is a required question `? -> %b`
58+### $answer
59+An answer is a json object with the back type as the key and the written answer
60+as the value.
61+eg. `[%o p={[p='noun' q=[%s p='this is my answer']]}]`
62+## Actions
63+All possible actions the agent accepts.
64+```+$ action
65+ $% [%create title description visibility slug]
66+ [%delete survey-id]
67+ [%edit edit]
68+ [%ask ship survey-id]
69+ [%submit ship survey-id response]
70+ ==
71+```
72+### %create
73+Creates a new survey.
74+### %delete
75+Deletes a survey from your state.
76+### %edit
77+Edits modifies the state of a survey. Adding, removing or editing
78+questions are also part of this same action.
79+```+$ edit
80+ $% [%title survey-id title]
81+ [%desc survey-id description]
82+ [%vis survey-id visibility]
83+ [%question survey-id q-action]
84+ ==
85+```
86+q-action is defined as follows:
87+```+$ q-action
88+ $% [%add title options front back required]
89+ [%del question-id]
90+ [%mod question-id title options front back required]
91+ ==
92+```
93+_Note: Modifyig a question will delete the question and recreate the question. I'm implementing it this way for simplicity. Open for
94+comments._
95+## Updates
96+Updates are pretty straightforward in this agent. You either send out a survey or a result.
97+```+$ update
98+ $% [%survey survey-id survey]
99+ [%result survey-id result]
100+ ==
101+```
102+Note: Result is a noun, this will be used when validation is a thing. Until then, it's just a placeholder.
103+## Scry Endpoints
104+### Survey
105+1. `/x/surveys/all` - Retrieves all `survey`s in `$surveys`.
106+2. `/x/surveys/[ship]` - Retrieves all `survey`s authored by the selected ship.
107+3. `/x/survey/[survey-id]` - Retrieves a specific survey
108+### Response
109+1. `/x/responses/[survey-id]` - Retrieves all responses for a specific form.
110+2. `/x/responses/[survey-id]/[ship]` - Retrieves all responses from a specific ship for a specific form.
111+View
112+```::::::::::::::::::::::::::
113+:: ::
114+:: GIANT PLACEHOLDER ::
115+:: ::
116+::::::::::::::::::::::::::
117+```
118+# Deliverables and Funding
119+## Milestone 1 - 1 Star
120+1. Complete core functionality as laid out above.
121+## Milestone 2 - 1 Star
122+1. Improved GUI
123+2. Validation
124+3. Multiple editors in one survey
125+4. Anonymous survey -- Earth facing mirror
126+
127+# Miscellaneous
128+##Contact, Issues, Requests, Feedback
129+`~donpub-datdux/gerhana-network`