@@ -0,0 +1,247 @@
7+grant_type = ["Proposal"]
8+grant_category = ["App Dev"]
12+description = "Create forms and surveys with multiple question types"
14+assignee = "~nallux-dozryl"
15+champion = "~lagrev-nocfep"
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.
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.
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.
38+- `surveys`: the survey store, all forms goes here.
39+- `responses`: the response store, all responses goes here.
42+This is a map of `author=ship` and a mop of `survey-id` and `survey` sorted by
45++$ surveys (map author ((mop survey-id survey) gth))
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*
52++$ responses ((mop survey-id (map author ((mop response-id response) gth))) lth)
56+A survey is a json object containing:
58+- `description`: `@t -> %s`
59+- `visibility`: `?(%public %private %team) -> %s`
61+- `questions`: `((mop question-id question) gth) -> %o`
63+_**Note:**_ As of right now, %team doesn't do anything. This is for future functionality.
66+A response is a json object containing a mop of `question-id` and `answer` sorted by gth
68+((mop question-id answer) gth) -> %o
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`
81+An answer is a json object with the back type as the key and the written answer
84+eg. [%o p={[p='noun' q=[%s p='this is my answer']]}]
88+All possible actions the agent accepts.
92+ $% [%create title description visibility slug]
95+ [%ask ship survey-id]
96+ [%respond survey-id question-id answer]
97+ [%submit ship survey-id response]
102+Creates a new survey.
105+Deletes a survey from your state.
108+Edits modifies the state of a survey. Adding, removing or editing
109+ questions are also part of this same action.
113+ $% [%title survey-id title]
114+ [%desc survey-id description]
115+ [%vis survey-id visibility]
116+ [%question survey-id q-action]
119+q-action is defined as follows:
122+ $% [%add title options front back required]
124+ [%mod question-id title options front back required]
127+_**Note:**_ Modifying a question will delete the question and recreate
128+ the question. I'm implementing it this way for simplicity. Open for
132+Pokes the author ship to get a survey.
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
139+Updates are pretty straightforward in this agent. You either send out a `survey` or a `result`.
142+ $% [%survey survey-id survey]
143+ [%result survey-id result]
146+_**Note:**_ Result is a noun, this will be used when validation is a thing. Until then, it's just a placeholder.
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
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.
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.
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.
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.
175+
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.
183+Next, there are three tabs displayed. The first is this page, `questions`. Then there is
184+ `responses` and `settings`.
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.
190+
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.
199+
203+This is the settings menu. You get to switch the visibility of the survey and modify the slug of
206+
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
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.
217+
219+## Deliverables and Funding
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
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)
237+### Milestone 2 - 1 Star
241+- Multiple editors in one survey
242+- Anonymous survey -- Earth facing mirror
246+### Contact, Issues, Requests, Feedback
247+`~donpub-datdux/gerhana-network`