@defra/forms-engine-plugin 1.3.1 → 1.4.1

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', () => {

package/src/server/services/cacheService.ts

@@ -30,6 +30,12 @@ export class CacheService {
     request: Request | FormRequest | FormRequestPayload
   ) => Promise<FormSubmissionState | null>
 
+  customPersister?: (
+    key: string,
+    state: FormSubmissionState,
+    request: Request | FormRequest | FormRequestPayload
+  ) => Promise<void>
+
   logger: Server['logger']
 
   constructor({
@@ -46,9 +52,14 @@ export class CacheService {
       sessionHydrator?: (
         request: Request | FormRequest | FormRequestPayload
       ) => Promise<FormSubmissionState | null>
+      sessionPersister?: (
+        key: string,
+        state: FormSubmissionState,
+        request: Request | FormRequest | FormRequestPayload
+      ) => Promise<void>
     }
   }) {
-    const { keyGenerator, sessionHydrator } = options ?? {}
+    const { keyGenerator, sessionHydrator, sessionPersister } = options ?? {}
     if (!cacheName) {
       server.log(
         'warn',
@@ -57,6 +68,7 @@ export class CacheService {
     }
     this.generateKey = keyGenerator ?? this.defaultKeyGenerator.bind(this)
     this.customFetcher = sessionHydrator ?? undefined
+    this.customPersister = sessionPersister ?? undefined
     this.cache = server.cache({ cache: cacheName, segment: 'formSubmission' })
     this.logger = server.logger
   }
@@ -64,18 +76,16 @@ export class CacheService {
   async getState(
     request: Request | FormRequest | FormRequestPayload
   ): Promise<FormSubmissionState> {
-    let cached = await this.cache.get(this.Key(request))
+    const key = this.Key(request)
+
+    let cached = await this.cache.get(key)
 
     // If nothing in Redis, attempt to rehydrate from backend DB
     if (!cached && this.customFetcher) {
       const rehydrated = await this.customFetcher(request)
 
       if (rehydrated != null) {
-        await this.cache.set(
-          this.Key(request),
-          rehydrated,
-          config.get('sessionTimeout')
-        )
+        await this.cache.set(key, rehydrated, config.get('sessionTimeout'))
         cached = await this.getState(request)
       }
     }
@@ -91,6 +101,7 @@ export class CacheService {
     const ttl = config.get('sessionTimeout')
 
     await this.cache.set(key, state, ttl)
+
     return this.getState(request)
   }
 
@@ -146,8 +157,8 @@ export class CacheService {
       throw new Error('No session ID found')
     }
 
-    const state = request.params.state ?? ''
-    const slug = request.params.slug ?? ''
+    const state = (request.params.state as string) || ''
+    const slug = (request.params.slug as string) || ''
     return `${request.yar.id}:${state}:${slug}:`
   }