Skip to content

Commit b5a4ef9

Browse files
mokhldmokhld
authored
chore(docs): PLUGIN_OPTIONS documentation with required and optional options, including detailed explanations for nunjucks configuration, viewContext, and model usage. Add examples for clarity. (#221)
1 parent d222299 commit b5a4ef9

File tree

1 file changed

+158
-7
lines changed

1 file changed

+158
-7
lines changed

‎docs/PLUGIN_OPTIONS.md‎

Lines changed: 158 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -9,21 +9,29 @@ nav_order: 3
99

1010
The forms plugin is configured with [registration options](https://hapi.dev/api/?v=21.4.0#plugins)
1111

12+
## Required options
13+
14+
- `nunjucks` (required) - Template engine configuration. See [nunjucks configuration](#nunjucks-configuration)
15+
- `viewContext` (required) - A function that provides global context to all templates. See [viewContext](#viewcontext)
16+
- `baseUrl` (required) - Base URL of the application (protocol and hostname, e.g., `"https://myservice.gov.uk"`). Used for generating absolute URLs in markdown rendering and other contexts
17+
18+
## Optional options
19+
20+
- `model` (optional) - Pre-built `FormModel` instance. When provided, the plugin serves a single static form definition. When omitted, forms are loaded dynamically via `formsService`. See [model](#model)
1221
- `services` (optional) - object containing `formsService`, `formSubmissionService` and `outputService`
1322
- `formsService` - used to load `formMetadata` and `formDefinition`
1423
- `formSubmissionService` - used prepare the form during submission (ignore - subject to change)
1524
- `outputService` - used to save the submission
1625
- `controllers` (optional) - Object map of custom page controllers used to override the default. See [custom controllers](#custom-controllers)
17-
- `globals` (optional) - A map of custom template globals to include
18-
- `filters` (optional) - A map of custom template filters to include
19-
- `cache` (optional) - Caching options
20-
- `cache` (optional) - Caching options. Recommended for production. This can be either:
21-
- a string representing the cache name to use (e.g. hapi's default server cache). See [here](#custom-cache) for more details.
22-
- a custom `CacheService` instance implementing your own caching logic
26+
- `globals` (optional) - A map of custom template globals to include. See [custom globals](#custom-globals)
27+
- `filters` (optional) - A map of custom template filters to include. See [custom filters](#custom-filters)
28+
- `cache` (optional) - Caching options. Recommended for production. This can be either:
29+
- a string representing the cache name to use (e.g. hapi's default server cache). See [custom cache](#custom-cache) for more details.
30+
- a custom `CacheService` instance implementing your own caching logic
2331
- `pluginPath` (optional) - The location of the plugin (defaults to `node_modules/@defra/forms-engine-plugin`)
2432
- `preparePageEventRequestOptions` (optional) - A function that will be invoked for http-based [page events](./features/configuration-based/PAGE_EVENTS.md). See [here](./features/configuration-based/PAGE_EVENTS.md#authenticating-a-http-page-event-request-from-dxt-in-your-api) for details
2533
- `saveAndExit` (optional) - Configuration for custom session management including key generation, session hydration, and persistence. See [save and exit documentation](./features/code-based/SAVE_AND_EXIT.md) for details
26-
- `onRequest` (optional) - A function that will be invoked on each request to any form route e.g `/{slug}/{path}`. See [here](#onrequest) for more details
34+
- `onRequest` (optional) - A function that will be invoked on each request to any form route e.g `/{slug}/{path}`. See [onRequest](#onrequest) for more details
2735

2836
## Services
2937

@@ -33,6 +41,149 @@ See [our services documentation](./features/code-based/CUSTOM_SERVICES.md).
3341

3442
TODO
3543

44+
## nunjucks configuration
45+
46+
The `nunjucks` option is required and configures the template engine paths and layout.
47+
48+
```ts
49+
{
50+
baseLayoutPath: string // Path to the base layout template
51+
paths: string[] // Array of paths to search for Nunjucks templates
52+
}
53+
```
54+
55+
Example:
56+
57+
```js
58+
await server.register({
59+
plugin,
60+
options: {
61+
nunjucks: {
62+
baseLayoutPath: 'layout.html',
63+
paths: [
64+
'src/server/views',
65+
'node_modules/govuk-frontend/dist'
66+
]
67+
}
68+
}
69+
})
70+
```
71+
72+
The `baseLayoutPath` is the file that all form pages will extend. The `paths` array tells Nunjucks where to look for templates, including your custom templates and any third-party template libraries (like GOV.UK Frontend).
73+
74+
## viewContext
75+
76+
The `viewContext` option is a required function that provides global context variables to all templates rendered by the plugin.
77+
78+
```ts
79+
type ViewContext = (
80+
request: AnyFormRequest | null
81+
) => Record<string, unknown> | Promise<Record<string, unknown>>
82+
```
83+
84+
This function receives the current request (or `null` for non-request contexts) and should return an object containing any data you want available in your templates, such as:
85+
86+
- Application version
87+
- Asset paths
88+
- Configuration values
89+
- CSRF tokens
90+
- User session data
91+
- Feature flags
92+
93+
Example:
94+
95+
```js
96+
import pkg from './package.json' with { type: 'json' }
97+
98+
await server.register({
99+
plugin,
100+
options: {
101+
viewContext: (request) => {
102+
return {
103+
appVersion: pkg.version,
104+
assetPath: '/assets',
105+
config: {
106+
serviceName: 'My Service',
107+
phaseTag: 'beta'
108+
},
109+
// Add CSRF token if request exists
110+
crumb: request?.plugins.crumb?.generate?.(request)
111+
}
112+
}
113+
}
114+
})
115+
```
116+
117+
The context returned by this function is merged with the plugin's internal context and made available to all templates.
118+
119+
## model
120+
121+
The `model` option allows you to provide a pre-built `FormModel` instance to serve a single static form definition.
122+
123+
When `model` is provided:
124+
125+
- The plugin serves only that specific form
126+
- No dynamic form loading occurs
127+
- Useful for testing or single-form applications
128+
129+
When `model` is omitted (recommended for production):
130+
131+
- Forms are loaded dynamically via `formsService`
132+
- Multiple forms can be served
133+
- Form definitions can be updated without redeploying
134+
135+
Example (single form):
136+
137+
```js
138+
import { FormModel } from '@defra/forms-engine-plugin/engine/models/FormModel.js'
139+
140+
const definition = await getFormDefinition()
141+
142+
const model = new FormModel(
143+
definition,
144+
{ basePath: '/my-form' },
145+
services
146+
)
147+
148+
await server.register({
149+
plugin,
150+
options: {
151+
model,
152+
// ... other options
153+
}
154+
})
155+
```
156+
157+
## Custom globals
158+
159+
Use the `globals` plugin option to provide custom functions that can be called from within Nunjucks templates.
160+
161+
Unlike filters which transform values, globals are functions that can be called directly in templates.
162+
163+
Example:
164+
165+
```js
166+
await server.register({
167+
plugin,
168+
options: {
169+
globals: {
170+
getCurrentYear: () => new Date().getFullYear(),
171+
formatCurrency: (amount) => new Intl.NumberFormat('en-GB', {
172+
style: 'currency',
173+
currency: 'GBP'
174+
}).format(amount)
175+
}
176+
}
177+
})
178+
```
179+
180+
In your templates:
181+
182+
```html
183+
<p>Copyright {{ getCurrentYear() }}</p>
184+
<p>Total: {{ formatCurrency(123.45) }}</p>
185+
```
186+
36187
## Custom filters
37188

38189
Use the `filter` plugin option to provide custom template filters.

0 commit comments

Comments
 (0)