@defra/forms-engine-plugin 1.3.0 → 1.4.0

package/src/server/plugins/engine/models/SummaryViewModel.ts

@@ -51,6 +51,7 @@ export class SummaryViewModel {
   serviceUrl: string
   hasMissingNotificationEmail?: boolean
   components?: ComponentViewModel[]
+  allowSaveAndReturn?: boolean
 
   constructor(
     request: FormContextRequest,

package/src/server/plugins/engine/options.js

@@ -9,6 +9,7 @@ const pluginRegistrationOptionsSchema = Joi.object({
   services: Joi.object().optional(),
   controllers: Joi.object().pattern(Joi.string(), Joi.any()).optional(),
   cacheName: Joi.string().optional(),
+  globals: Joi.object().pattern(Joi.string(), Joi.any()).optional(),
   filters: Joi.object().pattern(Joi.string(), Joi.any()).optional(),
   pluginPath: Joi.string().optional(),
   nunjucks: Joi.object({
@@ -18,7 +19,10 @@ const pluginRegistrationOptionsSchema = Joi.object({
   viewContext: Joi.function().required(),
   preparePageEventRequestOptions: Joi.function().optional(),
   onRequest: Joi.function().optional(),
-  baseUrl: Joi.string().uri().required()
+  baseUrl: Joi.string().uri().required(),
+  keyGenerator: Joi.function().optional(),
+  sessionHydrator: Joi.function().optional(),
+  sessionPersister: Joi.function().optional()
 })
 
 /**

package/src/server/plugins/engine/options.test.js

@@ -16,6 +16,26 @@ describe('validatePluginOptions', () => {
     expect(validatePluginOptions(validOptions)).toEqual(validOptions)
   })
 
+  it('accepts optional properties keyGenerator, sessionHydrator, and sessionPersister', () => {
+    const validOptionsWithOptionals = {
+      nunjucks: {
+        baseLayoutPath: 'dxt-devtool-baselayout.html',
+        paths: ['src/server/devserver']
+      },
+      viewContext: () => {
+        return { hello: 'world' }
+      },
+      baseUrl: 'http://localhost:3009',
+      keyGenerator: () => 'test-key',
+      sessionHydrator: () => Promise.resolve({ someState: 'value' }),
+      sessionPersister: () => Promise.resolve(undefined)
+    }
+
+    expect(validatePluginOptions(validOptionsWithOptionals)).toEqual(
+      validOptionsWithOptionals
+    )
+  })
+
   /**
    * tsc would usually check compliance with the type, but given a user might be using plain JS we still want a test
    */

package/src/server/plugins/engine/pageControllers/PageController.test.ts

@@ -204,5 +204,30 @@ describe('PageController', () => {
         'Unsupported POST route handler for this page'
       )
     })
+
+    it('supports save and return functionality', async () => {
+      const mockRequest = {
+        ...request,
+        payload: { saveAndReturn: true }
+      } as FormRequest
+
+      const mockResponse = {
+        redirect: jest.fn(),
+        view: jest.fn()
+      } as unknown as ResponseToolkit
+
+      await controller1.makeGetRouteHandler()(
+        mockRequest,
+        model.getFormContext(mockRequest, { $$__referenceNumber: 'test-ref' }),
+        mockResponse
+      )
+
+      expect(mockResponse.view).toHaveBeenCalledWith(
+        controller1.viewName,
+        expect.objectContaining({
+          pageTitle: 'Buy a rod fishing licence'
+        })
+      )
+    })
   })
 })

package/src/server/plugins/engine/pageControllers/QuestionPageController.test.ts

@@ -10,7 +10,10 @@ import {
   type FormState,
   type FormSubmissionState
 } from '~/src/server/plugins/engine/types.js'
-import { type FormRequest } from '~/src/server/routes/types.js'
+import {
+  type FormRequest,
+  type FormRequestPayload
+} from '~/src/server/routes/types.js'
 import { CacheService } from '~/src/server/services/cacheService.js'
 import conditionalReveal from '~/test/form/definitions/conditional-reveal.js'
 import definitionConditionsBasic, {
@@ -1274,3 +1277,177 @@ describe('QuestionPageController V2', () => {
     })
   })
 })
