Add docs on using Nunjucks macros #67

m-green · 2020-07-22T15:20:55Z

As part of Improving guidance for using Nunjucks docs, this creates a new page in GOV.UK Frontend docs about using Nunjucks macros.

It also updates a couple of links elsewhere in the docs to point to this new page.

Thanks to @hannalaakso for her help pairing to create this new documentation.

netlify · 2020-07-22T15:33:22Z

Deploy preview for govuk-frontend-docs-preview ready!

Built with commit 09d5b0b

https://deploy-preview-67--govuk-frontend-docs-preview.netlify.app

mgladdish · 2020-07-22T16:03:42Z

I'd say "your application and any frameworks that support it must be written in JavaScript" isn't quite right. It's worse than that because, as far as I can tell, Nunjucks can only be used within the browser or within Node. Just using Javascript isn't enough.

mgladdish · 2020-07-22T16:05:07Z

And surely this is about using Nunjucks templates and macros? Not just macros alone? This reads as though you could choose to use Nunjucks templates but not the macros. Which you can't AFAIK.

36degrees

This feels like a great improvement 👏🏻

36degrees · 2020-07-22T16:23:19Z

source/use-nunjucks-macros/index.html.md.erb

+For example, to add the breadcrumbs component to your page, add the following code from the first example on the [breadcrumbs component page](https://design-system.service.gov.uk/components/breadcrumbs/):
+
+```javascript
+{% from "govuk/components/breadcrumbs/macro.njk" import govukBreadcrumbs %}


Are we happy with the risk of this getting out of sync with the first example on the Breadcrumbs page?

Hmm good question. @hannalaakso - is it better to ask users to copy the code from the breadcrumbs page? I can't remember why we specifically included the code now.

Yes good catch @36degrees, I think we can ask users to just copy it from the Design System.

👍 I've updated in 0526b83. The last commit failed so just need to check the new commit is ok.

36degrees · 2020-07-22T16:25:54Z

source/use-nunjucks-macros/index.html.md.erb

+
+To see the options for a component, select the **Nunjucks** tab of the component example on any Design System website page, then select **Nunjucks macro options**.
+
+There’s a different way to [change how the page template works](https://design-system.service.gov.uk/styles/page-template/#changing-template-content).


I initially read this as 'there is a second, alternative way to do this same thing' rather than 'configuring the page template works differently'.

Given this is closely related to configuring the page template, should we mention this in the 'Set up Nunjucks' as well?

Ah good points both. I'll solve both these issues at once by tweaking the language slightly, and moving it to the end of the 'Set up Nunjucks' section where I agree it's a better fit.

36degrees · 2020-07-22T16:27:51Z

source/use-nunjucks-macros/index.html.md.erb

+weight: 45
+---
+
+# Use Nunjucks macros


I wonder if this should just be called 'Use Nunjucks' as it covers two things that work in different ways:

Extending (and configuring) the Nunjucks page template (which is not a macro)

Using the component macros

Introducing them as two distinct things then breaking them into their own sections might help with explaining the fact that e.g. configuring the page template works differently?

Good point, and I'm going to rejig the intro to this page slightly based on this and @mgladdish's second comment above.

m-green · 2020-07-29T12:38:27Z

Thank you for the great feedback @mgladdish. I've iterated on the docs now, including updates from @36degrees's comments, so hopefully the new content is clearer.

36degrees · 2020-08-03T08:52:19Z

source/use-nunjucks/index.html.md.erb

+    })
+    ```
+
+    `autoescape: true` makes the output render as text by default, to help prevent cross-site scripting (XSS) attacks.


This is the default config option for autoescape – is it still worth including?

Oh thanks for pointing this out - we can probably leave this out then.

36degrees · 2020-08-03T08:56:01Z

source/use-nunjucks/index.html.md.erb

+
+1. Make sure you installed Nunjucks when you [installed GOV.UK Frontend with npm](/installing-with-npm).
+
+2. Import the Nunjucks package at the top of your configuration file, for example:


Not sure 'configuration file' is the right term here… it's more likely to be your main application file, whatever that's called…

'Main application file' sounds good to me. We should probably document these terms in our style guide...

36degrees · 2020-08-03T09:13:32Z

source/use-nunjucks/index.html.md.erb

+
+You do not need to follow this guidance to [use Nunjucks macros in the GOV.UK Prototype Kit](https://design-system.service.gov.uk/get-started/prototyping/#using-nunjucks-macros).
+
+## Set up Nunjucks and use the page template


I suspect in most cases, what the user does is going to look quite different to this, depending on what framework they're using. For example, if they're using express they might install express-nunjucks; if they're using eleventy it already has nunjucks installed and support built in.

Hmm this is a good point. I wondered about adding something above the list, along the lines of 'You may need to set up Nunjucks differently depending on the framework you're using'? But I wonder how useful that is (because it doesn't help you if you're not sure what to do). What do you think?

36degrees · 2020-08-03T09:14:46Z

source/use-nunjucks/index.html.md.erb

+
+    `autoescape: true` makes the output render as text by default, to help prevent cross-site scripting (XSS) attacks.
+
+4. Use the GOV.UK Frontend template by adding the following at the top of your view file:


There's a step missing here which is where the configured nunjucks environment is actually hooked in to the view layer of whatever framework they're using.

Unfortunately, what that step looks like is going to depend a lot on what framework is being used.

36degrees · 2020-08-03T09:16:12Z

source/use-nunjucks/index.html.md.erb

+
+To see the options for a component, select the **Nunjucks** tab of the component example on any Design System website page, then select **Nunjucks macro options**.
+
+You must sanitise any HTML you pass in to Nunjucks macros you’re using in your live application, to protect your website against cross-site scripting (XSS) attacks. Talk to your team’s security specialist about how to do this.


I think @vanitabarrett's comment on #70 applies here as well – the chances that there's a clear 'security specialist' to go and talk to for any given team seem slim to me.

m-green · 2020-08-11T14:59:23Z

@36degrees @hannalaakso Updated in 250ad57 and ready for re-review! We've made it clearer that how you set up Nunjucks (generically) will depend on your environment, but our example is for users using Express.

36degrees

Couple of outstanding Express-related comments, but otherwise this is looking good 👍🏻

36degrees · 2020-08-13T16:19:45Z

source/use-nunjucks/index.html.md.erb

+
+## Set up Nunjucks and use the page template
+
+How you set up Nunjucks will depend on your environment. You can do the following to set up Nunjucks if you're using [Express](https://expressjs.com/).


Have we tested this with a clean install of Express? I think at the very least Nunjucks needs to be configured to 'install itself' against the Express app (as per https://mozilla.github.io/nunjucks/api.html#configure)

36degrees · 2020-08-13T16:20:05Z

source/use-nunjucks/index.html.md.erb

+
+    ```javascript
+    nunjucks.configure([
+      "node_modules/govuk-frontend/"


Would this need the user's 'view' folder included as well?

m-green · 2020-08-17T08:34:27Z

Tweaked to focus on Frontend-specific steps following a chat with Ollie on Friday.

36degrees

LGTM 👍🏻

m-green added the documentation Improvements or additions to documentation label Jul 22, 2020

m-green self-assigned this Jul 22, 2020

This was referenced Jul 22, 2020

Update Nunjucks guidance and link to new docs alphagov/govuk-design-system#1311

Merged

Improve guidance for using Nunjucks alphagov/govuk-design-system#1281

Closed

36degrees reviewed Jul 22, 2020

View reviewed changes

m-green force-pushed the add_using_nunjucks_docs branch from 0526b83 to ea3cfaa Compare July 31, 2020 08:31

36degrees reviewed Aug 3, 2020

View reviewed changes

36degrees reviewed Aug 13, 2020

View reviewed changes

36degrees approved these changes Aug 17, 2020

View reviewed changes

Add docs on using Nunjucks macros

09d5b0b

m-green force-pushed the add_using_nunjucks_docs branch from e7234eb to 09d5b0b Compare August 20, 2020 08:32

m-green merged commit cd0d8d6 into master Aug 20, 2020

m-green deleted the add_using_nunjucks_docs branch August 20, 2020 08:39

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Add docs on using Nunjucks macros #67

Add docs on using Nunjucks macros #67

m-green commented Jul 22, 2020 •

edited

Loading

netlify bot commented Jul 22, 2020 •

edited

Loading

mgladdish commented Jul 22, 2020

mgladdish commented Jul 22, 2020

36degrees left a comment

36degrees Jul 22, 2020

m-green Jul 29, 2020

hannalaakso Jul 30, 2020

m-green Jul 31, 2020 •

edited

Loading

36degrees Jul 22, 2020

m-green Jul 29, 2020

36degrees Jul 22, 2020

m-green Jul 29, 2020

m-green commented Jul 29, 2020

36degrees Aug 3, 2020

m-green Aug 3, 2020

36degrees Aug 3, 2020

m-green Aug 3, 2020 •

edited

Loading

36degrees Aug 3, 2020

m-green Aug 3, 2020 •

edited

Loading

36degrees Aug 3, 2020

36degrees Aug 3, 2020

m-green commented Aug 11, 2020

36degrees left a comment

36degrees Aug 13, 2020

36degrees Aug 13, 2020

m-green commented Aug 17, 2020

36degrees left a comment


		To see the options for a component, select the Nunjucks tab of the component example on any Design System website page, then select Nunjucks macro options.

		There’s a different way to [change how the page template works](https://design-system.service.gov.uk/styles/page-template/#changing-template-content).


		1. Make sure you installed Nunjucks when you [installed GOV.UK Frontend with npm](/installing-with-npm).

		2. Import the Nunjucks package at the top of your configuration file, for example:


		You do not need to follow this guidance to [use Nunjucks macros in the GOV.UK Prototype Kit](https://design-system.service.gov.uk/get-started/prototyping/#using-nunjucks-macros).

		## Set up Nunjucks and use the page template


		`autoescape: true` makes the output render as text by default, to help prevent cross-site scripting (XSS) attacks.

		4. Use the GOV.UK Frontend template by adding the following at the top of your view file:


		To see the options for a component, select the Nunjucks tab of the component example on any Design System website page, then select Nunjucks macro options.

		You must sanitise any HTML you pass in to Nunjucks macros you’re using in your live application, to protect your website against cross-site scripting (XSS) attacks. Talk to your team’s security specialist about how to do this.


		## Set up Nunjucks and use the page template

		How you set up Nunjucks will depend on your environment. You can do the following to set up Nunjucks if you're using [Express](https://expressjs.com/).

Add docs on using Nunjucks macros #67

Add docs on using Nunjucks macros #67

Conversation

m-green commented Jul 22, 2020 • edited Loading

netlify bot commented Jul 22, 2020 • edited Loading

mgladdish commented Jul 22, 2020

mgladdish commented Jul 22, 2020

36degrees left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

m-green Jul 31, 2020 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

m-green commented Jul 29, 2020

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

m-green Aug 3, 2020 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

m-green Aug 3, 2020 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

m-green commented Aug 11, 2020

36degrees left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

m-green commented Aug 17, 2020

36degrees left a comment

Choose a reason for hiding this comment

m-green commented Jul 22, 2020 •

edited

Loading

netlify bot commented Jul 22, 2020 •

edited

Loading

m-green Jul 31, 2020 •

edited

Loading

m-green Aug 3, 2020 •

edited

Loading

m-green Aug 3, 2020 •

edited

Loading