@defra/forms-engine-plugin 4.0.24 → 4.0.26

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

@@ -22,6 +22,7 @@ import {
 } from '~/src/server/plugins/engine/components/helpers/components.js'
 import { type FormModel } from '~/src/server/plugins/engine/models/FormModel.js'
 import { type PageControllerClass } from '~/src/server/plugins/engine/pageControllers/helpers/pages.js'
+import { stripParam } from '~/src/server/plugins/engine/pageControllers/helpers/state.js'
 import {
   type AnyFormRequest,
   type FormContext,
@@ -133,7 +134,7 @@ export function proceed(
   const response =
     isReturnAllowed && isPathRelative(returnUrl)
       ? h.redirect(returnUrl)
-      : h.redirect(redirectPath(nextUrl))
+      : h.redirect(redirectPath(nextUrl, stripParam(query, 'returnUrl')))
 
   // Redirect POST to GET to avoid resubmission
   return method === 'post'

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

@@ -33,8 +33,11 @@ export const prepareNunjucksEnvironment = function (
     env.addFilter(name, nunjucksFilter)
   }
 
-  env.addFilter('markdown', (text: string) =>
-    markdownToHtml(text, pluginOptions.baseUrl)
+  env.addFilter('markdown', (text: string, startingHeaderLevel?: number) =>
+    markdownToHtml(text, {
+      baseUrl: pluginOptions.baseUrl,
+      startingHeaderLevel
+    })
   )
 
   for (const [name, nunjucksGlobal] of Object.entries(globals)) {

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

@@ -74,6 +74,7 @@ export class FormModel {
   lists: FormDefinition['lists']
   sections: FormDefinition['sections'] = []
   name: string
+  formId: string
   values: FormDefinition
   basePath: string
   versionNumber?: number
@@ -100,6 +101,7 @@ export class FormModel {
       basePath: string
       versionNumber?: number
       ordnanceSurveyApiKey?: string
+      formId?: string
     },
     services: Services = defaultServices,
     controllers?: Record<string, typeof PageController>
@@ -152,6 +154,7 @@ export class FormModel {
     this.lists = def.lists
     this.sections = def.sections
     this.name = def.name ?? ''
+    this.formId = options.formId ?? ''
     this.values = result.value
     this.basePath = options.basePath
     this.versionNumber = options.versionNumber

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

@@ -24,7 +24,8 @@ describe('PageController', () => {
     const page2 = pages[1]
 
     model = new FormModel(definition, {
-      basePath: testBasePath
+      basePath: testBasePath,
+      formId: 'form-id'
     })
 
     controller1 = new PageController(model, page1)
@@ -61,18 +62,10 @@ describe('PageController', () => {
       })
     })
 
-    it('returns feedback link (from form definition)', () => {
-      expect(controller1).toHaveProperty('feedbackLink', undefined)
-
-      const emailAddress = 'test@feedback.cat'
-
-      model.def.feedback = {
-        emailAddress
-      }
-
+    it('returns feedback link default', () => {
       expect(controller1).toHaveProperty(
         'feedbackLink',
-        `mailto:${emailAddress}`
+        '/form/feedback?formId=form-id'
       )
     })
 

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

@@ -10,7 +10,6 @@ import { type Lifecycle, type RouteOptions, type Server } from '@hapi/hapi'
 
 import { type ComponentCollection } from '~/src/server/plugins/engine/components/ComponentCollection.js'
 import {
-  encodeUrl,
   getSaveAndExitHelpers,
   getStartPath,
   normalisePath
@@ -119,14 +118,7 @@ export class PageController {
   }
 
   get feedbackLink() {
-    const { def } = this
-
-    // setting the feedbackLink to undefined here for feedback forms prevents the feedback link from being shown
-    const feedbackLink = def.feedback?.emailAddress
-      ? `mailto:${def.feedback.emailAddress}`
-      : def.feedback?.url
-
-    return encodeUrl(feedbackLink)
+    return `/form/feedback?formId=${this.model.formId}`
   }
 
   get phaseTag() {

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

@@ -28,6 +28,7 @@ import {
 } from '~/src/server/plugins/engine/helpers.js'
 import { type FormModel } from '~/src/server/plugins/engine/models/index.js'
 import { PageController } from '~/src/server/plugins/engine/pageControllers/PageController.js'
+import { prefillStateFromQueryParameters } from '~/src/server/plugins/engine/pageControllers/helpers/state.js'
 import {
   type AnyFormRequest,
   type FormContext,
@@ -403,6 +404,12 @@ export class QuestionPageController extends PageController {
       const { collection, model, viewName } = this
       const { evaluationState } = context
 
+      // Copy any URL params into the form state (if not already done so)
+      if (await prefillStateFromQueryParameters(request, this)) {
+        // Forward to same page without query string
+        return h.redirect(`${request.url.origin}${request.url.pathname}`)
+      }
+
       const viewModel = this.getViewModel(request, context)
       viewModel.errors = collection.getViewErrors(viewModel.errors)
 

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

@@ -41,13 +41,20 @@ export class StatusPageController extends QuestionPageController {
 
       const slug = request.params.slug
       const { formsService } = this.model.services
-      const { getFormMetadata } = formsService
+      const { getFormMetadata, getFormMetadataById } = formsService
 
       const { submissionGuidance } = await getFormMetadata(slug)
 
+      // Re-read form name if overriding display (for example, in a feedback form)
+      const storedFormId = confirmationState.formId
+      const formName = storedFormId
+        ? (await getFormMetadataById(storedFormId)).title
+        : undefined
+
       return h.view(viewName, {
         ...viewModel,
-        submissionGuidance
+        submissionGuidance,
+        formName
       })
     }
   }

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

@@ -25,6 +25,7 @@ import {
 } from '~/src/server/plugins/engine/models/types.js'
 import { QuestionPageController } from '~/src/server/plugins/engine/pageControllers/QuestionPageController.js'
 import {
+  type FormConfirmationState,
   type FormContext,
   type FormContextRequest,
   type FormSubmissionState
@@ -152,7 +153,10 @@ export class SummaryPageController extends QuestionPageController {
       )
     }
 
-    await cacheService.setConfirmationState(request, { confirmed: true })
+    await cacheService.setConfirmationState(request, {
+      confirmed: true,
+      formId: context.state.formId
+    } as FormConfirmationState)
 
     // Clear all form data
     await cacheService.clearState(request)

package/src/server/plugins/engine/pageControllers/helpers/state.test.ts

@@ -0,0 +1,221 @@
+import { ComponentType, type Page } from '@defra/forms-model'
+
+import { type FormModel } from '~/src/server/plugins/engine/models/FormModel.js'
+import { type PageControllerClass } from '~/src/server/plugins/engine/pageControllers/helpers/pages.js'
+import {
+  prefillStateFromQueryParameters,
+  stripParam
+} from '~/src/server/plugins/engine/pageControllers/helpers/state.js'
+import { type AnyFormRequest } from '~/src/server/plugins/engine/types.js'
+import { type FormsService, type Services } from '~/src/server/types.js'
+
+function buildMockPage(
+  pagesOverride = {},
+  stateOverride = {},
+  servicesOverride = {} as Services
+) {
+  return {
+    model: {
+      def: {
+        metadata: {
+          submission: { code: 'TEST-CODE' }
+        } as { submission: { code: string } },
+        pages: pagesOverride
+      },
+      getFormContext: jest.fn().mockReturnValue({
+        isForceAccess: false,
+        data: {}
+      }),
+      services: servicesOverride
+    } as unknown as FormModel,
+    ...stateOverride
+  } as unknown as PageControllerClass
+}
+
+describe('State helpers', () => {
+  describe('prefillStateFromQueryParameters', () => {
+    const mockGetState = jest.fn()
+    const mockMergeState = jest.fn()
+    const mockRequestPrefill: AnyFormRequest = {
+      app: {},
+      yar: { flash: () => [] },
+      params: { path: 'test-path' },
+      query: {}
+    } as unknown as AnyFormRequest
+
+    it('should not add any state if no params', async () => {
+      const mockPagePrefill = buildMockPage([], {
+        getState: mockGetState,
+        mergeState: mockMergeState
+      })
+
+      expect(
+        await prefillStateFromQueryParameters(
+          mockRequestPrefill,
+          mockPagePrefill
+        )
+      ).toBeFalse()
+      expect(mockMergeState).not.toHaveBeenCalled()
+    })
+
+    it('should ignore if no params (but some hidden fields)', async () => {
+      const mockRequest2 = {
+        ...mockRequestPrefill,
+        query: {}
+      } as unknown as AnyFormRequest
+
+      const mockPagePrefill = buildMockPage(
+        [
+          {
+            components: [
+              {
+                type: ComponentType.HiddenField,
+                name: 'param2'
+              },
+              {
+                type: ComponentType.HiddenField,
+                name: 'param4'
+              }
+            ],
+            next: []
+          } as unknown as Page
+        ],
+        {
+          getState: mockGetState,
+          mergeState: mockMergeState
+        }
+      )
+
+      expect(
+        await prefillStateFromQueryParameters(mockRequest2, mockPagePrefill)
+      ).toBeFalse()
+      expect(mockMergeState).not.toHaveBeenCalled()
+    })
+
+    it('should only add state where param names match hidden field names', async () => {
+      const mockRequest2 = {
+        ...mockRequestPrefill,
+        query: {
+          param1: 'val1',
+          param2: 'val2',
+          param3: 'val3',
+          param4: 'val4'
+        }
+      } as unknown as AnyFormRequest
+
+      const mockPagePrefill = buildMockPage(
+        [
+          {
+            components: [
+              {
+                type: ComponentType.HiddenField,
+                name: 'param2'
+              },
+              {
+                type: ComponentType.HiddenField,
+                name: 'param4'
+              }
+            ],
+            next: []
+          } as unknown as Page
+        ],
+        {
+          getState: mockGetState.mockResolvedValue({}),
+          mergeState: mockMergeState
+        }
+      )
+
+      expect(
+        await prefillStateFromQueryParameters(mockRequest2, mockPagePrefill)
+      ).toBe(true)
+      expect(mockMergeState).toHaveBeenCalledWith(
+        expect.anything(),
+        expect.anything(),
+        {
+          param2: 'val2',
+          param4: 'val4'
+        }
+      )
+    })
+
+    it('should call lookup function for formId', async () => {
+      const mockRequest3 = {
+        ...mockRequestPrefill,
+        query: {
+          formId: 'c644804b-2f23-4c96-a2fc-ad4975974723'
+        }
+      } as unknown as AnyFormRequest
+
+      const mockPagePrefill = buildMockPage(
+        [
+          {
+            components: [
+              {
+                type: ComponentType.HiddenField,
+                name: 'formId'
+              }
+            ],
+            next: []
+          } as unknown as Page
+        ],
+        {
+          getState: mockGetState.mockResolvedValue({}),
+          mergeState: mockMergeState
+        },
+        {
+          formsService: {
+            getFormMetadata: jest.fn(),
+            getFormMetadataById: jest
+              .fn()
+              .mockResolvedValue({ title: 'My looked-up form name' }),
+            getFormDefinition: jest.fn()
+          } as unknown as FormsService
+        } as Services
+      )
+
+      await prefillStateFromQueryParameters(mockRequest3, mockPagePrefill)
+      expect(mockMergeState).toHaveBeenCalledWith(
+        expect.anything(),
+        expect.anything(),
+        {
+          formId: 'c644804b-2f23-4c96-a2fc-ad4975974723',
+          formName: 'My looked-up form name'
+        }
+      )
+    })
+  })
+
+  describe('stripParam', () => {
+    it('should remove param when exists', () => {
+      const params = {
+        paramName1: 'val1',
+        returnUrl: 'http://somesite.com',
+        paramName2: 'val2',
+        paramName3: undefined
+      }
+      expect(stripParam(params, 'returnUrl')).toStrictEqual({
+        paramName1: 'val1',
+        paramName2: 'val2',
+        paramName3: ''
+      })
+    })
+
+    it('should handle param missing', () => {
+      const params = {
+        paramName1: 'val1',
+        returnUrl: 'http://somesite.com',
+        paramName2: 'val2'
+      }
+      expect(stripParam(params, 'paramNotThere')).toStrictEqual({
+        paramName1: 'val1',
+        returnUrl: 'http://somesite.com',
+        paramName2: 'val2'
+      })
+    })
+
+    it('should handle no params', () => {
+      const params = {}
+      expect(stripParam(params, 'anyParam')).toBeUndefined()
+    })
+  })
+})

package/src/server/plugins/engine/pageControllers/helpers/state.ts

@@ -0,0 +1,93 @@
+import { getHiddenFields } from '@defra/forms-model'
+
+import { type PageControllerClass } from '~/src/server/plugins/engine/pageControllers/helpers/pages.js'
+import {
+  type AnyFormRequest,
+  type FormStateValue
+} from '~/src/server/plugins/engine/types.js'
+import { type FormQuery } from '~/src/server/routes/types.js'
+import { type Services } from '~/src/server/types.js'
+
+/**
+ * A series of functions that can transform a pre-fill input parameter e.g lookup a form title based on form id
+ */
+const paramLookupFunctions = {
+  formId: async (val: string, services: Services) => {
+    let formTitle
+    if (val) {
+      const meta = await services.formsService.getFormMetadataById(val)
+      formTitle = meta.title
+    }
+    return {
+      key: 'formName',
+      value: formTitle
+    }
+  }
+} as Partial<
+  Record<
+    string,
+    (
+      val: string,
+      services: Services
+    ) => Promise<{ key: string; value: string | undefined }>
+  >
+>
+
+export function stripParam(query: FormQuery, paramToRemove: string) {
+  const params = {} as Record<string, FormStateValue | undefined>
+  for (const [key, value = ''] of Object.entries(query)) {
+    if (key !== paramToRemove) {
+      params[key] = value
+    }
+  }
+  return Object.keys(params).length ? (params as FormQuery) : undefined
+}
+
+/**
+ * Any hidden parameters defined in the FormDefinition may be pre-filled by URL parameter values.
+ * Other parameters are ignored for security reasons.
+ * @param request
+ * @param model
+ */
+export async function prefillStateFromQueryParameters(
+  request: AnyFormRequest,
+  page: PageControllerClass
+): Promise<boolean> {
+  const { model } = page
+
+  const hiddenFieldNames = new Set(
+    getHiddenFields(model.def).map((field) => field.name)
+  )
+
+  if (!hiddenFieldNames.size) {
+    return false
+  }
+
+  // Remove 'returnUrl' param
+  const query = stripParam(request.query, 'returnUrl')
+
+  if (!query) {
+    return false
+  }
+
+  const params = {} as Record<string, FormStateValue | undefined>
+
+  for (const [key, value = ''] of Object.entries(query)) {
+    if (hiddenFieldNames.has(key)) {
+      const lookupFunc = paramLookupFunctions[key]
+      if (lookupFunc) {
+        const res = await lookupFunc(value, model.services)
+        // Store original value and result
+        params[key] = value
+        params[res.key] = res.value
+      } else {
+        params[key] = value
+      }
+    }
+  }
+
+  const formData = await page.getState(request)
+  await page.mergeState(request, formData, params)
+
+  return true
+}

package/src/server/plugins/engine/routes/index.test.ts

@@ -1,3 +1,4 @@
+import { type Page } from '@defra/forms-model'
 import Boom from '@hapi/boom'
 import { type ResponseObject, type ResponseToolkit } from '@hapi/hapi'
 
@@ -15,9 +16,31 @@ import {
   type OnRequestCallback
 } from '~/src/server/plugins/engine/types.js'
 import { type FormResponseToolkit } from '~/src/server/routes/types.js'
+import { type Services } from '~/src/server/types.js'
 
 jest.mock('~/src/server/plugins/engine/helpers')
 
+function buildMockModel(
+  pagesOverride = [] as Page[],
+  pagesControllerOverride = [] as PageControllerClass[],
+  servicesOverride = {} as Services
+) {
+  return {
+    def: {
+      metadata: {
+        submission: { code: 'TEST-CODE' }
+      } as { submission: { code: string } },
+      pages: pagesOverride
+    },
+    getFormContext: jest.fn().mockReturnValue({
+      isForceAccess: false,
+      data: {}
+    }),
+    pages: pagesControllerOverride,
+    services: servicesOverride
+  } as unknown as FormModel
+}
+
 describe('redirectOrMakeHandler', () => {
   const mockServer = {} as unknown as Parameters<
     typeof redirectOrMakeHandler
@@ -38,17 +61,7 @@ describe('redirectOrMakeHandler', () => {
 
   let mockPage: PageControllerClass
 
-  const mockModel: FormModel = {
-    def: {
-      metadata: {
-        submission: { code: 'TEST-CODE' }
-      } as { submission: { code: string } }
-    },
-    getFormContext: jest.fn().mockReturnValue({
-      isForceAccess: false,
-      data: {}
-    })
-  } as unknown as FormModel
+  const mockModel = buildMockModel()
 
   const mockMakeHandler = jest
     .fn()

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

@@ -244,7 +244,7 @@ export function makeLoadFormPreHandler(server: Server, options: PluginOptions) {
       // Construct the form model
       const model = new FormModel(
         definition,
-        { basePath, versionNumber, ordnanceSurveyApiKey },
+        { basePath, versionNumber, ordnanceSurveyApiKey, formId: id },
         services,
         controllers
       )

package/src/server/plugins/engine/services/formsService.js

@@ -12,6 +12,16 @@ export function getFormMetadata(_slug) {
   throw error
 }
 
+// eslint-disable-next-line jsdoc/require-returns-check
+/**
+ * Dummy function to get form metadata.
+ * @param {string} _id - the id of the form
+ * @returns {Promise<FormMetadata>}
+ */
+export function getFormMetadataById(_id) {
+  throw error
+}
+
 // eslint-disable-next-line jsdoc/require-returns-check
 /**
  * Dummy function to get form metadata.

package/src/server/plugins/engine/services/formsService.test.js

@@ -0,0 +1,21 @@
+import { FormStatus } from '@defra/forms-model'
+
+import {
+  getFormDefinition,
+  getFormMetadata,
+  getFormMetadataById
+} from '~/src/server/plugins/engine/services/formsService.js'
+
+describe('formsService', () => {
+  it('getFormMetadata should throw error', () => {
+    expect(() => getFormMetadata('slug')).toThrow()
+  })
+
+  it('getFormMetadataById should throw error', () => {
+    expect(() => getFormMetadataById('id')).toThrow()
+  })
+
+  it('getFormDefinition should throw error', () => {
+    expect(() => getFormDefinition('id', FormStatus.Draft)).toThrow()
+  })
+})

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

@@ -97,6 +97,11 @@ export interface FormSubmissionError
   text: string // e.g: 'Date field must be a real date'
 }
 
+export interface FormConfirmationState {
+  confirmed?: true
+  formId?: string
+}
+
 export interface FormPayloadParams {
   action?: FormAction
   confirm?: true

package/src/server/plugins/engine/views/components/declarationfield.html

@@ -5,7 +5,7 @@
 {% macro DeclarationField(component) %}
   {% set content %}
     <div class="app-prose-scope">
-      {{ component.model.content | markdown | safe }}
+      {{ component.model.content | markdown(component.model.headerStartLevel)  | safe }}
     </div>
   {% endset %}
   {% set checkboxes = component.model | merge({ formGroup: { beforeInputs: { html: content } } }) %}

package/src/server/plugins/engine/views/components/hiddenfield.html

@@ -0,0 +1,3 @@
+{% macro HiddenField(component) %}
+  <input type="hidden" id="{{ component.model.name }}" name="{{ component.model.name }}" value="{{ component.model.value }}" />
+{% endmacro %}

package/src/server/plugins/engine/views/components/markdown.html

@@ -1,5 +1,5 @@
 {% macro Markdown(component) %}
   <div class="app-prose-scope">
-    {{ component.model.content | markdown | safe }}
+    {{ component.model.content | markdown(component.model.headerStartLevel) | safe }}
   </div>
 {% endmacro %}

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

@@ -12,8 +12,13 @@
       }) }}
       <h2 class="govuk-heading-m">What happens next</h2>
       <div class="app-prose-scope">
-        {{ submissionGuidance | markdown | safe }}
+        {{ submissionGuidance | markdown(3) | safe }}
       </div>
+      {% if feedbackLink %}
+        <p class="govuk-body">
+          <a href="{{ feedbackLink }}" class="govuk-link govuk-link--no-visited-state">What do you think of this service?</a> (takes 30 seconds)
+        </p>
+      {% endif %}
     </div>
   </div>
 {% endblock %}

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

@@ -6,9 +6,17 @@
 
   {{ componentList(components) }}
 
+  {% if isStartPage %}
+    {% set buttonText = "Start now" %}
+  {% elif submitButtonText %}
+    {% set buttonText = submitButtonText %}
+  {% else %}
+    {% set buttonText = "Continue" %}
+  {% endif %}
+
   <div class="govuk-button-group">
     {{ govukButton({
-      text: "Start now" if isStartPage else "Continue",
+      text: buttonText,
       isStartButton: isStartPage,
       preventDoubleClick: true
     }) }}