+
+describe('Save and Return functionality', () => {
+  let model: FormModel
+  let controller1: QuestionPageController
+  let requestPage1: FormRequest
+
+  beforeEach(() => {
+    const { pages } = definitionConditionsBasic
+
+    model = new FormModel(definitionConditionsBasic, {
+      basePath: 'test'
+    })
+
+    controller1 = new QuestionPageController(model, pages[0])
+
+    requestPage1 = {
+      method: 'get',
+      url: new URL('http://example.com/test/first-page'),
+      path: '/test/first-page',
+      params: {
+        path: 'first-page',
+        slug: 'test'
+      },
+      query: {},
+      app: { model }
+    } as FormRequest
+  })
+
+  const response = {
+    code: jest.fn().mockImplementation(() => response)
+  }
+
+  const h: Pick<ResponseToolkit, 'redirect' | 'view'> = {
+    redirect: jest.fn().mockReturnValue(response),
+    view: jest.fn()
+  }
+
+  beforeEach(() => {
+    jest.clearAllMocks()
+    jest.spyOn(CacheService.prototype, 'setState')
+  })
+
+  describe('shouldShowSaveAndReturn', () => {
+    it('should return true by default', () => {
+      expect(controller1.shouldShowSaveAndReturn()).toBe(true)
+    })
+  })
+
+  describe('handleSaveAndReturn', () => {
+    it('should save state and redirect to exit page', async () => {
+      const state: FormSubmissionState = {
+        $$__referenceNumber: 'foobar',
+        yesNoField: true
+      }
+      const request = {
+        ...requestPage1,
+        method: 'post',
+        payload: { yesNoField: true, action: 'save-and-return' }
+      } as unknown as FormRequestPayload
+
+      const context = model.getFormContext(request, state)
+
+      jest.spyOn(controller1, 'setState').mockResolvedValue(state)
+
+      await controller1.handleSaveAndReturn(request, context, h)
+
+      expect(controller1.setState).toHaveBeenCalledWith(request, state)
+      expect(h.redirect).toHaveBeenCalledWith('/test/exit')
+    })
+
+    it('should handle save-and-return with incomplete data', async () => {
+      const state: FormSubmissionState = {
+        $$__referenceNumber: 'foobar',
+        yesNoField: null
+      }
+      const request = {
+        ...requestPage1,
+        method: 'post',
+        payload: { yesNoField: '', action: 'save-and-return' }
+      } as unknown as FormRequestPayload
+
+      const context = model.getFormContext(request, state)
+
+      jest.spyOn(controller1, 'setState').mockResolvedValue(state)
+
+      await controller1.handleSaveAndReturn(request, context, h)
+
+      expect(controller1.setState).toHaveBeenCalledWith(request, state)
+      expect(h.redirect).toHaveBeenCalledWith('/test/exit')
+    })
+
+    it('should handle save-and-return with validation errors', async () => {
+      const state: FormSubmissionState = { $$__referenceNumber: 'foobar' }
+      const request = {
+        ...requestPage1,
+        method: 'post',
+        payload: { action: 'save-and-return' }
+      } as unknown as FormRequestPayload
+
+      const context = model.getFormContext(request, state)
+
+      jest.spyOn(controller1, 'setState').mockResolvedValue(state)
+
+      await controller1.handleSaveAndReturn(request, context, h)
+
+      expect(controller1.setState).toHaveBeenCalledWith(request, state)
+      expect(h.redirect).toHaveBeenCalledWith('/test/exit')
+    })
+  })
+
+  describe('POST handler with save-and-return action', () => {
+    it('should handle FormAction.SaveAndReturn', async () => {
+      const state: FormSubmissionState = {
+        $$__referenceNumber: 'foobar',
+        yesNoField: true
+      }
+      const request = {
+        ...requestPage1,
+        method: 'post',
+        payload: { yesNoField: true, action: 'save-and-return' }
+      } as unknown as FormRequestPayload
+
+      const context = model.getFormContext(request, state)
+
+      jest.spyOn(controller1, 'getState').mockResolvedValue({})
+      jest
+        .spyOn(controller1, 'handleSaveAndReturn')
+        .mockResolvedValue(h.redirect('/test/exit'))
+
+      const postHandler = controller1.makePostRouteHandler()
+      await postHandler(request, context, h)
+
+      expect(controller1.handleSaveAndReturn).toHaveBeenCalledWith(
+        request,
+        context,
+        h
+      )
+    })
+
+    it('should not call handleSaveAndReturn for continue action', async () => {
+      const state: FormSubmissionState = {
+        $$__referenceNumber: 'foobar',
+        yesNoField: true
+      }
+      const request = {
+        ...requestPage1,
+        method: 'post',
+        payload: { yesNoField: true, action: 'continue' }
+      } as unknown as FormRequestPayload
+
+      const context = model.getFormContext(request, state)
+
+      jest.spyOn(controller1, 'getState').mockResolvedValue({})
+      jest
+        .spyOn(controller1, 'handleSaveAndReturn')
+        .mockResolvedValue(h.redirect('/test/exit'))
+      jest.spyOn(controller1, 'setState').mockResolvedValue(state)
+
+      const mockResponse = {
+        code: jest.fn().mockReturnValue({ redirect: jest.fn() })
+      }
+
+      const mockH = {
+        redirect: jest.fn().mockReturnValue(mockResponse),
+        view: jest.fn()
+      }
+
+      const postHandler = controller1.makePostRouteHandler()
+      await postHandler(request, context, mockH)
+
+      expect(controller1.handleSaveAndReturn).not.toHaveBeenCalled()
+    })
+  })
+})

