CLDC-NONE: Finish question and page docs

docs/form/page.md

@@ -11,32 +11,11 @@ Pages sit below the [`Subsection`](subsection) level of a form definition.
 An example page might look something like this:
 
 ```
-class Form::Sales::Pages::PropertyPostcode < ::Form::Page
+class Form::Sales::Pages::SomePage < ::Form::Page
   def initialize(id, hsh, subsection)
     super
-    @id = property_postcode
-    @depends_on = [{ "needstype" => 1 }]
-    @title_text = {
-      "translation": "translation1",
-      "arguments": [
-        {
-          "key": "some_general_field",
-          "label": true,
-          "i18n_template": "template1"
-        }
-      ]
-    }
-    @informative_text": {
-      "translation": "translation2",
-      "arguments": [
-        {
-          "key": "some_currency_method",
-          "label": false,
-          "i18n_template": "template2",
-          "currency": true,
-        }
-      ]
-    }
+    @id = "some_page"
+    @depends_on = [{ "needstype" => 1 }, { "age#{@person_index}" => { "operator" => "<", "operand" => 16 } }]
   end
 
   def questions
@@ -56,3 +35,23 @@ The description is optional but if provided is used for a paragraph displayed un
 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 accessible 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.
 
 Pages can contain one or more [questions](question).
+
+## Useful Properties
+<dl>
+<dt>id</dt>
+<dd>
+The name of the field. This should correspond to a column in the database. In the example, the id is 'ppcodenk'.
+<br>
+Note page IDs must be unique. If not unique, you may run into issues where the next page function will have a stack overflow exception. This is true if using `depends_on` blocks to hide/show pages. You can however reuse page names if using ternary or if conditions to dynamically add pages to a subsection. We only do this for year specific pages on CORE, so page IDs don't have to be unique across all years.
+<br>
+A potential issue you may see is if you accidentally set the page ID to null, the code to register all the page routes will try to register a nil route, which will set it to the root path for a log. This means you'll get a strange error on the log summary page.</dd>
+<dt>depends_on</dt>
+<dd>
+Pages can have a `depends_on` which contains the set of conditions that must be met for the page to be accessible. It is specified as a hash from properties of a log to conditions.
+<br>
+A condition can be a single value that must equal the property or a hash of comparisons. Multiple conditions in a single hash work as 'AND' conditions. Multiple hashes work as 'OR' conditions.
+<br>
+If the conditions are not met then the page is not routed to as part of the form flow. In the above example the page is dependent on picking `General needs` on the `needstype` question, or age being 16+.</dd>
+<dt>questions</dt>
+<dd>Array of questions to show on the page.</dd>
+</dl>

docs/form/question.md

@@ -46,14 +46,14 @@ class Form::Sales::Questions::PreviousPostcodeKnown < ::Form::Question
 end
 ```
 
-Let's take a look at the properties in the `initialize` function.
+## Useful Properties
 
 <dl>
 <dt>id</dt>
 <dd>The name of the field. This should correspond to a column in the database. In the example, the id is 'ppcodenk'.</dd>
 
 <dt>copy_key</dt>
-<dd>This specifies copy from <code>config/locales/forms/...</code> that should be associated with the question</dd>
+<dd>This specifies copy from <code>config/locales/forms/...</code> that should be associated with the question. Not normally needed, will be inferred as <code>#{form.type}.#{subsection.copy_key}.#{id}</code>.</dd>
 
 <dt>type</dt>
 <dd>Determines what type of question is rendered on the page. In the example, the question is a Radio Form so the <code>app/views/form/_radio_question.html.erb</code> partial will be rendered on the page when this question is displayed to the user</dd>
@@ -75,7 +75,17 @@ Let's take a look at the properties in the `initialize` function.
 <dd>
   Determines which number gets rendered next to the question text on the question page and in the 'check your answers' page.
   <br/>
-  The convention that we use for the question number is that we only add to the 'QUESTION_NUMBER_FROM_YEAR' hash when the question number changes. So, if the example remains unchanged into 2026, 2027, etc., that means that it is still question 57. 
+  The convention that we use for the question number is that the hash should contain all years explicitly, even if it doesn't change between years. When building a new year's forms we should add the question number for the new year to all questions. See the `add_new_year_to_questions` rake.
+</dd>
+
+<dt>disable_clearing_if_not_routed_or_dynamic_answer_options</dt>
+<dd>
+  Questions that are not routed to will be cleared. Setting this to true will prevent this from happening. Normally can be replaced with implementing <code>derived?</code>.
+</dd>
+
+<dt>check_answers_card_number</dt>
+<dd>
+  Is used only for the household characteristics section as each person gets their own card on the CYA page. If you're looking to add a custom CYA card somewhere else in the form, see <code>check_answers_card_title</code>
 </dd>
 </dl>
 
@@ -109,3 +119,26 @@ end
 <dt>inferred_answers</dt>
 <dd>Determines any questions whose answers can be inferred based on the answer to this question. In the example, the 'la' question (Local Authority) can be inferred from the Postcode. We set a property 'is_la_inferred' on the log to record this inferrance.</dd>
 </dl>
+
+## Useful methods
+<dl>
+<dt>derived?</dt>
+<dd>This is function that should return true if the question is to be derived, such as where it's answer can be inferred based on another question. Setting this to true will cause the question to not be shown in CYA. The user will still be shown the question. This method is very similar to a depends_on method, but a depends_on block is used to always infer an answer of "". derived? is reliant on other code setting the answer, such as <code>set_derived_fields!</code></dd>
+
+<dt>get_extra_check_answer_value</dt>
+<dd>Used for putting extra lines below the main answer in the CYA page. Used on the address search to show the full address below the UPRN</dd>
+
+<dt>label_from_value</dt>
+<dd>Used for custom labels that differ from the main site. Normally will use the labels on the page, Useful for instance changing "No, enter xyz" to just "No".</dd>
+
+<dt>skip_question_in_form_flow?</dt>
+<dd>Similar to derived, but the user is still able to go back and edit the question later. Will not cause question to be hidden from CYA.</dd>
+</dl>
+
+## Question visibility
+There are broadly 3 reasons to hide a question. Here's how to handle them.
+
+1. The question should not be asked, answer should be derived as nil and user should not be able to change this. If so, set up a `depends_on` on the page.
+2. The question should not be asked, answer should be derived as some value and user should not be able to change this. If so, set up a `depends_on` on the page and set up a `derived?`. Use a method like `set_derived_fields!` to set the answer.
+3. The question should not be asked, answer should be derived as some value and user should be able to change this. If so, set up a `skip_question_in_form_flow?` method.
+