@planning-inspectorate/dynamic-forms 3.20.5 → 3.21.0

package/README.md

@@ -82,6 +82,55 @@ 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) 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
+}
+```
+
+
 ### Conditions
 
 Conditions are used to show/hide questions based on the answers to other questions. There are fluent methods on a 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.21.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/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) {

package/src/components/single-line-input/index.njk

@@ -38,6 +38,8 @@
                             text: errors[question.fieldName].msg
                         },
                         classes: question.classes,
+                        prefix: question.prefix,
+                        suffix: question.suffix,
                         attributes: question.attributes,
                         type: question.type,
                         autocomplete: question.autocomplete
@@ -62,6 +64,8 @@
                             text: errors[question.fieldName].msg
                         },
                         classes: question.classes,
+                        prefix: question.prefix,
+                        suffix: question.suffix,
                         attributes: question.attributes,
                         type: question.type,
                         autocomplete: question.autocomplete

package/src/components/single-line-input/question.d.ts

@@ -10,6 +10,8 @@ export class SingleLineInputQuestion extends Question {
     inputAttributes: Record<string, string>;
     label: string | undefined;
     classes: string;
+    prefix: import("#typedefs/question-props.d.ts").Affix | undefined;
+    suffix: import("#typedefs/question-props.d.ts").Affix | undefined;
 }
 export default SingleLineInputQuestion;
 import { Question } from '#question';

package/src/components/single-line-input/question.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"question.d.ts","sourceRoot":"","sources":["question.js"],"names":[],"mappings":"AAEA;;GAEG;AACH;IAIC;;OAEG;IACH,oBAFW,OAAO,+BAA+B,EAAE,6BAA6B,EAW/E;IAfD,qCAAqC;IACrC,iBADW,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CACjB;IAWf,0BAAyB;IAEzB,gBAAmC;CAepC;;yBAnCwB,WAAW"}
+{"version":3,"file":"question.d.ts","sourceRoot":"","sources":["question.js"],"names":[],"mappings":"AAEA;;GAEG;AACH;IAIC;;OAEG;IACH,oBAFW,OAAO,+BAA+B,EAAE,6BAA6B,EAa/E;IAjBD,qCAAqC;IACrC,iBADW,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CACjB;IAWf,0BAAyB;IAEzB,gBAAmC;IACnC,kEAA2B;IAC3B,kEAA2B;CAiB5B;;yBAvCwB,WAAW"}

package/src/components/single-line-input/question.js

@@ -19,6 +19,8 @@ export class SingleLineInputQuestion extends Question {
 		this.label = params.label;
 		this.inputAttributes = params.inputAttributes || {};
 		this.classes = params.classes || '';
+		this.prefix = params.prefix;
+		this.suffix = params.suffix;
 	}
 
 	/**
@@ -32,6 +34,8 @@ export class SingleLineInputQuestion extends Question {
 		viewModel.question.type = type;
 
 		viewModel.question.classes = this.classes;
+		viewModel.question.prefix = this.prefix;
+		viewModel.question.suffix = this.suffix;
 	}
 }
 

package/src/components/single-line-input/question.test.js

@@ -11,6 +11,8 @@ describe('./src/dynamic-forms/components/single-line-input/question.js', () => {
 		const HTML = '/path/to/html.njk';
 		const HINT = 'hint';
 		const LABEL = 'A label';
+		const PREFIX = { text: '£', classes: 'govuk-!-font-weight-bold' };
+		const SUFFIX = { text: 'per year' };
 
 		const question = new SingleLineInputQuestion({
 			title: TITLE,
@@ -20,6 +22,8 @@ describe('./src/dynamic-forms/components/single-line-input/question.js', () => {
 			html: HTML,
 			hint: HINT,
 			label: LABEL,
+			prefix: PREFIX,
+			suffix: SUFFIX,
 			autocomplete: FIELDNAME
 		});
 
@@ -31,6 +35,8 @@ describe('./src/dynamic-forms/components/single-line-input/question.js', () => {
 		assert.strictEqual(question.html, HTML);
 		assert.strictEqual(question.hint, HINT);
 		assert.strictEqual(question.label, LABEL);
+		assert.strictEqual(question.prefix, PREFIX);
+		assert.strictEqual(question.suffix, SUFFIX);
 		assert.strictEqual(question.autocomplete, FIELDNAME);
 	});
 });

package/src/components/unit-option-entry/question.d.ts

@@ -54,7 +54,7 @@ export class UnitOptionEntryQuestion 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<{ answers: Record<string, unknown> }>}
      */ getDataToSave(req: import("express").Request, journeyResponse: JourneyResponse): Promise<{
         answers: Record<string, unknown>;

package/src/components/unit-option-entry/question.js

@@ -125,7 +125,7 @@ export class UnitOptionEntryQuestion 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<{ answers: Record<string, unknown> }>}
 	 */ //eslint-disable-next-line no-unused-vars -- journeyResponse kept for other questions to use
 	async getDataToSave(req, journeyResponse) {

package/src/questions/options-question.js

@@ -147,7 +147,7 @@ export class OptionsQuestion extends Question {
 	/**
 	 * Get the data to save from the request, returns an object of answers
 	 * @param {import('express').Request} req
-	 * @param {import('../journey/journey-response.js').JourneyResponse} journeyResponse - current journey response, modified with the new answers
+	 * @param {import('../journey/journey-response.js').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/typedefs/question-props.d.ts

@@ -68,7 +68,7 @@ export type SelectableOption = {
 	attributes?: Record<string, string>;
 	behaviour?: 'exclusive';
 	conditional?: {
-		question: string;
+		question?: string;
 		type: string;
 		fieldName: string;
 		inputClasses?: string;
@@ -261,6 +261,8 @@ export type SingleLineInputQuestionParams = CommonQuestionParams & {
 	inputAttributes?: Record<string, string>; // HTML attributes to add to the input
 	label?: string; // if defined this will show as a label for the input and the question will just be a standard h1
 	classes?: string; // HTML classes to add to the input
+	prefix?: Affix;
+	suffix?: Affix;
 };
 
 type SingleLineInputQuestionProps = SingleLineInputQuestionParams & {