Skip to content

Commit 5ba9745

Browse files
alexluckettalexluckett
authored
Merge pull request #401 from DEFRA/docs/page-elements
Document view model props
2 parents 9c52146 + 4e1e533 commit 5ba9745

4 files changed

Lines changed: 189 additions & 0 deletions

File tree

‎docs/features/index.md‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -10,6 +10,10 @@ A library of built-in form components — text fields, date inputs, radio button
1010

1111
Built-in page controllers that define how a page behaves — question pages, repeating groups, file upload pages, summary and confirmation pages.
1212

13+
## [Page Elements](./features/page-elements)
14+
15+
View model properties that the plugin provides for page-level GOV.UK Frontend components — back link, phase banner, page title, service navigation, and footer — which your base layout template must render.
16+
1317
## Advanced
1418

1519
### [Configuration-based Features](./features/configuration-based)

‎docs/features/page-elements.mdx‎

Lines changed: 181 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,181 @@
1+
# Page Elements
2+
3+
For each page it renders, the plugin computes a set of view model properties and makes them available to your base layout template — set via `baseLayoutPath` in the [plugin options](../plugin-options.md#nunjucks-configuration). Some of these map directly to GOV.UK Frontend components (back link, phase banner, error summary, service navigation). Others are general metadata about the current page or form (title, name, slug) that your layout can use however it needs to.
4+
5+
None of these are required. The form journey will function without any of them, but omitting them may result in a degraded experience: missing back links, no phase banner, inaccessible page titles, and so on. Use whichever ones apply to your service.
6+
7+
The template block names in the examples below follow the [GOV.UK Frontend page template](https://design-system.service.gov.uk/styles/page-template/).
8+
9+
| Property | Type | Description |
10+
|----------|------|-------------|
11+
| `backLink` | `{ text: string; href: string } \| undefined` | Back link macro params, or `undefined` if there is no back navigation |
12+
| `pageTitle` | `string` | Title of the current page |
13+
| `name` | `string \| undefined` | Form name from the form definition |
14+
| `phaseTag` | `string \| undefined` | Phase label from the form definition's `phaseBanner.phase` setting |
15+
| `feedbackLink` | `string \| undefined` | URL of the built-in feedback form, or `undefined` if feedback is disabled |
16+
| `serviceUrl` | `string` | Root URL of the current form |
17+
| `errors` | `FormSubmissionError[] \| undefined` | Validation errors for the current page |
18+
19+
---
20+
21+
## Back link
22+
23+
**Property:** `backLink: { text: string; href: string } | undefined`
24+
25+
The plugin automatically calculates the back link for each page based on the user's journey. The value is ready to pass directly to the GOV.UK Frontend [Back link](https://design-system.service.gov.uk/components/back-link/) macro.
26+
27+
Add the following to your base layout's `beforeContent` block:
28+
29+
```njk
30+
{% from "govuk/components/back-link/macro.njk" import govukBackLink %}
31+
32+
{% block beforeContent %}
33+
{% if backLink %}
34+
{{ govukBackLink(backLink) }}
35+
{% endif %}
36+
{% endblock %}
37+
```
38+
39+
`backLink` is `undefined` on pages with no back navigation — for example, the start page and confirmation page.
40+
41+
<div className="component-preview app-no-prose">
42+
<div dangerouslySetInnerHTML={{ __html: `<a href="#" class="govuk-back-link">Back</a>` }} />
43+
</div>
44+
45+
---
46+
47+
## Phase banner
48+
49+
**Properties:** `phaseTag: string | undefined`, `feedbackLink: string | undefined`
50+
51+
The plugin provides both values for rendering a GOV.UK Frontend [Phase banner](https://design-system.service.gov.uk/components/phase-banner/).
52+
53+
- `phaseTag` comes from the form definition's `phaseBanner.phase` property.
54+
- `feedbackLink` is the URL of the built-in form feedback page (`/form/feedback?formId=...`). It is `undefined` when user feedback is disabled via `disableUserFeedback` in the form definition's options.
55+
56+
If either value is not set by the form definition, you can fall back to a value from your own service configuration:
57+
58+
```njk
59+
{% from "govuk/components/phase-banner/macro.njk" import govukPhaseBanner %}
60+
61+
{% set phaseTag = phaseTag or config.phaseTag %}
62+
{% set feedbackLink = feedbackLink or config.feedbackLink %}
63+
64+
{% if phaseTag %}
65+
{{ govukPhaseBanner({
66+
tag: { text: phaseTag | capitalize },
67+
html: '<a class="govuk-link govuk-link--no-visited-state" href="' + feedbackLink + '" target="_blank" rel="noopener noreferrer">Give feedback</a>'
68+
}) }}
69+
{% endif %}
70+
```
71+
72+
<div className="component-preview app-no-prose">
73+
<div dangerouslySetInnerHTML={{ __html: `<div class="govuk-phase-banner">
74+
<p class="govuk-phase-banner__content">
75+
<strong class="govuk-tag govuk-phase-banner__content__tag">
76+
Beta
77+
</strong>
78+
<span class="govuk-phase-banner__text">
79+
This is a new service – <a class="govuk-link govuk-link--no-visited-state" href="#">give feedback</a>.
80+
</span>
81+
</p>
82+
</div>` }} />
83+
</div>
84+
85+
---
86+
87+
## Error summary
88+
89+
**Property:** `errors: FormSubmissionError[] | undefined`
90+
91+
The plugin populates `errors` with validation failures when a page is submitted with invalid input. Pass it to the GOV.UK Frontend [Error summary](https://design-system.service.gov.uk/components/error-summary/) component, which must appear at the top of the main content area, above the page heading.
92+
93+
The plugin's own page views already render the error summary. This property is listed here because your `pageTitle` block should prefix the title with `"Error: "` when errors are present — a GDS accessibility requirement.
94+
95+
```njk
96+
{% block pageTitle %}
97+
{{ "Error: " if errors | length }}{{ pageTitle }} - {{ name }} - GOV.UK
98+
{% endblock %}
99+
```
100+
101+
<div className="component-preview app-no-prose">
102+
<div dangerouslySetInnerHTML={{ __html: `<div class="govuk-error-summary" data-module="govuk-error-summary">
103+
<div role="alert">
104+
<h2 class="govuk-error-summary__title">
105+
There is a problem
106+
</h2>
107+
<div class="govuk-error-summary__body">
108+
<ul class="govuk-list govuk-error-summary__list">
109+
<li>
110+
<a href="#dob">Enter your date of birth</a>
111+
</li>
112+
<li>
113+
<a href="#email">Enter an email address in the correct format, like name@example.com</a>
114+
</li>
115+
</ul>
116+
</div>
117+
</div>
118+
</div>` }} />
119+
</div>
120+
121+
---
122+
123+
## Page title
124+
125+
**Property:** `pageTitle: string`
126+
127+
The title of the current form page. Use it in your layout's `pageTitle` block to populate the browser `<title>` element. `name` is the form name from the form definition:
128+
129+
```njk
130+
{% block pageTitle %}
131+
{{ "Error: " if errors | length }}{{ pageTitle }} - {{ name }} - GOV.UK
132+
{% endblock %}
133+
```
134+
135+
When a page has validation errors, prefix the title with `"Error: "`. Screen readers announce the page title on load, so this is what alerts users to the presence of errors before they reach the error summary or individual fields. This pattern is documented in the [GDS error summary guidance](https://design-system.service.gov.uk/components/error-summary/#how-it-works).
136+
137+
---
138+
139+
## Header and service navigation
140+
141+
**Properties:** `serviceUrl: string`, `name: string | undefined`
142+
143+
- `serviceUrl` is the root URL of the current form (e.g. `/my-form`). Use it as the service link in your header so users can return to the start of the form.
144+
- `name` is the form name from the form definition.
145+
146+
The [GOV.UK Service navigation](https://design-system.service.gov.uk/components/service-navigation/) component is recommended for this from GOV.UK Frontend v5.
147+
148+
If your service hosts a single form and the form name is the service name, passing `name` as `serviceName` is appropriate:
149+
150+
```njk
151+
{% from "govuk/components/service-navigation/macro.njk" import govukServiceNavigation %}
152+
153+
{{ govukServiceNavigation({
154+
serviceName: name,
155+
serviceUrl: serviceUrl
156+
}) }}
157+
```
158+
159+
If your service hosts multiple forms, `serviceName` should be your real service name rather than the individual form name. In that case, `name` is more suited as a page-level heading — for example, as an `<h1>` above the form content:
160+
161+
```njk
162+
{{ govukServiceNavigation({
163+
serviceName: "My Service Name",
164+
serviceUrl: "/"
165+
}) }}
166+
167+
<h1 class="govuk-heading-l">{{ name }}</h1>
168+
```
169+
170+
---
171+
172+
## Other available properties
173+
174+
The following properties are also available in the template context. They are used internally by the plugin's own page views but can be accessed in your base layout where needed:
175+
176+
| Property | Description |
177+
|----------|-------------|
178+
| `slug` | The form's URL slug (e.g. `my-form`). Only set on successful page responses — `undefined` on error pages. Commonly used to build per-form footer links (privacy, cookies, accessibility statement). |
179+
| `currentPath` | The current page URL including query string. Useful for building redirect URLs (e.g. cookie preference form actions). |
180+
| `context.isForceAccess` | `true` when a form is being viewed in preview mode. Use this to suppress external navigation links. |
181+
| `previewMode` | Set when the form is in a preview state, indicating which preview mode is active. |

‎docusaurus.config.cjs‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -80,6 +80,7 @@ const config = {
8080
sidebar: [
8181
{ text: 'Components', href: '/features/components' },
8282
{ text: 'Page Types', href: '/features/pages' },
83+
{ text: 'Page Elements', href: '/features/page-elements' },
8384
{
8485
text: 'Advanced',
8586
href: '/features',

‎scripts/component-metadata.json‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -84,6 +84,9 @@
8484
]
8585
},
8686
"componentLinks": {
87+
"UkAddressField": [
88+
"When `usePostcodeLookup` is enabled, the component uses the Ordnance Survey API to find addresses by postcode. This requires the `ordnanceSurveyApiKey` and `ordnanceSurveyApiSecret` [plugin options](../../plugin-options.md#geospatial-map) to be set — without them the component falls back to the manual address entry form regardless of the `usePostcodeLookup` setting."
89+
],
8790
"FileUploadField": [
8891
"This component renders the list of files already in session state, allows the user to remove individual files, and enforces min/max file count constraints. On final form submission it calls `persistFiles()` to move files to permanent storage. It does not handle uploading — that is the responsibility of the page controller. See [`FileUploadPageController`](../pages/file-upload-page.md) for the provided Defra implementation."
8992
],

0 commit comments

Comments
 (0)