Session Timeout Warning

This is a basic documentation page to help developers use an updated version of the HOF framework to implement the session timeout warning in HOF forms.

Package.json updates

• Specify package to use hof@~22.0.0

• Run yarn install

• Make dev use the .env file (command varies on projects)

"dev": "NODE_ENV=development hof-build watch --env"

Setting the component and envs

To enable and customise the session timeout behaviour, you need to set the component in your project's hof.settings.json file:

 "behaviours": [
    "hof/components/session-timeout-warning"
  ]

The default session expiry time in hof is 30 minutes, with the timeout warning default being 5 minutes before the session times out. If you need to adjust the time for this on your local machine, they can be set in the .env file e.g.

SESSION_TTL=900 // session is now 15 minutes
SESSION_TIMEOUT_WARNING=60 // warning will now show 1 minute before session times out

Breaking changes

Adding steps

Session timeout step

Once the time runs out on the session, the user is redirected to the session-timeout page. This now requires that projects have the /session-timeout page included in the steps in index.js. An empty {} will pick up the default template from hof.

'/session-timeout': {}

Exit step

For forms that do not use the save and exit functionality, when the user clicks 'Exit this form' the link goes to the '/exit' page. This now requires that projects have the /exit page included in the steps in index.js. An empty {} will pick up the default template from hof.

'/exit': {}

Save and Exit Forms: Save and exit step

Forms that have the save and exit functionality require a '/save-and-exit' page. When the user clicks 'Sign out' the link goes to the '/save-and-exit' page.

 '/save-and-exit': {
      backLink: false,
      behaviours: [
        saveAndExit
      ]
  }

Static pages

If you have static pages that do not require the session timeout warning to be displayed, you must ensure the template is not using {{<partials-page))...{{/partials-page}} template. This is because the session timeout warning is set in the {{$form}} element of {{partials-page}}. Your static page should use the {{layout}}...{{/layout}} template instead.

Example: Changing the template for a static accessibility page so it does not display the session timeout warning

Change:

{{<partials-page}}
  {{$page-content}}
    {{#markdown}}accessibility{{/markdown}}
  {{/page-content}}
{{/partials-page}}

to:

{{<layout}}
  {{$journeyHeader}}
    {{#t}}journey.header{{/t}}
  {{/journeyHeader}}
    
  {{$propositionHeader}}{{/propositionHeader}}
    
  {{$header}}
    {{header}}
  {{/header}}
    
  {{$content}}
    {{#markdown}}accessibility{{/markdown}}
  {{/content}}
{{/layout}}

Customising content

By default, the framework uses the standard content provided by HOF. If you wish to override this with custom content at the project level, you must set the following variables to true in hof.settings.json:

 {
  "behaviours": [
    "require('../').components.sessionTimeoutWarning"
  ],
  "sessionTimeoutWarningContent": true, // allows you to customise the content in the session timeout dialog box
  "exitFormContent": true, // allows you to customise the content on the exit page
  "saveExitFormContent": true // allows you to customise the content on the save-and-exit page
 }

Customising content in pages.json

Once the variables are set, you can customise the session-timeout-warning, exit and save-and-exit messages in your project's pages.json:

"session-timeout-warning": {
  "dialog-title": "Your application will close soon",
  "dialog-text": "If that happens, your progress will not be saved",
  "timeout-continue-button": "Stay on this page",
  "dialog-exit-link": "Exit this form"
},
"exit": {
  "message": "We have cleared your information to keep it secure. Your information has not been saved."
},
"save-and-exit": {
  "header": "Your report has been saved",
  "paragraph-1": "You have until the <date> to update or submit your report.",
  "paragraph-2": "We have sent a confirmation email to: <email>",
  "paragraph-3": "You can return to your report at any time via the <a class="govuk-link" href="/start">start page</a> on GOV.UK"
 }

Customising exit and save-and-exit steps

You can customise the exit and save-and-exit steps by setting the exitStep or saveAndExitStep properties in the apps/<app_name>/index.js to the desired path name:

// customising exit step name
module.exports = {
  name: 'sandbox',
  exitStep: '/leave',
  steps: {
    ...
    '/leave': {
      template: 'exit'
    }
  }
  ...
}

// customising save-and-exit step name
module.exports = {
  name: 'sandbox',
  saveAndExitStep: '/sign-out',
  steps: {
    ...
    '/sign-out': {
      template: 'save-and-exit'
    }
  }
  ...
}