@planning-inspectorate/dynamic-forms 3.20.5 → 3.22.0

package/README.md

@@ -82,6 +82,100 @@ The controllers available are:
 | buildSave      | Returns a controller to handle saving the answer and either redirecting to the next question or show any validation errors if present. Accepts a save function. |
 | list/buildList | Renders a check-your-answers page showing all the answers, links to change any answer, and a button to submit the answers.                                      |
 
+#### Saving answers
+
+The `buildSave` controller accepts a `SaveDataFn` which is passed the context required to save the answer(s). To save answers to session during a journey, a `SaveDataFn` implementation is provided called `saveDataToSession`.
+
+For other use cases, write a custom `SaveDataFn`. A basic implementation (if you are not using ManageList or DynamicSection) needs to save the answers passed in as `data.answers`, which is an object whose keys are the question field names, and the values are the answers. For example:
+
+```typescript
+const update: SaveDataFn = async ({data}) => {
+    const answers = data.answers;
+    
+    console.log('saving', answers);
+    
+    // TODO: map to database
+    // TODO: write to database
+}
+```
+
+To support `ManageList` questions as well, handle the `isManageListItem`, `manageListQuestionFieldName`, `manageListItemRemove` parameters. For example:
+
+```typescript
+const update: SaveDataFn = async ({data, req, isManageListItem, manageListQuestionFieldName, manageListItemRemove}) => {
+    if (isManageListItem) {
+        const update = {
+            id: req.params.manageListItemId,
+            ...data.answers
+        };
+
+        console.log('saving', update);
+        // TODO: map to database
+        // TODO: write to database
+        return;
+    } else if (manageListItemRemove) {
+        const id = req.params.manageListItemId;
+        // identify which type of item it is via the field name
+        const type = manageListQuestionFieldName;
+        console.log('removing item', {id, type});
+        // TODO: delete from database
+        return;
+    }
+    const answers = data.answers;
+    
+    console.log('saving', answers);
+    
+    // TODO: map to database
+    // TODO: write to database
+}
+```
+
+To support `DynamicSection`, handle `isDynamicSection`, `dynamicSectionFieldName`, and `dynamicSectionId`. The implementation is very similar to the manage lists and the logic can be combined. For example:
+
+```typescript
+const update: SaveDataFn = async ({
+        data,
+        req,
+        isManageListItem,
+        manageListQuestionFieldName,
+        manageListItemRemove,
+        isDynamicSection,
+        dynamicSectionFieldName,
+        dynamicSectionId
+    }) => {
+    if (isManageListItem || isDynamicSection) {
+        // manage list and dynamic sections can be handled the same, just with different properties
+        // for the fieldName and item id
+        const fieldName = isManageListItem ? manageListQuestionFieldName : dynamicSectionFieldName;
+        const itemId = isManageListItem ? req.params.manageListItemId : dynamicSectionId;
+        
+        const update = {
+            id: itemId,
+            ...data.answers
+        };
+
+        console.log('saving', update);
+        // TODO: map to database
+        // TODO: write to database
+        return;
+    } else if (manageListItemRemove) {
+        const id = req.params.manageListItemId;
+        // identify which type of item it is via the field name
+        const type = manageListQuestionFieldName;
+        console.log('removing item', {id, type});
+        // TODO: delete from database
+        return;
+    }
+    const answers = data.answers;
+    
+    console.log('saving', answers);
+    
+    // TODO: map to database
+    // TODO: write to database
+}
+```
+
+
 ### Conditions
 
 Conditions are used to show/hide questions based on the answers to other questions. There are fluent methods on a Section
