You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Page templates are a configuration-way of adding dynamic content to the form UI, such as displaying the answer to a question, or some data from your API. This feature is only used for presentation purposes.
4
+
5
+
Certain elements of your form, such as content blocks or page titles, allow for the use of LiquidJS. LiquidJS is a templating engine that runs alongside Nunjucks to dynamically insert data into the rendered page.
6
+
7
+
A simple example of page templates is to print the answer to a previous question.
8
+
9
+
For example:
10
+
11
+
```json
12
+
{
13
+
"title": "What's your name?",
14
+
"path": "/full-name",
15
+
"components": [
16
+
{
17
+
"name": "applicantFullName",
18
+
"title": "What's your full name?",
19
+
"type": "TextField"
20
+
}
21
+
]
22
+
},
23
+
{
24
+
"path": "/greeting-page",
25
+
"title": "Hello, {{ applicantFullName }}"
26
+
},
27
+
```
28
+
29
+
The above snippet would ask the user for their full name, e.g. "Joe Bloggs". The following page would be titled "Hello, Joe Bloggs".
30
+
31
+
## Why LiquidJS?
32
+
33
+
Nunjucks is the templating library of choice for frontends within Defra. Nunjucks templates are ultimately compiled down into Javascript code and executed, which opens the risk of user-defined code being executed.
34
+
35
+
LiquidJS is a safe alternative that provides very similar functionality to Nunjucks, but is not passed to `eval` or invoked as a function. This allows us to insert dynamic content into our forms using our configuration files, rather than requiring each team to hardcode it into the codebase.
36
+
37
+
The core codebase for DXT uses Nunjucks. LiquidJS is only used from the form definition JSON files.
38
+
39
+
## Where page templates are supported
4
40
5
41
The following elements support [LiquidJS templates](https://liquidjs.com/):
6
42
7
43
- Page **title**
44
+
- jq path: `.title`
8
45
- Form component **title**
46
+
- jq path: `.pages[].components[].title`
9
47
- Support for fieldset legend text or label text
10
48
- This includes when the title is used in **error messages**
11
49
- Html (guidance) component **content**
50
+
- jq path: `.pages[].components[].content`
12
51
- Summary component **row** key title (check answers and repeater summary)
52
+
- Derived from component title
13
53
14
-
## Template Data
54
+
## Template data
15
55
16
56
The data the templates are evaluated against is the raw answers the user has provided up to the page they're currently on.
17
57
For example, given a YesNoField component called `TKsWbP`, the template `{{ TKsWbP }}` would render "true" or "false" depending on how the user answered the question.
18
58
19
59
The current FormContext is also available as `context` in the templates. This allows access to the full data including the path the user has taken in their journey and any miscellaneous data returned from `Page event`s in `context.data`.
20
60
21
-
## Liquid Filters
61
+
Templates should be single line JSON strings, where line breaks are not rendered and are defined as `\n`. Our reccomendation is that template strings are edited separately to the form JSON, before being minified and copied into the JSON.
22
62
23
-
There are a number of `LiquidJS` filters available to you from within the templates:
63
+
## DXT filters
64
+
65
+
There are a number of filters available to you from within the templates:
24
66
25
67
-`page` - returns the page definition for the given path
26
68
-`field` - returns the component definition for the given name
@@ -30,6 +72,10 @@ There are a number of `LiquidJS` filters available to you from within the templa
30
72
31
73
## Examples
32
74
75
+
### Substituting a page title
76
+
77
+
Below is what a form may look like using page templates. It asks the user for their full name, then renders the following page with their name in the title. For example, "Are you in England, Joe Bloggs?".
78
+
33
79
```json
34
80
"pages": [
35
81
{
@@ -43,8 +89,8 @@ There are a number of `LiquidJS` filters available to you from within the templa
43
89
}
44
90
]
45
91
},
46
-
// This example shows how a component can use an answer to a previous question (What's your full name) in it's title
47
92
{
93
+
"_comment": "This example shows how a component can use an answer to a previous question (What's your full name) in it's title",
48
94
"title": "Are you in England?",
49
95
"path": "/are-you-in-england",
50
96
"components": [
@@ -54,30 +100,47 @@ There are a number of `LiquidJS` filters available to you from within the templa
54
100
"type": "YesNoField"
55
101
}
56
102
]
57
-
},
58
-
// This example shows how a Html (guidance) component can use the available filters to get the form definition and user answers and display them
59
-
{
60
-
"title": "Template example for {{ WmHfSb }}?",
61
-
"path": "/example",
62
-
"components": [
63
-
{
64
-
"title": "Html",
65
-
"type": "Html",
66
-
"content": "<p class=\"govuk-body\">
67
-
// Use Liquid's `assign` to create a variable that holds reference to the \"/are-you-in-england\" page
// Use the href filter to display the full page path
74
-
{{ \"/are-you-in-england\" | href }}<br>
109
+
You may want to do more than just add a dynamic value to the page title. Using the below example, you can create an entire HTML snippet and add it to a page.
75
110
76
-
// Use the `answer` filter to render the user provided answer to a question
77
-
{{ 'TKsWbP' | answer }}
78
-
</p>\n"
79
-
}
80
-
]
81
-
}
82
-
]
111
+
Here is an example of a Liquid template that renders a page title, displays a link to a page called "are you in england" and prints out the answer to a question.
112
+
113
+
```jinja
114
+
<p class="govuk-body">
115
+
{# Use Liquid's `assign` to create a variable that holds reference to the \"/are-you-in-england\" page #}
{# Use the href filter to display the full page path #}
122
+
{{ "/are-you-in-england" | href }}<br>
123
+
124
+
{# Use the `answer` filter to render the user provided answer to a question #}
125
+
{{ 'TKsWbP' | answer }}
126
+
</p>
127
+
```
128
+
129
+
The above template should be minified and inserted into the content field in the form definition example. To make it valid JSON, quotes should be either replaced with `'` or escaped `\"`. Your IDE should do this automatically when pasting the into a JSON string, or a tool like https://www.freeformatter.com/json-escape.html can do it manually.
130
+
131
+
Full example of the minified and escaped component, which can be appended to [the first example's JSON snippet](#substituting-a-page-title).
132
+
133
+
```json
134
+
{
135
+
"_comment": "This example shows how a Html (guidance) component can use the available filters to get the form definition and user answers and display them",
136
+
"title": "Template example for {{ WmHfSb }}?",
137
+
"path": "/example",
138
+
"components": [
139
+
{
140
+
"title": "Html",
141
+
"type": "Html",
142
+
"content": "<p class=\"govuk-body\">\r\n {# Use Liquid's `assign` to create a variable that holds reference to the \\\"\/are-you-in-england\\\" page #}\r\n {%- assign inEngland = \"\/are-you-in-england\" | page -%}\r\n\r\n {# Use the reference to `evaluate` the title #}\r\n {{ inEngland.title | evaluate }}<br>\r\n\r\n {# Use the href filter to display the full page path #}\r\n {{ \"\/are-you-in-england\" | href }}<br>\r\n\r\n {# Use the `answer` filter to render the user provided answer to a question #}\r\n {{ 'TKsWbP' | answer }}\r\n<\/p>"
0 commit comments