@defra/forms-engine-plugin 0.0.4 → 0.0.6

package/README.md

@@ -1,15 +1,209 @@
-# forms-engine
+# @defra/forms-engine-plugin
 
-Form hapi-plugin
+The `@defra/forms-engine-plugin` is a [plugin](https://hapi.dev/tutorials/plugins/?lang=en_US) for [hapi](https://hapi.dev/) used to serve GOV.UK-based form journeys.
 
-...
+It is designed to be embedded in the frontend of a digital service and provide a convenient, configuration driven approach to building forms that are aligned to [GDS Design System](https://design-system.service.gov.uk/) guidelines.
+
+## Installation
+
+`npm install @defra/forms-engine-plugin --save`
+
+## Dependencies
+
+The following are [plugin dependencies](<https://hapi.dev/api/?v=21.4.0#server.dependency()>) that are required to be registered with hapi:
+
+`npm install hapi-pino @hapi/crumb @hapi/yar @hapi/vision --save`
+
+- [hapi-pino](https://github.com/hapijs/hapi-pino) - [Pino](https://github.com/pinojs/pino) logger for hapi
+- [@hapi/crumb](https://github.com/hapijs/crumb) - CSRF crumb generation and validation
+- [@hapi/yar](https://github.com/hapijs/yar) - Session manager
+- [@hapi/vision](https://github.com/hapijs/vision) - Template rendering support
+
+Additional npm dependencies that you will need are:
+
+`npm install nunjucks govuk-frontend --save`
+
+- [nunjucks](https://www.npmjs.com/package/nunjucks) - [templating engine](https://mozilla.github.io/nunjucks/) used by GOV.UK design system
+- [govuk-frontend](https://www.npmjs.com/package/govuk-frontend) - [code](https://github.com/alphagov/govuk-frontend) you need to build a user interface for government platforms and services
+
+Optional dependencies
+
+`npm install @hapi/inert --save`
+
+- [@hapi/inert](https://www.npmjs.com/package/@hapi/inert) - static file and directory handlers for serving GOV.UK assets and styles
+
+## Setup
+
+### Form config
+
+The `form-engine-plugin` uses JSON configuration files to serve form journeys.
+These files are called `Form definitions` and are built up of:
+
+- `pages` - includes a `path`, `title`
+- `components` - one or more questions on a page
+- `conditions` - used to conditionally show and hide pages and
+- `lists` - data used to in selection fields like [Select](https://design-system.service.gov.uk/components/select/), [Checkboxes](https://design-system.service.gov.uk/components/checkboxes/) and [Radios](https://design-system.service.gov.uk/components/radios/)
+
+The [types](https://github.com/DEFRA/forms-designer/blob/main/model/src/form/form-definition/types.ts), `joi` [schema](https://github.com/DEFRA/forms-designer/blob/main/model/src/form/form-definition/index.ts) and the [examples](test/form/definitions) folder are a good place to learn about the structure of these files.
+
+TODO - Link to wiki for `Form metadata`
+TODO - Link to wiki for `Form definition`
+
+#### Providing form config to the engine
+
+The engine plugin registers several [routes](https://hapi.dev/tutorials/routing/?lang=en_US) on the hapi server.
+
+They look like this:
+
+```
+GET     /{slug}/{path}
+POST    /{slug}/{path}
+```
+
+A unique `slug` is used to route the user to the correct form, and the `path` used to identify the correct page within the form to show.
+The [plugin registration options](#options) have a `services` setting to provide a `formsService` that is responsible for returning `form definition` data.
+
+WARNING: This below is subject to change
+
+A `formsService` has two methods, one for returning `formMetadata` and another to return `formDefinition`s.
+
+```
+const formsService = {
+  getFormMetadata: async function (slug) {
+    // Returns the metadata for the slug
+  },
+  getFormDefinition: async function (id, state) {
+    // Returns the form definition for the given id
+  }
+}
+```
+
+The reason for the two separate methods is caching.
+`formMetadata` is a lightweight record designed to give top level information about a form.
+This method is invoked for every page request.
+
+Only when the `formMetadata` indicates that the definition has changed is a call to `getFormDefinition` is made.
+The response from this can be quite big as it contains the entire form definition.
+
+See [example](#example) below for more detail
+
+### Static assets and styles
+
+TODO
+
+## Example
+
+```
+import hapi from '@hapi/hapi'
+import yar from '@hapi/yar'
+import crumb from '@hapi/crumb'
+import inert from '@hapi/inert'
+import pino from 'hapi-pino'
+import plugin from '@defra/forms-engine-plugin'
+
+const server = hapi.server({
+  port: 3000
+})
+
+// Register the dependent plugins
+await server.register(pino)
+await server.register(inert)
+await server.register(crumb)
+await server.register({
+  plugin: yar,
+  options: {
+    cookieOptions: {
+      password: 'ENTER_YOUR_SESSION_COOKIE_PASSWORD_HERE' // Must be > 32 chars
+    }
+  }
+})
+
+// Register the `forms-engine-plugin`
+await server.register({
+  plugin
+})
+
+await server.start()
+```
+
+## Environment variables
+
+## Options
+
+The forms plugin is configured with [registration options](https://hapi.dev/api/?v=21.4.0#plugins)
+
+- `services` (optional) - object containing `formsService`, `formSubmissionService` and `outputService`
+  - `formsService` - used to load `formMetadata` and `formDefinition`
+  - `formSubmissionService` - used prepare the form during submission (ignore - subject to change)
+  - `outputService` - used to save the submission
+- `controllers` (optional) - Object map of custom page controllers used to override the default. See [custom controllers](#custom-controllers)
+- `filters` (optional) - A map of custom template filters to include
+- `cacheName` (optional) - The cache name to use. Defaults to hapi's [default server cache]. Recommended for production. See [here]
+  (#custom-cache) for more details
+- `pluginPath` (optional) - The location of the plugin (defaults to `node_modules/@defra/forms-engine-plugin`)
+
+### Services
+
+TODO
+
+### Custom controllers
+
+TODO
+
+### Custom filters
+
+Use the `filter` plugin option to provide custom template filters.
+Filters are available in both [nunjucks](https://mozilla.github.io/nunjucks/templating.html#filters) and [liquid](https://liquidjs.com/filters/overview.html) templates.
+
+```
+const formatter = new Intl.NumberFormat('en-GB')
+
+await server.register({
+  plugin,
+  options: {
+    filters: {
+      money: value => formatter.format(value),
+      upper: value => typeof value === 'string' ? value.toUpperCase() : value
+    }
+  }
+})
+```
+
+### Custom cache
+
+The plugin will use the [default server cache](https://hapi.dev/api/?v=21.4.0#-serveroptionscache) to store form answers on the server.
+This is just an in-memory cache which is fine for development.
+
+In production you should create a custom cache one of the available `@hapi/catbox` adapters.
+
+E.g. [Redis](https://github.com/hapijs/catbox-redis)
+
+```
+import { Engine as CatboxRedis } from '@hapi/catbox-redis'
+
+const server = new Hapi.Server({
+  cache : [
+    {
+      name: 'my_cache',
+      provider: {
+        constructor: CatboxRedis,
+        options: {}
+      }
+    }
+  ]
+})
+```
+
+## Exemplar
+
+TODO: Link to CDP exemplar
 
 ## Templates
 
 The following elements support [LiquidJS templates](https://liquidjs.com/):
 
 - Page **title**
-- Form component **titles**
+- Form component **title**
   - Support for fieldset legend text or label text
   - This includes when the title is used in **error messages**
 - Html (guidance) component **content**
@@ -85,3 +279,20 @@ There are a number of `LiquidJS` filters available to you from within the templa
   }
 ]
 ```
+
+## Templates and views: Extending the default layout
+
+TODO
+
+To override the default page template, vision and nunjucks both need to be configured to search in the `forms-engine-plugin` views directory when looking for template files.
+
+For vision this is done through the `path` [plugin option](https://github.com/hapijs/vision/blob/master/API.md#options)
+For nunjucks it is configured through the environment [configure options](https://mozilla.github.io/nunjucks/api.html#configure).
+
+The `forms-engine-plugin` path to add can be imported from:
+
+`import { VIEW_PATH } from '@defra/forms-engine-plugin'`
+
+Which can then be appended to the `node_modules` path `node_modules/@defra/forms-engine`.
+
+The main template layout is `govuk-frontend`'s `template.njk` file, this also needs to be added to the `path`s that nunjucks can look in.

package/package.json

@@ -1,12 +1,13 @@
 {
   "name": "@defra/forms-engine-plugin",
-  "version": "0.0.4",
+  "version": "0.0.6",
   "description": "Defra forms engine",
   "type": "module",
   "main": ".server/server/plugins/engine/index.js",
   "files": [
     ".server",
-    ".public"
+    ".public",
+    "src"
   ],
   "scripts": {
     "build": "npm run build:server && npm run build:client",
@@ -59,7 +60,6 @@
     "@hapi/vision": "^7.0.3",
     "@hapi/wreck": "^18.1.0",
     "@hapi/yar": "^11.0.2",
-    "@hapipal/schmervice": "^3.0.0",
     "@types/humanize-duration": "^3.27.4",
     "accessible-autocomplete": "^3.0.1",
     "atob": "^2.1.2",

package/src/client/javascripts/application.js

@@ -0,0 +1,87 @@
+import {
+  Button,
+  CharacterCount,
+  Checkboxes,
+  ErrorSummary,
+  Header,
+  NotificationBanner,
+  Radios,
+  SkipLink,
+  createAll
+} from 'govuk-frontend'
+
+createAll(Button)
+createAll(CharacterCount)
+createAll(Checkboxes)
+createAll(ErrorSummary)
+createAll(Header)
+createAll(NotificationBanner)
+createAll(Radios)
+createAll(SkipLink)
+
+// Show preview close link via `rel="opener"`
+if (window.opener) {
+  const $closeLink = document.querySelector('.js-preview-banner-close')
+
+  $closeLink?.removeAttribute('hidden')
+  $closeLink?.addEventListener('click', (event) => {
+    event.preventDefault()
+    window.close()
+  })
+}
+
+/**
+ * Initialise autocomplete
+ * @param {HTMLSelectElement | null} $select
+ * @param {(config: object) => void} init
+ */
+function initAutocomplete($select, init) {
+  if (!$select) {
+    return
+  }
+
+  const config = {
+    id: $select.id,
+    selectElement: $select
+  }
+
+  init(config)
+
+  /** @type {HTMLInputElement | null} */
+  const $input = document.querySelector(`#${config.id}`)
+
+  // Allowed values for input
+  const inputValues = [...$select.options].map((option) => option.text)
+
+  // Reset select when input value is not allowed
+  $input?.addEventListener('blur', () => {
+    if (!$input.value || !inputValues.includes($input.value)) {
+      $select.value = ''
+    }
+  })
+}
+
+// Find all autocompletes
+const $autocompletes = document.querySelectorAll(
+  `[data-module="govuk-accessible-autocomplete"]`
+)
+
+// Lazy load autocomplete component
+if ($autocompletes.length) {
+  // @ts-expect-error -- No types available
+  import('accessible-autocomplete')
+    .then((component) => {
+      const { default: accessibleAutocomplete } = component
+
+      // Initialise each autocomplete
+      $autocompletes.forEach(($module) =>
+        initAutocomplete(
+          $module.querySelector('select'),
+          accessibleAutocomplete.enhanceSelectElement
+        )
+      )
+    })
+
+    // eslint-disable-next-line no-console
+    .catch(console.error)
+}