@@ -221,6 +315,12 @@ formatSummaryValue: ({ formattedAnswer, journey }) => {
 
 > **Note:** `formattedAnswer` is already escaped by dynamic-forms; you are responsible for escaping any additional user-controlled values you include (for example `answer` or values read from `journey.response.answers`).
 
+### Other features
+
+See documentation in [docs](./docs), including:
+
+* [Dynamic Sections](./docs/Dynamic%20Sections.md)
+
 ## Contributing
 
 When contributing to this package, ensure changes are generic and not service-specific. Speak to the R&D devs if you are not sure. Prefer configuration over hardcoding values, and ensure the code is well documented. 

package/docs/Dynamic Sections.md

@@ -0,0 +1,47 @@
+# Dynamic Sections
+
+Use a dynamic section for sections which are generated from an array of objects.
+
+This can be useful for adding a section for each entry in a ManageList, or each row in a database. The controller logic, when encountering a DynamicSection, will check for answers within `journeyResponse.answers[section.fieldName]` which is expected to be an array, and it will look for an object with an `id` property matching the sections' segment.
+
+For example, considering a dynamic section for a Person object:
+
+```typescript
+function createPersonSection(person) {
+	return new DynamicSection(person.name, person.id, 'people').addQuestion(questions.name);
+	// ... other questions
+}
+```
+
+Then the answers object should be of the form:
+
+```typescript
+answers = {
+	myField: 'some answer', // a normal question field
+	people: [
+		// dynamic section fields
+		{ id: 'person-id-1', name: 'Grogu' },
+		{ id: 'person-id-2', name: 'Mando' }
+	]
+};
+```
+
+## Saving data
+
+When using with `buildSave`, be sure to handle the parameters: `isDynamicSection`, `dynamicSectionId`,`dynamicSectionFieldName`. The implementation `buildSaveDataToSession` (in `session-answer-store.js`) may be a useful reference.
+
+```typescript
+const buildSaveFn: SaveDataFn = async (params) => {
+	if (params.isDynamicSection) {
+		// saving a response within a dynamic section
+		const itemId = params.dynamicSectionId;
+		const listType = params.dynamicSectionFieldName;
+
+		// some logic to save the data for this item
+	}
+};
+```
+
+## Conditions
+
+Question conditions can only access other questions within the section.

package/docs/Getting Started.md

@@ -78,7 +78,7 @@ Dynamic forms requires two templates to work for rendering questions and renderi
 ### Journey (or question) template
 
 The journey template is used for question pages. It must include a block called `dynQuestionContent`, and a block called `head` (which the default gov.uk template has).
-It should also include the rendering of the errorSummary component. The path to this template is configured via the `journeyTemplate` property on a Journey.
+It should also include the rendering of the errorSummary component, and optionally the back link. The path to this template is configured via the `journeyTemplate` property on a Journey.
 
 For example:
 
@@ -87,7 +87,13 @@ e.g.
 ```nunjucks
 {% extends "govuk/template.njk" %}
 
-{% block beforeContent %}
+{% from "govuk/components/back-link/macro.njk" import govukBackLink %}
+{% from "govuk/components/error-summary/macro.njk" import govukErrorSummary %}
+
+{% block containerStart %}
+    {% if backLink %}
+        {{ govukBackLink({ href: backLink }) }}
+    {% endif %}
     {% if errorSummary %}
         <div class="govuk-grid-row">
             <div class="govuk-grid-column-two-thirds">

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@planning-inspectorate/dynamic-forms",
-  "version": "3.20.5",
+  "version": "3.22.0",
   "description": "This package is for building GDS forms using a configuration-based approach.",
   "main": "./src/index.js",
   "type": "module",

package/src/components/boolean/question.d.ts

@@ -17,7 +17,7 @@ export class BooleanQuestion extends RadioQuestion {
     /**
      * Get the data to save from the request, returns an object of answers
      * @param {import('express').Request} req
-     * @param {JourneyResponse} journeyResponse - current journey response, modified with the new answers
+     * @param {JourneyResponse} journeyResponse - current journey response
      * @returns {Promise<{ answers: Record<string, unknown> }>}
      */ getDataToSave(req: import("express").Request, journeyResponse: JourneyResponse): Promise<{
         answers: Record<string, unknown>;

package/src/components/boolean/question.js

@@ -97,7 +97,7 @@ export class BooleanQuestion extends RadioQuestion {
 	/**
 	 * Get the data to save from the request, returns an object of answers
 	 * @param {import('express').Request} req
-	 * @param {JourneyResponse} journeyResponse - current journey response, modified with the new answers
+	 * @param {JourneyResponse} journeyResponse - current journey response
 	 * @returns {Promise<{ answers: Record<string, unknown> }>}
 	 */ //eslint-disable-next-line no-unused-vars -- journeyResponse kept for other questions to use
 	async getDataToSave(req, journeyResponse) {

package/src/components/date/question.d.ts

@@ -10,7 +10,7 @@ export class DateQuestion extends Question {
     /**
      * Get the data to save from the request, returns an object of answers
      * @param {import('express').Request} req
-     * @param {import('#journey-response').JourneyResponse} journeyResponse - current journey response, modified with the new answers
+     * @param {import('#journey-response').JourneyResponse} journeyResponse - current journey response
      * @returns {Promise.<Object>}
      */ getDataToSave(req: import("express").Request, journeyResponse: import("#journey-response").JourneyResponse): Promise<Object>;
     answerForViewModel(answers: any, isPayload: any): {

package/src/components/date/question.js

@@ -29,7 +29,7 @@ export class DateQuestion extends Question {
 	/**
 	 * Get the data to save from the request, returns an object of answers
 	 * @param {import('express').Request} req
-	 * @param {import('#journey-response').JourneyResponse} journeyResponse - current journey response, modified with the new answers
+	 * @param {import('#journey-response').JourneyResponse} journeyResponse - current journey response
 	 * @returns {Promise.<Object>}
 	 */ //eslint-disable-next-line no-unused-vars -- journeyResponse kept for other questions to use
 	async getDataToSave(req, journeyResponse) {

package/src/components/date-period/question.d.ts

@@ -19,7 +19,7 @@ export class DatePeriodQuestion extends Question {
     /**
      * Get the data to save from the request, returns an object of answers
      * @param {import('express').Request} req
-     * @param {import('#journey-response').JourneyResponse} journeyResponse - current journey response, modified with the new answers
+     * @param {import('#journey-response').JourneyResponse} journeyResponse - current journey response
      * @returns {Promise.<Object>}
      */ getDataToSave(req: import("express").Request, journeyResponse: import("#journey-response").JourneyResponse): Promise<Object>;
     answerForViewModel(answers: any, isPayload: any): {

package/src/components/date-period/question.js

@@ -54,7 +54,7 @@ export class DatePeriodQuestion extends Question {
 	/**
 	 * Get the data to save from the request, returns an object of answers
 	 * @param {import('express').Request} req
-	 * @param {import('#journey-response').JourneyResponse} journeyResponse - current journey response, modified with the new answers
+	 * @param {import('#journey-response').JourneyResponse} journeyResponse - current journey response
 	 * @returns {Promise.<Object>}
 	 */ //eslint-disable-next-line no-unused-vars -- journeyResponse kept for other questions to use
 	async getDataToSave(req, journeyResponse) {

package/src/components/date-time/question.d.ts

@@ -10,7 +10,7 @@ export class DateTimeQuestion extends Question {
     /**
      * Get the data to save from the request, returns an object of answers
      * @param {import('express').Request} req
-     * @param {JourneyResponse} journeyResponse - current journey response, modified with the new answers
+     * @param {JourneyResponse} journeyResponse - current journey response
      * @returns {Promise.<Object>}
      */ getDataToSave(req: import("express").Request, journeyResponse: JourneyResponse): Promise<Object>;
     answerForViewModel(answers: any, isPayload: any): {

package/src/components/date-time/question.js

@@ -38,7 +38,7 @@ export class DateTimeQuestion extends Question {
 	/**
 	 * Get the data to save from the request, returns an object of answers
 	 * @param {import('express').Request} req
-	 * @param {JourneyResponse} journeyResponse - current journey response, modified with the new answers
+	 * @param {JourneyResponse} journeyResponse - current journey response
 	 * @returns {Promise.<Object>}
 	 */ //eslint-disable-next-line no-unused-vars -- journeyResponse kept for other questions to use
 	async getDataToSave(req, journeyResponse) {

package/src/components/manage-list/question.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"question.d.ts","sourceRoot":"","sources":["question.js"],"names":[],"mappings":"AAKA;;;;;;GAMG;AAEH;IAOC;;OAEG;IACH,oBAFW,OAAO,+BAA+B,EAAE,wBAAwB,EAe1E;IAcD,wCAEC;IAyDD;;;;OAMC;IAED;;OAEG;IACH,+BAkBC;IAED,4EAQC;IAoCD,yDAEC;IATD,kDAKC;;CAKD;;;;;;mBApLa,MAAM;;;;;;;;;;;;;;yBAPK,WAAW"}
+{"version":3,"file":"question.d.ts","sourceRoot":"","sources":["question.js"],"names":[],"mappings":"AAKA;;;;;;GAMG;AAEH;IAOC;;OAEG;IACH,oBAFW,OAAO,+BAA+B,EAAE,wBAAwB,EAe1E;IAcD,wCAEC;IA8DD;;;;OAMC;IAED;;OAEG;IACH,+BAkBC;IAED,4EAQC;IAoCD,yDAEC;IATD,kDAKC;;CAKD;;;;;;mBAzLa,MAAM;;;;;;;;;;;;;;yBAPK,WAAW"}

package/src/components/manage-list/question.js

@@ -85,6 +85,11 @@ export class ManageListQuestion extends Question {
 		}
 		const mockJourney = {
 			getCurrentQuestionUrl() {},
+			responseForSection() {
+				// this function is already passed the array-item
+				// call to formatAnswerForSummary may use responseForSection so we implement here
+				return this.response;
+			},
 			response: {
 				answers: answer
 			}

package/src/components/manage-list/question.test.js

@@ -54,7 +54,9 @@ describe('components/manage-list/question', () => {
 		const innerQ2 = {
 			url: 'second-question',
 			title: 'Q 2',
-			formatAnswerForSummary() {
+			formatAnswerForSummary(sectionSegment, journey) {
+				// simulate a question which may call responseForSection, such as multi field input
+				journey.responseForSection(sectionSegment);
 				return [{ value: 'mock answer 2' }];
 			}
 		};

package/src/components/multi-field-input/question.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"question.d.ts","sourceRoot":"","sources":["question.js"],"names":[],"mappings":"AAIA;;GAEG;AACH;IACC;;OAEG;IACH,8CAFW,OAAO,+BAA+B,EAAE,6BAA6B,EAe/E;IAJC,kEAA8B;IAchC;;;;;;;;;;;;;;;QAOC;IA4CD;;;;;OAKG;IACH,uCAJW,MAAM,WACN,OAAO,UAAU,EAAE,OAAO,GACxB,OAAO,+BAA+B,EAAE,UAAU,EAAE,CAuChE;;CAsDD;;yBAtLwB,WAAW"}
+{"version":3,"file":"question.d.ts","sourceRoot":"","sources":["question.js"],"names":[],"mappings":"AAIA;;GAEG;AACH;IACC;;OAEG;IACH,8CAFW,OAAO,+BAA+B,EAAE,6BAA6B,EAe/E;IAJC,kEAA8B;IAchC;;;;;;;;;;;;;;;QAOC;IA4CD;;;;;OAKG;IACH,uCAJW,MAAM,WACN,OAAO,UAAU,EAAE,OAAO,GACxB,OAAO,+BAA+B,EAAE,UAAU,EAAE,CAyChE;;CAsDD;;yBAxLwB,WAAW"}

package/src/components/multi-field-input/question.js

@@ -44,7 +44,7 @@ export class MultiFieldInputQuestion extends Question {
 	/**
 	 * Get the data to save from the request, returns an object of answers
 	 * @param {import('express').Request} req
-	 * @param {import('#journey-response').JourneyResponse} journeyResponse - current journey response, modified with the new answers
+	 * @param {import('#journey-response').JourneyResponse} journeyResponse - current journey response
 	 * @returns {Promise<{ answers: Record<string, unknown> }>}
 	 */ //eslint-disable-next-line no-unused-vars -- journeyResponse kept for other questions to use
 	async getDataToSave(req, journeyResponse) {
@@ -90,8 +90,10 @@ export class MultiFieldInputQuestion extends Question {
 	 * @returns {import('#typedefs/question-types.d.ts').SummaryRow[]}
 	 */
 	formatAnswerForSummary(sectionSegment, journey) {
+		// get the response/answers for the section we're in - which might be a dynamic section
+		const response = journey.responseForSection(sectionSegment);
 		// Handle unanswered case - delegate to parent for notStartedText
-		if (this.#allQuestionsUnanswered(journey)) {
+		if (this.#allQuestionsUnanswered(response)) {
 			return super.formatAnswerForSummary(sectionSegment, journey, null);
 		}
 
@@ -99,7 +101,7 @@ export class MultiFieldInputQuestion extends Question {
 		const defaultJoinString = this.isInManageListSection ? '\n' : '<br>';
 
 		let summaryDetails = this.inputFields.reduce((accumulator, field) => {
-			const rawAnswer = journey.response.answers[field.fieldName];
+			const rawAnswer = response.answers[field.fieldName];
 			if (rawAnswer === undefined || rawAnswer === null || rawAnswer === '') return accumulator;
 
 			const formatted = this.#formatFieldForSummary(rawAnswer, field, journey, sectionSegment);
@@ -159,11 +161,11 @@ export class MultiFieldInputQuestion extends Question {
 
 	/**
 	 * checks whether any answers have been provided for input field questions
-	 * @param {import('#journey').Journey} journey
+	 * @param {import('#journey-response').JourneyResponse} response
 	 * @returns {boolean}
 	 */
-	#allQuestionsUnanswered(journey) {
-		return this.inputFields.every((field) => journey.response.answers[field.fieldName] === undefined);
+	#allQuestionsUnanswered(response) {
+		return this.inputFields.every((field) => response.answers[field.fieldName] === undefined);
 	}
 
 	/**