Form documentation

Adding documentation for the form definition including elements such as
the sections, subsections, pages and questions

docs/form/form.md

@@ -0,0 +1,86 @@
+## Form Definition
+
+The current system is built around a form definition written in JSON. At the top level every form will expect to have the following attributes:
+
+- Form type: this is to define whether the form is a lettings form or a sales form. The questions will differ between the types.
+- Start date: the start of the collection window for the form, this will usually be in April
+- End date: the end date of the collection window for the form, this will usually be in July, a year after the start date.
+- Sections: the sections in the form, this block is where the bulk of the form definition will be.
+
+An example of this might look like the following:
+```JSON
+{ 
+  "form_type": "lettings",
+  "start_date": "2021-04-01T00:00:00.000+01:00",
+  "end_date": "2022-07-01T00:00:00.000+01:00",
+  "sections": {
+    ... 
+  }
+}
+```
+
+Note that the end date of one form will overlap the start date of another to allow for late submissions. This means that every year there will be a period of time in which two forms are running simultaneously
+
+### How is the form split up?
+
+A summary of how the form is split up is as follows:
+
+- A form is divided up into one or more sections. 
+- Each section can have one or more subsections. 
+- Each subsection can have one or more pages. 
+- Each page can have one or more questions.
+
+More information about these form elements can be found in the following links:
+
+- Section
+- Subsections
+- Page
+- Question
+
+### The Form Model, Views and Controller
+
+Rails uses the Model, View, Controller (MVC) pattern which we follow.
+
+#### The Form Model
+
+There is no need to manually initialise a form object as this is handled by the FormHandler class at boot time. If a new form needs to be added then a JSON file containing the form definition should be added to `config/forms` where the FormHandler will be able to locate it and instantiate it.
+
+A form has the following attributes:
+
+- name: The name of the form
+- setup_sections: The setup section (this is not defined in the JSON, for more information see this)
+- form_definition: The parsed form JSON
+- form_sections: The sections found within the form definition JSON
+- type: The type of form (this is used to indicate if the form is for a sale or a letting)
+- sections: The combination of the setup section with those found in the JSON definition
+- subsections: The subsections of the form (these live under the sections)
+- pages: The pages of the form (these live under the subsections)
+- questions: The questions of the form (these live under the pages)
+- start_date: The start date of the form, in iso8601 format
+- end_date: The end date of the form, in iso8601 format
+
+
+#### The Form Views
+
+The main view used for rendering the form is the `app/views/form/page.html.erb` view as the Form contains multiple pages (which live in subsections within sections). This page view then renders the appropriate partials for the question types of the questions on the current page.
+
+We currently have views for the following question types:
+- Numerical
+- Date
+- Checkbox
+- Radio
+- Select
+- Text
+- Textarea
+- Interruption screen
+
+Interruption screen questions are radio questions used for soft validation of fields. They usually have yes and no options for a user to confirm a value is correct.
+
+#### The Form Controller
+
+The form controller handles the form submission as well as the rendering of the check answers page and the review page.
+
+### The FormHandler helper class
+
+The FormHandler helper is a helper that loads all of the defined forms and initialises them as Form objects. It can also be used to get specific forms if needed.
+

docs/form/page.md

@@ -0,0 +1,28 @@
+## Page
+
+Pages are under the subsection level of the form definition. A example page might look something like this:
+
+```JSON
+"property_postcode": {
+  "header": "",
+  "description": "",
+  "questions": {
+    ...
+  },
+  "depends_on": [
+    {
+      "needstype": 1
+    }
+  ]
+}
+```
+
+In the above example the the subsection has the id `property_postcode`. This id is used for the url of the web page, but the underscore is replaced with a hash, so the url for this page would be `[environment-url]/logs/[log-id]/property-postcode` e.g. on staging this url might look like the following: `https://dluhc-core-staging.london.cloudapps.digital/logs/1234/property-postcode`
+
+The header is optional but if provided is used for the heading displayed on the page
+
+The description is optional but if provided is used for a paragraph displayed under the page header
+
+It's worth noting that like subsections a page can also have a `depends_on` which contains the set of conditions that must be met for the section to be accessibile to a data provider. If the conditions are not met then the page is not routed to as part of the form flow. The `depends_on` for a page will usually depend on answers given to questions, most likely to be questions in the setup section. In the above example the page is dependent on the answer to the `needstype` question being `1`, which corresponds to picking `General needs` on that question as displayed to the data provider.
+
+

docs/form/section.md

@@ -0,0 +1,26 @@
+## Section
+
+Sections are under the top level of the form definition. A example section might look something like this:
+
+```JSON
+"sections": {
+    "tenancy_and_property": {
+      "label": "Property and tenancy information",
+      "subsections": {
+        "property_information": {
+          ...
+        },
+        "tenancy_information": {
+          ...
+        }
+      }
+    },
+    ...
+}
+```
+
+In the above example the section id would be `tenancy_and_property` and its subsections would be `property_information` and `tenancy_information`.
+
+The label contains the text that users will see for that section in the tasklist page of a case log.
+
+Sections can contain one or more subsections. For more information about subsections follow this link.

docs/form/subsection.md

@@ -0,0 +1,28 @@
+## Subsection
+
+Subsections are under the section level of the form definition. A example subsection might look something like this:
+
+```JSON
+"property_information": {
+  "label": "Property information",
+  "depends_on": [
+    {
+      "setup": "completed"
+    }
+  ],
+  "pages": {
+    "property_postcode": {
+      ...
+    },
+    "property_local_authority": {
+      ...
+    }
+  }
+}
+```
+
+In the above example the the subsection has the id `property_information`. The `depends_on` contains the set of conditions that must be met for the section to be accessibile to a data provider, in this example subsection depends on the completion of the setup section/subsection (note that this is a common condition as the answers provided to questions in the setup subsection often have an impact on what questions are asked of the data provider in later subsections of the form).
+
+The label contains the text that users will see for that subsection in the tasklist page of a case log.
+
+The pages of the subsection in the example would be `property_postcode` and `property_local_authority`. Subsections can contain one or more pages.