package/src/server/plugins/engine/pageControllers/QuestionPageController.ts

@@ -33,6 +33,7 @@ import {
   type FormSubmissionState
 } from '~/src/server/plugins/engine/types.js'
 import {
+  FormAction,
   type FormRequest,
   type FormRequestPayload,
   type FormRequestPayloadRefs,
@@ -172,7 +173,8 @@ export class QuestionPageController extends PageController {
       context,
       showTitle,
       components,
-      errors
+      errors,
+      allowSaveAndReturn: this.shouldShowSaveAndReturn()
     }
   }
 
@@ -510,6 +512,12 @@ export class QuestionPageController extends PageController {
         return h.view(viewName, viewModel)
       }
 
+      // Check if this is a save-and-return action
+      const { action } = request.payload
+      if (action === FormAction.SaveAndReturn) {
+        return this.handleSaveAndReturn(request, context, h)
+      }
+
       // Save and proceed
       await this.setState(request, state)
       return this.proceed(request, h, this.getNextPath(context))
@@ -528,6 +536,25 @@ export class QuestionPageController extends PageController {
     return proceed(request, h, nextUrl)
   }
 
+  shouldShowSaveAndReturn(): boolean {
+    return true
+  }
+
+  /**
+   * Handle save-and-return action by processing form data and redirecting to exit page
+   */
+  async handleSaveAndReturn(
+    request: FormRequestPayload,
+    context: FormContext,
+    h: Pick<ResponseToolkit, 'redirect' | 'view'>
+  ) {
+    const { state } = context
+
+    // Save the current state and redirect to exit page
+    await this.setState(request, state)
+    return h.redirect(this.getHref('/exit'))
+  }
+
   /**
    * {@link https://hapi.dev/api/?v=20.1.2#route-options}
    */

package/src/server/plugins/engine/pageControllers/StartPageController.ts

@@ -15,4 +15,8 @@ export class StartPageController extends QuestionPageController {
       isStartPage: true
     }
   }
+
+  shouldShowSaveAndReturn(): boolean {
+    return false
+  }
 }

package/src/server/plugins/engine/pageControllers/SummaryPageController.ts

@@ -68,6 +68,7 @@ export class SummaryPageController extends QuestionPageController {
     viewModel.feedbackLink = this.feedbackLink
     viewModel.phaseTag = this.phaseTag
     viewModel.components = components
+    viewModel.allowSaveAndReturn = this.shouldShowSaveAndReturn()
 
     return viewModel
   }
@@ -143,6 +144,10 @@ export class SummaryPageController extends QuestionPageController {
       }
     }
   }
