@@ -0,0 +1,247 @@
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
25+ the view, the glob for displaying the app.
26+
27+I have made the decision to work mostly in json, including the state, as this is the easiest
28+ way to keep the front end and back end as similar as possible.
29+
30+In its state, there are no separation between your own surveys and surveys you have received from
31+ other people. Instead, we put the author of the survey along side the survey itself. This also
32+ applies to responses.
33+
34+## Agent
35+
36+### Types
37+On the top level:
38+- `surveys`: the survey store, all forms goes here.
39+- `responses`: the response store, all responses goes here.
40+
41+#### $surveys
42+This is a map of `author=ship` and a mop of `survey-id` and `survey` sorted by
43+ `gth`.
44+```
45++$ surveys (map author ((mop survey-id survey) gth))
46+```
47+
48+#### $responses
49+This is a mop of `survey-id` and a map of `author` and mop of `response-id` and `response`
50+ sorted by `gth` sorted by `lth`. *sorry for this description*
51+```
52++$ responses ((mop survey-id (map author ((mop response-id response) gth))) lth)
53+```
54+
55+#### $survey
56+A survey is a json object containing:
57+- `title`: `@t -> %s`
58+- `description`: `@t -> %s`
59+- `visibility`: `?(%public %private %team) -> %s`
60+- `slug`: `@ta -> %s`
61+- `questions`: `((mop question-id question) gth) -> %o`
62+
63+_**Note:**_ As of right now, %team doesn't do anything. This is for future functionality.
64+
65+#### $response
66+A response is a json object containing a mop of `question-id` and `answer` sorted by gth
67+```
68+((mop question-id answer) gth) -> %o
69+```
70+
71+#### $question
72+A question is a json object containing:
73+- `title`: this is the question itself `@t -> %s`
74+- `options`: these are the choices provided `set -> %a of %s`. If no
75+ options are required, (text etc), options will be omitted.
76+- `front`: the component type that gets rendered in the view `@tas -> %s`
77+- `back`: the type of value the agent accepts for this question `@tas -> %s`
78+- `required`: whether or not this question is a required question `? -> %b`
79+
80+#### $answer
81+An answer is a json object with the back type as the key and the written answer
82+ as the value.
83+```
84+eg. [%o p={[p='noun' q=[%s p='this is my answer']]}]
85+```
86+
87+### Actions
88+All possible actions the agent accepts.
89+
90+```
91++$ action
92+ $% [%create title description visibility slug]
93+ [%delete survey-id]
94+ [%edit edit]
95+ [%ask ship survey-id]
96+ [%respond survey-id question-id answer]
97+ [%submit ship survey-id response]
98+ ==
99+```
100+
101+#### %create
102+Creates a new survey.
103+
104+#### %delete
105+Deletes a survey from your state.
106+
107+#### %edit
108+Edits modifies the state of a survey. Adding, removing or editing
109+ questions are also part of this same action.
110+
111+```
112++$ edit
113+ $% [%title survey-id title]
114+ [%desc survey-id description]
115+ [%vis survey-id visibility]
116+ [%question survey-id q-action]
117+ ==
118+```
119+q-action is defined as follows:
120+```
121++$ q-action
122+ $% [%add title options front back required]
123+ [%del question-id]
124+ [%mod question-id title options front back required]
125+ ==
126+```
127+_**Note:**_ Modifying a question will delete the question and recreate
128+ the question. I'm implementing it this way for simplicity. Open for
129+ comments.
130+
131+#### %ask
132+Pokes the author ship to get a survey.
133+
134+#### %respond
135+This puts an answer in the response and thus building the final response that will be sent
136+ to the survey author via %submit
137+
138+### Updates
139+Updates are pretty straightforward in this agent. You either send out a `survey` or a `result`.
140+```
141++$ update
142+ $% [%survey survey-id survey]
143+ [%result survey-id result]
144+ ==
145+```
146+_**Note:**_ Result is a noun, this will be used when validation is a thing. Until then, it's just a placeholder.
147+
148+### Scry Endpoints
149+
150+#### Survey
151+1. `/x/surveys/all` - Retrieves all `survey`s in `$surveys`.
152+2. `/x/surveys/[ship]` - Retrieves all `survey`s authored by the selected ship.
153+3. `/x/survey/[survey-id]` - Retrieves a specific survey
154+
155+#### Response
156+1. `/x/responses/[survey-id]` - Retrieves all responses for a specific form.
157+2. `/x/responses/[survey-id]/[ship]` - Retrieves all responses from a specific ship for a specific form.
158+
159+## View
160+
161+The term `form` and `survey` will be used interchangably below. This is because the agent uses
162+`survey` but the term `form` is more commonly used in the real world.
163+
164+### Home Page
165+
166+When opening the app, you will be greeted by the homepage. On the topmost of the page,
167+ there is a search bar. This is for requesting a survey from another ship. Below that,
168+ is the `+ Create` button. After that, a list of all the surveys in your survey
169+ store. Each item displays the title of the survey as well as a dropdown arrow. Clicking
170+ on the item itself will open the survey for responding.
171+
172+By clicking on the arrow, you will be presented with edit, respond, delete and clone. If you
173+ do not own the survey, you will not be able to edit it.
174+
175+
176+
177+### New Form
178+
179+After clicking on the `+ Create` button in the home page, you will be directed to this page.
180+ The title and description of the survey will by default `Untitled Form` and
181+ `enter description here` respectively. This can be changed.
182+
183+Next, there are three tabs displayed. The first is this page, `questions`. Then there is
184+ `responses` and `settings`.
185+
186+If there are no questions, only the buttons at the bottom of the screen will show. `+` is for
187+ adding a new question, and the floppy disk icon is the save button. Clicking this will update
188+ the state of your agent.
189+
190+
191+
192+### Responses
193+
194+Here, we see a similar layout to `New Form`, except the questions do not have options you can
195+ change. At the bottom of the screen, there are two buttons indicating `previous` and `next`
196+ with numbers showing the current and total reponses in between them. These buttons allow you to
197+ cycle between the different responses that have been submitted to you.
198+
199+
200+
201+### Settings
202+
203+This is the settings menu. You get to switch the visibility of the survey and modify the slug of
204+ the survey.
205+
206+
207+
208+### Responding
209+
210+This is the page you see when you click on any of the surveys in the home page. You will be
211+ presented with the title and description of the survey, with the address of the survey next
212+ to it.
213+
214+Below all that are the questions itself. At the bottom of the survey, there is a submit button.
215+ Clickng on `submit` will send your response to the author of the survey.
216+
217+
218+
219+## Deliverables and Funding
220+
221+### Milestone 1 - 1 Star
222+- The agent should be able to
223+ - Send, receive, edit and delete surveys.
224+ - Submit, receive and delete responses.
225+- A working front-end with the features outlined in the screenshots above.
226+- 9 front end question types
227+ - short text
228+ - paragraph
229+ - multiple choice (select one)
230+ - multiple choice (select many)
231+ - linear scale (discrete)
232+ - linear scale (continuous)
233+ - multiple choice grid (select one)
234+ - multiple choice grid (select many)
235+ - datetime
236+
237+### Milestone 2 - 1 Star
238+- Improved front-end
239+- CSV export
240+- Validation
241+- Multiple editors in one survey
242+- Anonymous survey -- Earth facing mirror
243+
244+## Miscellaneous
245+
246+### Contact, Issues, Requests, Feedback
247+`~donpub-datdux/gerhana-network`