From 71beb4fd62847b9d3ca86746b6500af7de3d3028 Mon Sep 17 00:00:00 2001 From: Katherine Langford Date: Fri, 23 Jan 2026 17:20:11 +0000 Subject: [PATCH 01/18] CLDC-NONE: Update setup docs to reccommend WSL --- docs/setup.md | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/docs/setup.md b/docs/setup.md index 8bf9c635f..d961462f9 100644 --- a/docs/setup.md +++ b/docs/setup.md @@ -18,6 +18,14 @@ We recommend using [RBenv](https://github.com/rbenv/rbenv) to manage Ruby versio We recommend using [nvm](https://github.com/nvm-sh/nvm) to manage NodeJS versions. +## Instructions for Windows users + +If you are working on a windows machine, you will want to install the tools on [WSL](https://learn.microsoft.com/en-us/windows/wsl/install) as some of them are not native to windows. The instructions in these docs assume a Debian-based distribution, such as Ubuntu. + +*You will see a significant performance degradation if you are running the server on WSL whilst the files are on windows.* Thus, make sure to clone the repository into your WSL instance. + +Some windows IDEs, such as [VSCode](https://code.visualstudio.com/docs/remote/wsl) and [RubyMine](jetbrains.com/help/ruby/remote-development-starting-page.html#run_in_wsl_ij) can connect you to WSL, which will allow you to develop as though the files were on the local windows filesystem. Ignore any reccommendations that you might see suggesting you keep the files on windows - our experience is that both tests and page loads are much slower when the files are on windows. + ## Pre-setup installation 1. Install PostgreSQL From f00986d2ba69dd16b34d78829f39dd673f83ed1b Mon Sep 17 00:00:00 2001 From: Katherine Langford Date: Fri, 23 Jan 2026 18:58:05 +0000 Subject: [PATCH 02/18] CLDC-NONE: Documentation for creating a new question --- docs/adr/index.md | 2 +- docs/dev_tasks/index.md | 9 ++ docs/dev_tasks/new_sales_question.md | 119 +++++++++++++++++++++++++++ docs/documentation_website.md | 2 +- 4 files changed, 130 insertions(+), 2 deletions(-) create mode 100644 docs/dev_tasks/index.md create mode 100644 docs/dev_tasks/new_sales_question.md diff --git a/docs/adr/index.md b/docs/adr/index.md index b4ee4f8ce..e8479c56e 100644 --- a/docs/adr/index.md +++ b/docs/adr/index.md @@ -1,6 +1,6 @@ --- has_children: true -nav_order: 14 +nav_order: 15 --- # Architecture decisions diff --git a/docs/dev_tasks/index.md b/docs/dev_tasks/index.md new file mode 100644 index 000000000..ca53fc7da --- /dev/null +++ b/docs/dev_tasks/index.md @@ -0,0 +1,9 @@ +--- +has_children: true +nav_order: 14 +--- + +# Common dev tasks + +A collection of guides for tasks that may have to be carried out repeatedly. + diff --git a/docs/dev_tasks/new_sales_question.md b/docs/dev_tasks/new_sales_question.md new file mode 100644 index 000000000..5b7c67032 --- /dev/null +++ b/docs/dev_tasks/new_sales_question.md @@ -0,0 +1,119 @@ +--- +parent: Common dev tasks +nav_order: 1 +--- + +# New Sales Log Questions + +Concerns adding a brand-new question to Sales Logs. This question will appear on the website as part of the Sales form and should be handled in Bulk Uploads. + +Guide is up-to-date as of 2026. + +## Basic checklist of tasks + +### 1. Create a migration to add the new field to the database + +This allows the answer to the new question to be saved. + +You can create a new empty migration file from the terminal if you are in the root of the project: + +``` +bin/rails generate migration NameOfMigration +``` + +The new migration file will be saved in `db/migrate`. + +Whilst the specifics will vary, the new migration file should look something like this: + +```ruby +class AddSexRegisteredAtBirthToSalesLogs < ActiveRecord::Migration[7.2] + def change + # Add a new column called "name" of type string to the sales_logs table + change_table :sales_logs, bulk: true do |t| + t.column :name, :string + end + end +end +``` + +See also: [Active record migrations](https://guides.rubyonrails.org/active_record_migrations.html) + +### 2. Run the new migration + +`bundle exec rake db:migrate` + +This will update `schema.rb`. You should not edit `schema.rb` directly. + +### 3. Create a new question class + +This will define the question that gets rendered on the online form. + +Existing question classes can be found in `app/models/form/sales/questions/`. Depending on the type of question (checkboxes, radio groups, free-text fields), there will almost certainly be an existing question class that you can refer to as a guide. + +For example, if you need to create a new radio form, then you may want to copy `armed_forces.rb`. + +See also: [Question]({% link form/question.md %}) + +### 4. Create a new page class + +This creates the page that your new question will be rendered on. + +Existing page classes can be found in `app/models/form/sales/pages`. + +Usually there is only one question per page, but in some cases there may be multiple. It may not be necessary to create a new page if the new question is being added to an existing one. + +See also: [Page]({% link form/page.md %}) + +### 5. Add new page to an existing subsection + +Without this step, your new page will not be inserted into the form! + +Subsections can be found in `app/models/form/sales/subsections`. + +You will want to add your new page to the appropriate place in the list returned by `def pages`. + +To make your new page only appear in the forms for the upcoming year, you wrap the page class in parentheses and add a conditional expression to the end, like so: + +```ruby +(Form::Sales::Pages::SexRegisteredAtBirth1.new(nil, nil, self) if form.start_year_2026_or_later?), +``` + +### 6. Update the locale file + +The locale files define some of the text for the new question, including hints and the question itself. + +Locale files can be found in `config/locales/forms//sales/` and there is one locale file for each form subsection. + +Copy the entry for an existing question and substitute in the text for your new one. + +### 7. Include the new field in exports + +The fields that get exported in CSVs and XMLs are defined in `app/services/exports/sales_log_export_constants.rb`. + +If there is not a set for POST__EXPORT_FIELDS, create one. Add your new field to the current year's set. + +You may also have to update the `sales_log_export_service.rb` to correctly filter the year-specific fields. + +### 8. Update the bulk upload row parser + +This will allow bulk upload files to save the new field to the database. + +You can find the relevant file at `app/services/bulk_upload/sales/year/row_parser.rb`. + +You will need to add a new `field_XXX` for the new field. In total, update the following places: + +- Add the new field to `QUESTIONS` with the text of the question. +- Add a new attribute alongside the existing ones neat the top of the file: + ```ruby + attribute :field_XXX, :type + ``` +- Add the new field to `field_mapping_for_errors` with the name of the field in the database. +- Add the new field to `attributes_for_log` with the name of the field in the database. + +You may also have to add some additional validation rules in this file. + +Validation for ensuring that the value uploaded is one of the permitted options is handled automatically, using the question class as the original source of truth. + +### 9. Update unit tests + +Create new test files for any new classes you have created. Update any test files for files that you have edited. diff --git a/docs/documentation_website.md b/docs/documentation_website.md index b306a6398..5032352b6 100644 --- a/docs/documentation_website.md +++ b/docs/documentation_website.md @@ -1,5 +1,5 @@ --- -nav_order: 15 +nav_order: 16 --- # This documentation website From a5f51638e5d4ab74c0295328913f66182e7f37e2 Mon Sep 17 00:00:00 2001 From: Katherine Langford Date: Tue, 27 Jan 2026 18:51:43 +0000 Subject: [PATCH 03/18] CLDC-NONE: Update question doc --- docs/form/question.md | 121 +++++++++++++++++++++++++----------------- 1 file changed, 73 insertions(+), 48 deletions(-) diff --git a/docs/form/question.md b/docs/form/question.md index 7112596cf..a40509757 100644 --- a/docs/form/question.md +++ b/docs/form/question.md @@ -6,81 +6,106 @@ nav_order: 4 # Question +*Updated for 2026.* + Questions are under the page level of the form definition. An example question might look something like this: -``` -class Form::Sales::Questions::PostcodeKnown < ::Form::Question +```ruby +class Form::Sales::Questions::PreviousPostcodeKnown < ::Form::Question def initialize(id, hsh, page) super - @id = postcode_known - @hint_text = "" - @header = "Do you know the property postcode?" - @check_answer_label = "Do you know the property postcode?" + @id = "ppcodenk" + @copy_key = "sales.household_situation.last_accommodation.ppcodenk" @type = "radio" - @answer_options = { - "1" => { "value" => "Yes" }, - "0" => { "value" => "No" } - }, + @answer_options = ANSWER_OPTIONS @conditional_for = { - "postcode_full" => [1] - }, - @hidden_in_check_answers = true + "ppostcode_full" => [0], + } + @hidden_in_check_answers = { + "depends_on" => [ + { + "ppcodenk" => 0, + }, + { + "ppcodenk" => 1, + }, + ], + } + @question_number = QUESTION_NUMBER_FROM_YEAR[form.start_date.year] || QUESTION_NUMBER_FROM_YEAR[QUESTION_NUMBER_FROM_YEAR.keys.max] + @disable_clearing_if_not_routed_or_dynamic_answer_options = true end + + ANSWER_OPTIONS = { + "0" => { "value" => "Yes" }, + "1" => { "value" => "No" }, + }.freeze + + QUESTION_NUMBER_FROM_YEAR = { 2023 => 57, 2024 => 59, 2025 => 57 }.freeze end ``` -In the above example the the question has the id `postcode_known`. +Let's take a look at the properties in the `initialize` function. -The `check_answer_label` contains the text that will be displayed in the label of the table on the check answers page. +
+
id
+
The name of the field. This should correspond to a column in the database. In the example, the id is 'ppcodenk'.
-The header is text that is displayed for the question. +
copy_key
+
Unknown; requires investigation.
-Hint text is optional, but if provided it sits under the header and is normally given to provide the data inputters with guidance when answering the question, for example it might inform them about terms used in the question. +
type
+
Determines what type of question is rendered on the page. In the example, the question is a Radio Form so the app/views/form/_radio_question.html.erb partial will be rendered on the page when this question is displayed to the user
-The type is question type, which is used to determine the view rendered for the question. In the above example the question is a radio type so the `app/views/form/_radio_question.html.erb` partial will be rendered on the page when this question is displayed to the user. +
answer_options
+
Some types of question offer multiple options to pick from, which can be defined here. In the example, there are two options. The option that will be rendered with the label 'Yes' has the underlying value 0. The option with the label 'No' has the underlying value 1.
-The `conditional_for` contains the value needed to be selected by the data inputter in order to display another question that appears on the same page. In the example above the `postcode_full` question depends on the answer to `postcode_known` being selected as `1` or `Yes`, this would then display the `postcode_full` underneath the `Yes` option on the page, allowing the provide the provide the postcode if they have indicated they know it. If the user has JavaScript enabled then this realtime conditional display is handled by the `app/frontend/controllers/conditional_question_controller.js` file. +
conditional_for
+
Allows for additional questions to be rendered on the page if a certain value is chosen for the current question. In the example, if the value of this question is 0 (the 'Yes' option is selected), then the question with id 'ppostcode_full' will be rendered beneath the selected option.
If the user has JavaScript enabled then this realtime conditional display is handled by the app/frontend/controllers/conditional_question_controller.js file.
-the `hidden_in_check_answers` is used to hide a value from displaying on the check answers page. You only need to provide this if you want to set it to true in order to hide the value for some reason e.g. it's one of two questions appearing on a page and the other question is displayed on the check answers page. It's also worth noting that you can declare this as a with a `depends_on` which can be useful for conditionally displaying values on the check answers page. For example: +
hidden_in_check_answers
+
+ Allows us to hide the question on the 'check your answers' page. You only need to provide this if you want to set it to true in order to hide the value for some reason e.g. it's one of two questions appearing on a page and the other question is displayed on the check answers page. +
+ If depends_on is supplied, then whether this question is hidden can be made conditional on the answers provided to any question. In the example, the question is hidden if 'ppcodenk' (this question) has value 0 or 1. (As these are the only two possible answers, the question will always be hidden.) +
-``` -@hidden_in_check_answers = { - "depends_on" => [ - { "age6_known" => 0 }, - { "age6_known" => 1 } - ] -} -``` - -Would mean the question the above is attached to would be hidden in the check answers page if the value of age6_known is either `0` or `1`. +
question_number
+
+ Determines which number gets rendered next to the question text on the question page and in the 'check your answers' page. +
+ 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 answer the data inputter provides to some questions allows us to infer the values of other questions we might have asked in the form, allowing us to save the data inputters some time. An example of how this might look is as follows: +Another example shows us some fields that are used when we want to infer the answers to one question based on a user's answers to another question. This can allow the user to have to answer fewer questions, lowering their total number of clicks. -``` -class Form::Sales::Questions::PostcodeFull < ::Form::Question +```ruby +class Form::Sales::Questions::PostcodeForFullAddress < ::Form::Question def initialize(id, hsh, page) super - @id = postcode_full - @hint_text = "" - @header = "What is the property’s postcode?"" - @check_answer_label = "Postcode"" - @type = "text" - @width = 5 + @id = "postcode_full" + @inferred_check_answers_value = [{ + "condition" => { + "pcodenk" => 1, + }, + "value" => "Not known", + }] @inferred_answers = { - "la" => { "is_la_inferred" => true } + "la" => { + "is_la_inferred" => true, + }, } - @inferred_check_answers_value => [{ - "condition" => { "postcode_known" => 0 }, - "value": "Not known" - }] + # Other fields omitted for brevity end end ``` -In the above example the width is an optional attribute and can be provided for text type questions to determine the width of the text box on the page when when the question is displayed to a user (this allows you to match the width of the text box on the page to that of the design for a question). - -The above example links to the first example as both of these questions would be on the same page. The `inferred_check_answers_value` is what should be displayed on the check answers page for this question if we infer it. If the value of `postcode_known` was given as `0` (which is a no), as seen in the condition part of `inferred_check_answers_value` then we can infer that the data inputter does not know the postcode and so we would display the value of `Not known` on the check answers page for the postcode. +
+
inferred_check_answers_value
+
Determines what gets shown on the 'check your answers' page if we infer the answer to this question. In the example, if the question 'pcodenk' has value 1 (indicating that the postcode is not known), then the answer shown for this question will be 'Not known'.
-In the above example the `inferred_answers` refers to a question where we can infer the answer based on the answer of this question. In this case the `la` question can be inferred from the postcode value given by the data inputter as we are able to lookup the local authority based on the postcode given. We then set a property on the lettings log `is_la_inferred` to true to indicate that this is an answer we've inferred. +
inferred_answers
+
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.
+
From 97d0c4fac9642589770e628d4f71a143dfa20a2a Mon Sep 17 00:00:00 2001 From: Katherine Langford Date: Wed, 28 Jan 2026 10:11:50 +0000 Subject: [PATCH 04/18] CLDC-NONE: Lint fixes --- docs/dev_tasks/index.md | 1 - docs/dev_tasks/new_sales_question.md | 4 ++-- docs/form/question.md | 2 +- docs/setup.md | 4 ++-- 4 files changed, 5 insertions(+), 6 deletions(-) diff --git a/docs/dev_tasks/index.md b/docs/dev_tasks/index.md index ca53fc7da..1eeea9e77 100644 --- a/docs/dev_tasks/index.md +++ b/docs/dev_tasks/index.md @@ -6,4 +6,3 @@ nav_order: 14 # Common dev tasks A collection of guides for tasks that may have to be carried out repeatedly. - diff --git a/docs/dev_tasks/new_sales_question.md b/docs/dev_tasks/new_sales_question.md index 5b7c67032..f249b871e 100644 --- a/docs/dev_tasks/new_sales_question.md +++ b/docs/dev_tasks/new_sales_question.md @@ -90,7 +90,7 @@ Copy the entry for an existing question and substitute in the text for your new The fields that get exported in CSVs and XMLs are defined in `app/services/exports/sales_log_export_constants.rb`. -If there is not a set for POST__EXPORT_FIELDS, create one. Add your new field to the current year's set. +If there is not a set for POST\_\_EXPORT_FIELDS, create one. Add your new field to the current year's set. You may also have to update the `sales_log_export_service.rb` to correctly filter the year-specific fields. @@ -112,7 +112,7 @@ You will need to add a new `field_XXX` for the new field. In total, update the f You may also have to add some additional validation rules in this file. -Validation for ensuring that the value uploaded is one of the permitted options is handled automatically, using the question class as the original source of truth. +Validation for ensuring that the value uploaded is one of the permitted options is handled automatically, using the question class as the original source of truth. ### 9. Update unit tests diff --git a/docs/form/question.md b/docs/form/question.md index a40509757..fff9dd52d 100644 --- a/docs/form/question.md +++ b/docs/form/question.md @@ -6,7 +6,7 @@ nav_order: 4 # Question -*Updated for 2026.* +_Updated for 2026._ Questions are under the page level of the form definition. diff --git a/docs/setup.md b/docs/setup.md index d961462f9..87bab3201 100644 --- a/docs/setup.md +++ b/docs/setup.md @@ -20,9 +20,9 @@ We recommend using [nvm](https://github.com/nvm-sh/nvm) to manage NodeJS version ## Instructions for Windows users -If you are working on a windows machine, you will want to install the tools on [WSL](https://learn.microsoft.com/en-us/windows/wsl/install) as some of them are not native to windows. The instructions in these docs assume a Debian-based distribution, such as Ubuntu. +If you are working on a windows machine, you will want to install the tools on [WSL](https://learn.microsoft.com/en-us/windows/wsl/install) as some of them are not native to windows. The instructions in these docs assume a Debian-based distribution, such as Ubuntu. -*You will see a significant performance degradation if you are running the server on WSL whilst the files are on windows.* Thus, make sure to clone the repository into your WSL instance. +_You will see a significant performance degradation if you are running the server on WSL whilst the files are on windows._ Thus, make sure to clone the repository into your WSL instance. Some windows IDEs, such as [VSCode](https://code.visualstudio.com/docs/remote/wsl) and [RubyMine](jetbrains.com/help/ruby/remote-development-starting-page.html#run_in_wsl_ij) can connect you to WSL, which will allow you to develop as though the files were on the local windows filesystem. Ignore any reccommendations that you might see suggesting you keep the files on windows - our experience is that both tests and page loads are much slower when the files are on windows. From 622cc8b691ce9596161d96ffad153b956cb697f8 Mon Sep 17 00:00:00 2001 From: Nat Dean-Lewis Date: Mon, 2 Feb 2026 11:43:48 +0000 Subject: [PATCH 05/18] CLDC-NONE: update node version to correct value in setup.md --- docs/setup.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/setup.md b/docs/setup.md index 87bab3201..45ce7a39d 100644 --- a/docs/setup.md +++ b/docs/setup.md @@ -86,7 +86,7 @@ Some windows IDEs, such as [VSCode](https://code.visualstudio.com/docs/remote/ws 5. Install JavaScript dependencies - Note that we currently use node v16, which is no longer the latest LTS version so you will need to specify the version number when installing + Note that we currently use node v20, which is no longer the latest LTS version so you will need to specify the version number when installing macOS (using nvm): From d7c15ee3000f27b1154c2eac7fb67970fe3082e1 Mon Sep 17 00:00:00 2001 From: Nat Dean-Lewis Date: Mon, 2 Feb 2026 12:12:31 +0000 Subject: [PATCH 06/18] CLDC-NONE: make clear sales steps are generic for lettings too --- docs/dev_tasks/{new_sales_question.md => new_question.md} | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) rename docs/dev_tasks/{new_sales_question.md => new_question.md} (90%) diff --git a/docs/dev_tasks/new_sales_question.md b/docs/dev_tasks/new_question.md similarity index 90% rename from docs/dev_tasks/new_sales_question.md rename to docs/dev_tasks/new_question.md index f249b871e..24dc01d4c 100644 --- a/docs/dev_tasks/new_sales_question.md +++ b/docs/dev_tasks/new_question.md @@ -5,7 +5,9 @@ nav_order: 1 # New Sales Log Questions -Concerns adding a brand-new question to Sales Logs. This question will appear on the website as part of the Sales form and should be handled in Bulk Uploads. +Concerns adding a brand-new question to Lettings Logs or Sales Logs. This question will appear on the website as part of the Sales form and should be handled in Bulk Uploads. + +Note: this document focuses on Sales Logs but the steps are equivalent for Lettings Logs by replacing `sales` with `lettings` in file paths etc. Guide is up-to-date as of 2026. @@ -88,7 +90,7 @@ Copy the entry for an existing question and substitute in the text for your new ### 7. Include the new field in exports -The fields that get exported in CSVs and XMLs are defined in `app/services/exports/sales_log_export_constants.rb`. +The fields that get exported in CSVs and XMLs are defined in `app/services/exports/sales_log_export_constants.rb`. If there is not a set for POST\_\_EXPORT_FIELDS, create one. Add your new field to the current year's set. From f9ad054fce0f409788f8fd569c98cd2559ca9e88 Mon Sep 17 00:00:00 2001 From: Nat Dean-Lewis Date: Mon, 2 Feb 2026 12:13:05 +0000 Subject: [PATCH 07/18] CLDC-NONE: make clear sales steps are generic for lettings too --- docs/dev_tasks/new_question.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/dev_tasks/new_question.md b/docs/dev_tasks/new_question.md index 24dc01d4c..e1106c1eb 100644 --- a/docs/dev_tasks/new_question.md +++ b/docs/dev_tasks/new_question.md @@ -3,7 +3,7 @@ parent: Common dev tasks nav_order: 1 --- -# New Sales Log Questions +# New Questions Concerns adding a brand-new question to Lettings Logs or Sales Logs. This question will appear on the website as part of the Sales form and should be handled in Bulk Uploads. From 9aac02e674451bfd75ab4f2f4f8cfe1c521f5837 Mon Sep 17 00:00:00 2001 From: Nat Dean-Lewis Date: Mon, 2 Feb 2026 12:23:29 +0000 Subject: [PATCH 08/18] CLDC-NONE: add explanation of copy_key --- docs/form/question.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/form/question.md b/docs/form/question.md index fff9dd52d..baea21d21 100644 --- a/docs/form/question.md +++ b/docs/form/question.md @@ -53,7 +53,7 @@ Let's take a look at the properties in the `initialize` function.
The name of the field. This should correspond to a column in the database. In the example, the id is 'ppcodenk'.
copy_key
-
Unknown; requires investigation.
+
This specifies copy from config/locales/forms/... that should be associated with the question
type
Determines what type of question is rendered on the page. In the example, the question is a Radio Form so the app/views/form/_radio_question.html.erb partial will be rendered on the page when this question is displayed to the user
From fd05184418b448bcf21795eeb089d0b12b8d8274 Mon Sep 17 00:00:00 2001 From: Nat Dean-Lewis Date: Mon, 2 Feb 2026 12:28:48 +0000 Subject: [PATCH 09/18] CLDC-NONE: add note to update variable_definitions file --- docs/dev_tasks/new_question.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/docs/dev_tasks/new_question.md b/docs/dev_tasks/new_question.md index e1106c1eb..fb6f00710 100644 --- a/docs/dev_tasks/new_question.md +++ b/docs/dev_tasks/new_question.md @@ -118,4 +118,6 @@ Validation for ensuring that the value uploaded is one of the permitted options ### 9. Update unit tests -Create new test files for any new classes you have created. Update any test files for files that you have edited. +- Create new test files for any new classes you have created. Update any test files for files that you have edited. +- Update `spec/fixtures/variable_definitions/sales_download_25_26.csv` (for sales/lettings and for the relevant collection year) with the new question's field name and definition. + From 9e4408cf343040268846b1d1d91bf0bae914a88a Mon Sep 17 00:00:00 2001 From: Nat Dean-Lewis Date: Mon, 2 Feb 2026 12:34:31 +0000 Subject: [PATCH 10/18] CLDC-NONE: add note about page ids --- docs/dev_tasks/new_question.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/docs/dev_tasks/new_question.md b/docs/dev_tasks/new_question.md index fb6f00710..9c5c2003e 100644 --- a/docs/dev_tasks/new_question.md +++ b/docs/dev_tasks/new_question.md @@ -80,6 +80,8 @@ To make your new page only appear in the forms for the upcoming year, you wrap t (Form::Sales::Pages::SexRegisteredAtBirth1.new(nil, nil, self) if form.start_year_2026_or_later?), ``` +Note: the `@id` attribute of a page is what will be displayed in the url when visiting it. It must be unique within a collection year (i.e. two pages in 25/26 cannot share an ID, but two pages in different collection years can share an ID). + ### 6. Update the locale file The locale files define some of the text for the new question, including hints and the question itself. From 83de52ec8c78be0cfe7a3bd7879dcb0f5028975e Mon Sep 17 00:00:00 2001 From: Nat Dean-Lewis Date: Mon, 2 Feb 2026 13:49:13 +0000 Subject: [PATCH 11/18] CLDC-NONE: whitespace linting --- docs/dev_tasks/new_question.md | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/docs/dev_tasks/new_question.md b/docs/dev_tasks/new_question.md index 9c5c2003e..083652873 100644 --- a/docs/dev_tasks/new_question.md +++ b/docs/dev_tasks/new_question.md @@ -80,7 +80,7 @@ To make your new page only appear in the forms for the upcoming year, you wrap t (Form::Sales::Pages::SexRegisteredAtBirth1.new(nil, nil, self) if form.start_year_2026_or_later?), ``` -Note: the `@id` attribute of a page is what will be displayed in the url when visiting it. It must be unique within a collection year (i.e. two pages in 25/26 cannot share an ID, but two pages in different collection years can share an ID). +Note: the `@id` attribute of a page is what will be displayed in the url when visiting it. It must be unique within a collection year (i.e. two pages in 25/26 cannot share an ID, but two pages in different collection years can share an ID). ### 6. Update the locale file @@ -92,7 +92,7 @@ Copy the entry for an existing question and substitute in the text for your new ### 7. Include the new field in exports -The fields that get exported in CSVs and XMLs are defined in `app/services/exports/sales_log_export_constants.rb`. +The fields that get exported in CSVs and XMLs are defined in `app/services/exports/sales_log_export_constants.rb`. If there is not a set for POST\_\_EXPORT_FIELDS, create one. Add your new field to the current year's set. @@ -122,4 +122,3 @@ Validation for ensuring that the value uploaded is one of the permitted options - Create new test files for any new classes you have created. Update any test files for files that you have edited. - Update `spec/fixtures/variable_definitions/sales_download_25_26.csv` (for sales/lettings and for the relevant collection year) with the new question's field name and definition. - From 6fa34a4f26e626488adbb7167dd895bf95ed8cc5 Mon Sep 17 00:00:00 2001 From: samyou-softwire Date: Mon, 2 Mar 2026 09:29:35 +0000 Subject: [PATCH 12/18] CLDC-NONE: Finish question and page docs --- docs/form/page.md | 47 +++++++++++++++++++++---------------------- docs/form/question.md | 39 ++++++++++++++++++++++++++++++++--- 2 files changed, 59 insertions(+), 27 deletions(-) diff --git a/docs/form/page.md b/docs/form/page.md index 7e0607a70..28e55ed03 100644 --- a/docs/form/page.md +++ b/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 +
+
id
+
+The name of the field. This should correspond to a column in the database. In the example, the id is 'ppcodenk'. +
+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. +
+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.
+
depends_on
+
+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. +
+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. +
+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+.
+
questions
+
Array of questions to show on the page.
+
diff --git a/docs/form/question.md b/docs/form/question.md index baea21d21..8cc2d27a8 100644 --- a/docs/form/question.md +++ b/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
id
The name of the field. This should correspond to a column in the database. In the example, the id is 'ppcodenk'.
copy_key
-
This specifies copy from config/locales/forms/... that should be associated with the question
+
This specifies copy from config/locales/forms/... that should be associated with the question. Not normally needed, will be inferred as #{form.type}.#{subsection.copy_key}.#{id}.
type
Determines what type of question is rendered on the page. In the example, the question is a Radio Form so the app/views/form/_radio_question.html.erb partial will be rendered on the page when this question is displayed to the user
@@ -75,7 +75,17 @@ Let's take a look at the properties in the `initialize` function.
Determines which number gets rendered next to the question text on the question page and in the 'check your answers' page.
- 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. +
+ +
disable_clearing_if_not_routed_or_dynamic_answer_options
+
+ Questions that are not routed to will be cleared. Setting this to true will prevent this from happening. Normally can be replaced with implementing derived?. +
+ +
check_answers_card_number
+
+ 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 check_answers_card_title
@@ -109,3 +119,26 @@ end
inferred_answers
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.
+ +## Useful methods +
+
derived?
+
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 set_derived_fields!
+ +
get_extra_check_answer_value
+
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
+ +
label_from_value
+
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".
+ +
skip_question_in_form_flow?
+
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.
+
+ +## 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. + From 4cfd42575ba7ef8aa017543e3450888e75f9421b Mon Sep 17 00:00:00 2001 From: samyou-softwire Date: Tue, 24 Mar 2026 16:51:49 +0000 Subject: [PATCH 13/18] CLDC-NONE: Update docs gemfile deprecation warning, these dependencies won't be included in default ruby in future --- docs/Gemfile | 5 +++++ docs/Gemfile.lock | 6 ++++++ 2 files changed, 11 insertions(+) diff --git a/docs/Gemfile b/docs/Gemfile index 27acded18..db31c828b 100644 --- a/docs/Gemfile +++ b/docs/Gemfile @@ -7,3 +7,8 @@ end group :development do gem "webrick" end + +# used to be in standard library +gem "csv" +gem "base64" +gem "bigdecimal" diff --git a/docs/Gemfile.lock b/docs/Gemfile.lock index 9e014a8bd..9416df0df 100644 --- a/docs/Gemfile.lock +++ b/docs/Gemfile.lock @@ -8,6 +8,8 @@ GEM tzinfo (~> 2.0) addressable (2.8.1) public_suffix (>= 2.0.2, < 6.0) + base64 (0.3.0) + bigdecimal (4.0.1) coffee-script (2.4.1) coffee-script-source execjs @@ -15,6 +17,7 @@ GEM colorator (1.1.0) commonmarker (0.23.10) concurrent-ruby (1.2.2) + csv (3.3.5) dnsruby (1.61.9) simpleidn (~> 0.1) em-websocket (0.5.3) @@ -266,6 +269,9 @@ PLATFORMS x86_64-linux DEPENDENCIES + base64 + bigdecimal + csv github-pages webrick From b31c9f410b255f0d60326391d9e3bef0621d163e Mon Sep 17 00:00:00 2001 From: samyou-softwire Date: Tue, 24 Mar 2026 18:28:07 +0000 Subject: [PATCH 14/18] CLDC-NONE: Add extra library to install to setup --- docs/setup.md | 12 ++++++++++-- 1 file changed, 10 insertions(+), 2 deletions(-) diff --git a/docs/setup.md b/docs/setup.md index 45ce7a39d..2bc5e1815 100644 --- a/docs/setup.md +++ b/docs/setup.md @@ -116,9 +116,17 @@ Some windows IDEs, such as [VSCode](https://code.visualstudio.com/docs/remote/ws sudo mv geckodriver /usr/local/bin/ ``` -Also ensure you have firefox installed + Also ensure you have firefox installed -7. Clone the repo +7. Install libyaml-dev if on Linux + + Linux (Debian): + + ```bash + sudo apt install -y libyaml-dev + ``` + +8. Clone the repo ```bash git clone https://github.com/communitiesuk/submit-social-housing-lettings-and-sales-data.git From 4aad9b152abc3ebfd92824b39a53e2211f5f2825 Mon Sep 17 00:00:00 2001 From: samyou-softwire Date: Tue, 24 Mar 2026 18:28:26 +0000 Subject: [PATCH 15/18] CLDC-NONE: Update new question tutorial --- docs/dev_tasks/new_question.md | 69 ++++++++++++++++++++++++++++++---- 1 file changed, 62 insertions(+), 7 deletions(-) diff --git a/docs/dev_tasks/new_question.md b/docs/dev_tasks/new_question.md index 083652873..a6247d2b9 100644 --- a/docs/dev_tasks/new_question.md +++ b/docs/dev_tasks/new_question.md @@ -82,6 +82,8 @@ To make your new page only appear in the forms for the upcoming year, you wrap t Note: the `@id` attribute of a page is what will be displayed in the url when visiting it. It must be unique within a collection year (i.e. two pages in 25/26 cannot share an ID, but two pages in different collection years can share an ID). +Do not use a `depends_on` block for showing a page on a specific year. + ### 6. Update the locale file The locale files define some of the text for the new question, including hints and the question itself. @@ -90,19 +92,31 @@ Locale files can be found in `config/locales/forms//sales/` and there is o Copy the entry for an existing question and substitute in the text for your new one. -### 7. Include the new field in exports +The locale config for a question by default is laid out like en.forms.\.\
.\.\. We assume 1 question per page. If there is more than one question per page you will need to add these as subsections in the page locale and set up a custom @copy_key property in the constructor. + +### 7. Add validations + +Add validation methods to the appropriate file. For example `app/models/validations/_validations.rb` or `app/models/validations/sales/_validations.rb` for sales. Any method in these files with a name starting `validate` will be automatically called. Adding an error to the record (log) will show an error on the frontend and the BU. + +An error is added by calling `record.errors.add :, I18n.t("validations.")`. You'll need to add the key where appropriate to the relevant locale file inside `config/locales/validations/...`. -The fields that get exported in CSVs and XMLs are defined in `app/services/exports/sales_log_export_constants.rb`. +Make sure to add errors to all relevant question IDs that can trigger the error. Note that questions on CORE can be answered in any order and amended at will so you cannot make assumptions on order of questions answered. CORE uses the question ID to show the error to the user on the page. If you don't add errors to all relevant question IDs, the user will not see an error but not be able to submit. -If there is not a set for POST\_\_EXPORT_FIELDS, create one. Add your new field to the current year's set. +### 8. Include the new field in exports -You may also have to update the `sales_log_export_service.rb` to correctly filter the year-specific fields. +The fields that get exported in CSVs and XMLs are defined in `app/services/exports/\_log_export_constants.rb`. -### 8. Update the bulk upload row parser +If there is not a set for `YEAR__EXPORT_FIELDS`, create one. Add your new field to the current year's set. + +You may also have to update the `_log_export_service.rb` to correctly filter the year-specific fields. + +### 9. Update the bulk upload parser This will allow bulk upload files to save the new field to the database. -You can find the relevant file at `app/services/bulk_upload/sales/year/row_parser.rb`. +You can find the relevant file at `app/services/bulk_upload//year/row_parser.rb`. + +If doing this work during yearly rebuild, add this new field as the last field in the file. It's much easier to have a single task at the end to correct all the field numbers. You will need to add a new `field_XXX` for the new field. In total, update the following places: @@ -113,12 +127,53 @@ You will need to add a new `field_XXX` for the new field. In total, update the f ``` - Add the new field to `field_mapping_for_errors` with the name of the field in the database. - Add the new field to `attributes_for_log` with the name of the field in the database. +- If the field needs to be case-insensitive, add to `CASE_INSENSITIVE_FIELDS`. You may also have to add some additional validation rules in this file. +We should try and keep validations in the BU few, and leave to validations on the log which you set up earlier. Validations suitable for BU would be those that are specific to the bulk upload process. For instance, validating the input format where we allow "R". + Validation for ensuring that the value uploaded is one of the permitted options is handled automatically, using the question class as the original source of truth. -### 9. Update unit tests +Make sure that if a value fails a BU validation, then a valid value is not written to the log in the `attributes_for_log` method. If a BU produces a log that is 'complete', all errors will be ignored. Errors on fields the log considers 'valid' are ignored. So, you must make sure the log is incomplete for the user to see the error report. Normally you'll do this intuitively as invalid fields will mean you won't have a valid value. + +You'll also need to update the field count in `app/services/bulk_upload//year/csv_parser.rb`, as well as the `cols` method. + +### 10. Update unit tests - Create new test files for any new classes you have created. Update any test files for files that you have edited. - Update `spec/fixtures/variable_definitions/sales_download_25_26.csv` (for sales/lettings and for the relevant collection year) with the new question's field name and definition. + +### 11. Update factory file + +In `spec/factories` there are a series of factory files. These generate populated objects for use in tests. We also use them on CORE for the buttons that generate completed logs. + +You will need to update the factory file for the relevant log type to include the new field. Don't worry about gating it to be year specific, old year questions will be ignored. + +### 12. Update reference example BU file + +In `spec/fixtures/files` we keep a sample BU file for a range of years and both log types. This gives us a fixed reference for a valid BU file. Make sure to update this and test that you can upload it locally. + +### 13. Update auto generated example BU file + +In the `app/helpers_bulk_upload/_log_to_csv.rb` file we maintain functions that convert a log into a BU file. This is used by tests and by the button on CORE to download an example BU file. + +Make sure that this file is updated to include the new field in the relevant `to__row` method. You don't need to update the field numbers. + +If you're adding a new method for this year, copy paste the previous year's row method. This'll avoid some nasty merge conflicts down the line. + +Make sure you can download this test file and then upload it again. + +### 14. Check the CSV download service + +Users are able to download CSV exports of logs. This is handled by `app/services/csv/_log_csv_service.rb`. It should automatically include the new field, but worth checking locally that you're happy with both the codes and labels download. + +### 15. Add test CSV export definitions + +In `spec/fixtures/variable_definitions` there are a series of CSV files that define the names of fields. These are normally set in the UI by CORE but to make our tests more authentic we maintain labels for use in the tests. + +If making one for the new year, just add a new file in that folder. The CSV export tests will pick it up automatically. + +### 16. Check log export service + +We export an XML representation of all logs made that day nightly. This is handled by `app/services/exports/_log_export_service.rb`. It should automatically include the new field, though make sure the spec file for this service passes. You will need to update `apply_cds_transformation` if the column name requested in the export doesn't match the database. From c56cb6c6824b30e3e83c8d32071829352af07217 Mon Sep 17 00:00:00 2001 From: samyou-softwire Date: Tue, 24 Mar 2026 18:31:33 +0000 Subject: [PATCH 16/18] CLDC-NONE: Lint --- docs/Gemfile | 2 +- docs/form/page.md | 1 + docs/form/question.md | 3 ++- 3 files changed, 4 insertions(+), 2 deletions(-) diff --git a/docs/Gemfile b/docs/Gemfile index db31c828b..079c53771 100644 --- a/docs/Gemfile +++ b/docs/Gemfile @@ -9,6 +9,6 @@ group :development do end # used to be in standard library -gem "csv" gem "base64" gem "bigdecimal" +gem "csv" diff --git a/docs/form/page.md b/docs/form/page.md index 28e55ed03..cb22fed4f 100644 --- a/docs/form/page.md +++ b/docs/form/page.md @@ -37,6 +37,7 @@ It’s worth noting that like subsections a page can also have a `depends_on` wh Pages can contain one or more [questions](question). ## Useful Properties +
id
diff --git a/docs/form/question.md b/docs/form/question.md index 8cc2d27a8..e7694338b 100644 --- a/docs/form/question.md +++ b/docs/form/question.md @@ -121,6 +121,7 @@ end
## Useful methods +
derived?
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 set_derived_fields!
@@ -136,9 +137,9 @@ end
## 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. - From 53a4797d98b1dc8d07c9486d221e244714a2a446 Mon Sep 17 00:00:00 2001 From: samyou-softwire Date: Wed, 25 Mar 2026 09:44:54 +0000 Subject: [PATCH 17/18] CLDC-NONE: Final tweaks to new question --- docs/dev_tasks/new_question.md | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) diff --git a/docs/dev_tasks/new_question.md b/docs/dev_tasks/new_question.md index a6247d2b9..23fd68f31 100644 --- a/docs/dev_tasks/new_question.md +++ b/docs/dev_tasks/new_question.md @@ -5,9 +5,7 @@ nav_order: 1 # New Questions -Concerns adding a brand-new question to Lettings Logs or Sales Logs. This question will appear on the website as part of the Sales form and should be handled in Bulk Uploads. - -Note: this document focuses on Sales Logs but the steps are equivalent for Lettings Logs by replacing `sales` with `lettings` in file paths etc. +Concerns adding a brand-new question to Lettings Logs or Sales Logs. This question will appear on the website as part of the form and should be handled in Bulk Uploads. It will be exported as either a CSV download for users or XML export for automated ingestion by downstream users. Guide is up-to-date as of 2026. @@ -50,17 +48,19 @@ This will update `schema.rb`. You should not edit `schema.rb` directly. This will define the question that gets rendered on the online form. -Existing question classes can be found in `app/models/form/sales/questions/`. Depending on the type of question (checkboxes, radio groups, free-text fields), there will almost certainly be an existing question class that you can refer to as a guide. +Existing question classes can be found in `app/models/form//questions/`. Depending on the type of question (checkboxes, radio groups, free-text fields), there will almost certainly be an existing question class that you can refer to as a guide. For example, if you need to create a new radio form, then you may want to copy `armed_forces.rb`. +Sometimes a question will appear in multiple places in the form, or have multiple similar forms. Historically on CORE we'd make a different question class for each, but now we think it's more maintainable to add a small amount of logic to the question to make it dynamic. + See also: [Question]({% link form/question.md %}) ### 4. Create a new page class This creates the page that your new question will be rendered on. -Existing page classes can be found in `app/models/form/sales/pages`. +Existing page classes can be found in `app/models/form//pages`. Usually there is only one question per page, but in some cases there may be multiple. It may not be necessary to create a new page if the new question is being added to an existing one. @@ -70,7 +70,7 @@ See also: [Page]({% link form/page.md %}) Without this step, your new page will not be inserted into the form! -Subsections can be found in `app/models/form/sales/subsections`. +Subsections can be found in `app/models/form//subsections`. You will want to add your new page to the appropriate place in the list returned by `def pages`. @@ -88,11 +88,11 @@ Do not use a `depends_on` block for showing a page on a specific year. The locale files define some of the text for the new question, including hints and the question itself. -Locale files can be found in `config/locales/forms//sales/` and there is one locale file for each form subsection. +Locale files can be found in `config/locales/forms///` and there is one locale file for each form subsection. Copy the entry for an existing question and substitute in the text for your new one. -The locale config for a question by default is laid out like en.forms.\.\.\.\. We assume 1 question per page. If there is more than one question per page you will need to add these as subsections in the page locale and set up a custom @copy_key property in the constructor. +The locale config for a question by default is laid out like `en.forms.\.\.\.\`. We assume 1 question per page. If there is more than one question per page you will need to add these as subsections in the page locale and set up a custom @copy_key property in the constructor. ### 7. Add validations @@ -131,7 +131,7 @@ You will need to add a new `field_XXX` for the new field. In total, update the f You may also have to add some additional validation rules in this file. -We should try and keep validations in the BU few, and leave to validations on the log which you set up earlier. Validations suitable for BU would be those that are specific to the bulk upload process. For instance, validating the input format where we allow "R". +We should try and keep validations in the BU few, and leave to validations on the log which you set up earlier. Only add validation specific to the csv format. For instance, validating the input format where we allow "R". Validation for ensuring that the value uploaded is one of the permitted options is handled automatically, using the question class as the original source of truth. From f26ee3c5b28f6f53abb410779ee3a3aa19e47481 Mon Sep 17 00:00:00 2001 From: samyou-softwire Date: Wed, 25 Mar 2026 09:50:15 +0000 Subject: [PATCH 18/18] CLDC-NONE: Document check_answers_card_title --- docs/form/question.md | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/docs/form/question.md b/docs/form/question.md index e7694338b..17fa64aa5 100644 --- a/docs/form/question.md +++ b/docs/form/question.md @@ -87,6 +87,11 @@ end
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 check_answers_card_title
+ +
check_answers_card_title
+
+ If set to non nil, on the CYA this question will be put in a box with this title. If multiple questions set the same check_answers_card_title, they will be grouped. +
Another example shows us some fields that are used when we want to infer the answers to one question based on a user's answers to another question. This can allow the user to have to answer fewer questions, lowering their total number of clicks.