+
+  shouldShowSaveAndReturn(): boolean {
+    return true
+  }
 }
 
 async function submitForm(

package/src/server/plugins/engine/plugin.ts

@@ -8,6 +8,7 @@ import {
 
 import { type FormModel } from '~/src/server/plugins/engine/models/index.js'
 import { validatePluginOptions } from '~/src/server/plugins/engine/options.js'
+import { getRoutes as getSaveAndReturnExitRoutes } from '~/src/server/plugins/engine/routes/exit.js'
 import { getRoutes as getFileUploadStatusRoutes } from '~/src/server/plugins/engine/routes/file-upload.js'
 import { makeLoadFormPreHandler } from '~/src/server/plugins/engine/routes/index.js'
 import { getRoutes as getQuestionRoutes } from '~/src/server/plugins/engine/routes/questions.js'
@@ -33,6 +34,7 @@ export const plugin = {
       cacheName,
       keyGenerator,
       sessionHydrator,
+      sessionPersister,
       nunjucks: nunjucksOptions,
       viewContext,
       preparePageEventRequestOptions
@@ -42,7 +44,8 @@ export const plugin = {
       cacheName,
       options: {
         keyGenerator,
-        sessionHydrator
+        sessionHydrator,
+        sessionPersister
       }
     })
 
@@ -90,6 +93,7 @@ export const plugin = {
       ),
       ...getRepeaterSummaryRoutes(getRouteOptions, postRouteOptions),
       ...getRepeaterItemDeleteRoutes(getRouteOptions, postRouteOptions),
+      ...getSaveAndReturnExitRoutes(getRouteOptions),
       ...getFileUploadStatusRoutes()
     ]
 

package/src/server/plugins/engine/routes/exit.ts

@@ -0,0 +1,47 @@
+import { slugSchema } from '@defra/forms-model'
+import Boom from '@hapi/boom'
+import { type ResponseToolkit, type RouteOptions } from '@hapi/hapi'
+import Joi from 'joi'
+
+import {
+  type FormRequest,
+  type FormRequestRefs
+} from '~/src/server/routes/types.js'
+
+export function getRoutes(getRouteOptions: RouteOptions<FormRequestRefs>) {
+  return [
+    {
+      method: 'get',
+      path: '/{slug}/exit',
+      handler: (
+        request: FormRequest,
+        h: Pick<ResponseToolkit, 'redirect' | 'view'>
+      ) => {
+        const { app } = request
+        const { model } = app
+
+        if (!model) {
+          throw Boom.notFound('No model found for exit page')
+        }
+
+        const returnUrl = request.query.returnUrl
+
+        const exitViewModel = {
+          pageTitle: 'Your progress has been saved',
+          phaseTag: model.def.phaseBanner?.phase,
+          returnUrl
+        }
+
+        return h.view('exit', exitViewModel)
+      },
+      options: {
+        ...getRouteOptions,
+        validate: {
+          params: Joi.object().keys({
+            slug: slugSchema
+          })
+        }
+      }
+    }
+  ]
+}

package/src/server/plugins/engine/types.ts

@@ -30,6 +30,8 @@ import {
 import { type RequestOptions } from '~/src/server/services/httpService.js'
 import { type Services } from '~/src/server/types.js'
 
+type RequestType = Request | FormRequest | FormRequestPayload
+
 /**
  * Form submission state stores the following in Redis:
  * Props containing user's submitted values as `{ [inputId]: value }` or as `{ [sectionName]: { [inputName]: value } }`
@@ -303,6 +305,7 @@ export interface FormPageViewModel extends PageViewModelBase {
   context: FormContext
   errors?: FormSubmissionError[]
   hasMissingNotificationEmail?: boolean
+  allowSaveAndReturn?: boolean
 }
 
 export interface RepeaterSummaryPageViewModel extends PageViewModelBase {
@@ -360,10 +363,13 @@ export interface PluginOptions {
   cacheName?: string
   globals?: Record<string, GlobalFunction>
   filters?: Record<string, FilterFunction>
-  keyGenerator?: (request: Request | FormRequest | FormRequestPayload) => string
-  sessionHydrator?: (
-    request: Request | FormRequest | FormRequestPayload
-  ) => Promise<FormSubmissionState>
+  keyGenerator?: (request: RequestType) => string
+  sessionHydrator?: (request: RequestType) => Promise<FormSubmissionState>
+  sessionPersister?: (
+    key: string,
+    state: FormSubmissionState,
+    request: RequestType
+  ) => Promise<void>
   pluginPath?: string
   nunjucks: {
     baseLayoutPath: string

package/src/server/plugins/engine/views/exit.html

@@ -0,0 +1,31 @@
+{% extends baseLayoutPath %}
+
+{% from "govuk/components/panel/macro.njk" import govukPanel %}
+{% from "govuk/components/button/macro.njk" import govukButton %}
+
+{% set mainClasses = "govuk-main-wrapper--l" %}
+
+{% block content %}
+  <div class="govuk-grid-row">
+    <div class="govuk-grid-column-two-thirds">
+      {{ govukPanel({
+        titleText: pageTitle or "Your progress has been saved"
+      }) }}
+
+      <h2 class="govuk-heading-m">What happens next</h2>
+      <div class="app-prose-scope">
+        <p class="govuk-body">Your form progress has been saved. You can return to complete your application at any time using the link provided.</p>
+
+        {% if returnUrl %}
+          <p class="govuk-body">
+            {{ govukButton({
+              text: "Return to application",
+              href: returnUrl,
+              classes: "govuk-button--secondary"
+            }) }}
+          </p>
+        {% endif %}
+      </div>
+    </div>
+  </div>
+{% endblock %}

package/src/server/plugins/engine/views/partials/form.html

@@ -3,13 +3,24 @@
 
 <form method="post" novalidate>
   <input type="hidden" name="crumb" value="{{ crumb }}">
-  <input type="hidden" name="action" value="validate">
 
   {{ componentList(components) }}
 
-  {{ govukButton({
-    text: "Start now" if isStartPage else "Continue",
-    isStartButton: isStartPage,
-    preventDoubleClick: true
-  }) }}
+  <div class="govuk-button-group">
+    {{ govukButton({
+      text: "Start now" if isStartPage else "Continue",
+      isStartButton: isStartPage,
+      preventDoubleClick: true
+    }) }}
+
+    {% if allowSaveAndReturn %}
+      {{ govukButton({
+        text: "Save and return",
+        classes: "govuk-button--secondary",
+        name: "action",
+        value: "save-and-return",
+        preventDoubleClick: true
+      }) }}
+    {% endif %}
+  </div>
 </form>

package/src/server/routes/types.ts

@@ -39,7 +39,8 @@ export enum FormAction {
   Validate = 'validate',
   Delete = 'delete',
   AddAnother = 'add-another',
-  Send = 'send'
+  Send = 'send',
+  SaveAndReturn = 'save-and-return'
 }
 
 export enum FormStatus {

package/src/server/schemas/index.ts

@@ -13,7 +13,8 @@ export const actionSchema = Joi.string<FormAction>()
     FormAction.Validate,
     FormAction.Delete,
     FormAction.AddAnother,
-    FormAction.Send
+    FormAction.Send,
+    FormAction.SaveAndReturn
   )
   .default(FormAction.Validate)
   .optional()

package/src/server/services/cacheService.test.ts

@@ -110,6 +110,29 @@ describe('CacheService', () => {
       )
       expect(result).toEqual(rehydratedState)
     })
+
+    it('should return empty object when custom fetcher returns null', async () => {
+      const customFetcher = jest.fn().mockResolvedValue(null)
+
+      cacheService = new CacheService({
+        server: mockServer as Server,
+        cacheName: 'test-cache',
+        options: { sessionHydrator: customFetcher }
+      })
+
+      const mockRequest = {
+        yar: { id: 'session-id' },
+        params: { state: 's', slug: 'p' }
+      } as unknown as FormRequest
+
+      mockCache.get.mockResolvedValue(null)
+
+      const result = await cacheService.getState(mockRequest)
+
+      expect(customFetcher).toHaveBeenCalledWith(mockRequest)
+      expect(mockCache.set).not.toHaveBeenCalled()
+      expect(result).toEqual({})
+    })
   })
 
   describe('setState', () => {
@@ -312,6 +335,28 @@ describe('CacheService', () => {
         id: 'some-session:form1:page1:'
       })
     })
+
+    it('should not clear state when session ID is undefined', async () => {
+      const mockRequest = {
+        yar: { id: undefined },
+        params: { state: 'form1', slug: 'page1' }
+      } as unknown as FormRequest
+
+      await cacheService.clearState(mockRequest)
+
+      expect(mockCache.drop).not.toHaveBeenCalled()
+    })
+
+    it('should not clear state when session ID is null', async () => {
+      const mockRequest = {
+        yar: { id: null },
+        params: { state: 'form1', slug: 'page1' }
+      } as unknown as FormRequest
+
+      await cacheService.clearState(mockRequest)
+
+      expect(mockCache.drop).not.toHaveBeenCalled()
+    })
   })
 
   describe('getConfirmationState', () => {