From 09d5b0b1c34e1af2be91e2f00592c11ed8b8f8e0 Mon Sep 17 00:00:00 2001 From: Mark Green Date: Wed, 22 Jul 2020 16:16:24 +0100 Subject: [PATCH] Add docs on using Nunjucks macros --- source/installing-with-npm/index.html.md.erb | 2 +- .../index.html.md.erb | 2 +- source/use-nunjucks/index.html.md.erb | 70 +++++++++++++++++++ 3 files changed, 72 insertions(+), 2 deletions(-) create mode 100644 source/use-nunjucks/index.html.md.erb diff --git a/source/installing-with-npm/index.html.md.erb b/source/installing-with-npm/index.html.md.erb index c5c02fc2..946f84f6 100644 --- a/source/installing-with-npm/index.html.md.erb +++ b/source/installing-with-npm/index.html.md.erb @@ -24,7 +24,7 @@ weight: 10 GOV.UK Frontend also works with Ruby Sass version 3.4.0 or higher, but we recommend you do not use Ruby Sass because it's been deprecated. -You can also [install Nunjucks v3.0.0 or later](https://www.npmjs.com/package/nunjucks) if you want to [use GOV.UK Frontend's Nunjucks macros](https://design-system.service.gov.uk/get-started/production/#using-nunjucks-macros). +You can also [install Nunjucks v3.0.0 or later](https://www.npmjs.com/package/nunjucks) if you want to [use GOV.UK Frontend's Nunjucks macros](/use-nunjucks/). ## Install GOV.UK Frontend diff --git a/source/migrating-from-legacy-products/index.html.md.erb b/source/migrating-from-legacy-products/index.html.md.erb index 29e22387..ffeb82d6 100644 --- a/source/migrating-from-legacy-products/index.html.md.erb +++ b/source/migrating-from-legacy-products/index.html.md.erb @@ -34,7 +34,7 @@ If you use macros, your project will be: - easier to migrate, because your project will be organised the same way we organise the GOV.UK Design System - easier to update when new versions of GOV.UK Frontend are released -If you're using Node.js, you can use [our Nunjucks macros](https://design-system.service.gov.uk/styles/page-template/#nunjucks). You'll need to [install Nunjucks](https://mozilla.github.io/nunjucks/getting-started.html) first. +If you're using Node.js, you can [use our Nunjucks macros](/use-nunjucks/). Each [component page](https://design-system.service.gov.uk/components/) on the GOV.UK Design System website has example Nunjucks macros and a table of macro options. diff --git a/source/use-nunjucks/index.html.md.erb b/source/use-nunjucks/index.html.md.erb new file mode 100644 index 00000000..1e356b9c --- /dev/null +++ b/source/use-nunjucks/index.html.md.erb @@ -0,0 +1,70 @@ +--- +title: Use Nunjucks +weight: 45 +--- + +# Use Nunjucks + +You can use our Nunjucks code to generate the HTML for pages and components. + +You can also change the HTML that's generated by passing options into the Nunjucks code. + +If you use Nunjucks, your application will be easier to update when a new version of GOV.UK Frontend is released. + +To use Nunjucks, your application and any frameworks that support your application must use Node.js. + +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). + +## Before you start + +You must first: + +- [install GOV.UK Frontend with Node.js package manager (npm)](/installing-with-npm/) +- make sure you’ve installed Nunjucks so it’s working in your environment + +## Set up Nunjucks and use the page template + +1. Add `node_modules/govuk-frontend/` to your list of Nunjucks paths, so Nunjucks knows where to find the GOV.UK Frontend template and components. + + For example: + + ```javascript + nunjucks.configure([ + "node_modules/govuk-frontend/", + "YOUR-VIEWS-FOLDER" + ]) + ``` + +2. Use the GOV.UK Frontend template by adding the following at the top of your view file: + + ```javascript + {% extends "govuk/template.njk" %} + ``` + +3. Go to the [default page template example](https://design-system.service.gov.uk/styles/page-template/#default) on the GOV.UK Design System website, then copy the Nunjucks code into your view file. + +You may need to change the paths in the Nunjucks code to [get the CSS, assets and JavaScript working](/importing-css-assets-and-javascript). + +Find out how to [change how the page template works](https://design-system.service.gov.uk/styles/page-template/#changing-template-content). + +## Adding a component + +Go to any component page on the Design System website, then copy the Nunjucks macro code from the **Nunjucks** tab of any example. + +For example, to add the breadcrumbs component to your page, copy the code from the **Nunjucks** tab in the first example on the [breadcrumbs component page](https://design-system.service.gov.uk/components/breadcrumbs/). + +## Changing a component + +You can use options to change how a component looks or behaves. + +For example, use the `text` option to change the text on a [button](https://design-system.service.gov.uk/components/button/): + +```javascript +{{ govukButton({ + text: "Example button text" +}) }} +``` + +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. You can read more about [XSS](https://developer.mozilla.org/en-US/docs/Web/Security/Types_of_attacks#Cross-site_scripting_XSS) on the MDN website. \ No newline at end of file