From 070b8131ed04735f13f9907a658b65081722c8fe Mon Sep 17 00:00:00 2001
From: Rhodine Orleans-Lindsay
 <43888758+Rhodine-orleans-lindsay@users.noreply.github.com>
Date: Mon, 5 Aug 2024 19:49:48 +0100
Subject: [PATCH] HOFF-737 and HOFF-738: Add session timeout warning
 documentation

---
 .../Wiki_How_Tos/3.session-timeout-warning.md | 153 ++++++++++++++++++
 1 file changed, 153 insertions(+)
 create mode 100644 wiki/Wiki_How_Tos/3.session-timeout-warning.md

diff --git a/wiki/Wiki_How_Tos/3.session-timeout-warning.md b/wiki/Wiki_How_Tos/3.session-timeout-warning.md
new file mode 100644
index 0000000..17c04a7
--- /dev/null
+++ b/wiki/Wiki_How_Tos/3.session-timeout-warning.md
@@ -0,0 +1,153 @@
+---
+title: 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.
+
+
+<br>
+
+```toc
+# This code block gets replaced with the Table Of Contents
+```
+
+
+## Package.json updates
+
+- Specify package to use `hof@~22.0.0`
+- Run `yarn install`
+
+- Make dev use the .env file (command varies on projects)
+```js:title=basic-dev-cmd.js
+"dev": "NODE_ENV=development hof-build watch --env"
+```
+## Setting envs
+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 on 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.
+```js:title=index.js
+'/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.
+```js:title=index.js
+'/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.
+```js:title=index.js
+ '/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 confirmation page so it does not display the session timeout warning**
+
+  Change:
+
+```html:title=confirmation.html
+{{<partials-page}}
+   {{$page-content}}
+    {{>partials-confirmation-alert}}
+    {{#markdown}}what-happens-next{{/markdown}}
+  {{/page-content}}
+{{/partials-page}}
+```
+  to:
+
+```html:title=confirmation.html
+{{<layout}}
+  {{$journeyHeader}}
+    {{#t}}journey.header{{/t}}
+  {{/journeyHeader}}
+    
+  {{$propositionHeader}}
+    {{> partials-navigation}}
+  {{/propositionHeader}}
+    
+  {{$header}}
+    {{header}}
+  {{/header}}
+    
+  {{$content}}
+    {{>partials-confirmation-alert}}
+    {{#markdown}}what-happens-next{{/markdown}}
+  {{/content}}
+{{/layout}}
+```
+
+## Customising content
+By default sessionTimeoutWarningContent, exitFormContent and saveExitFormContent are set to true which will pick the default content from the hof framework. If the content requires customisation at a project level, the variables must be set to `true` in hof.settings.json.
+```json:title=hof.settings.json
+{
+ "behaviours": [
+   "require('../').components.sessionTimeoutWarning"
+ ],
+ "sessionTimeoutWarningContent": true,
+ "exitFormContent": true
+}
+```
+
+ ### 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:
+ ```json:title=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:
+
+```js
+// customising exit step name
+module.exports = {
+  name: 'sandbox',
+  exitStep: '/leave',
+  steps: {
+    ...
+    '/leave': {
+      template: 'exit'
+    }
+  }
+  ...
+}
+```
+
+```js
+// customising save-and-exit step name
+module.exports = {
+  name: 'sandbox',
+  saveAndExitStep: '/sign-out',
+  steps: {
+    ...
+    '/sign-out': {
+      template: 'save-and-exit'
+    }
+  }
+  ...
+}
+```