Merge pull request #965 from alphagov/update-tutorial-use-components

Update tutorial to use components

docs/documentation/make-first-prototype/let-user-change-answers.md

@@ -7,35 +7,57 @@ Make the **Change** links on the ‘Check your answers’ page work by adding th
 1. In the the `<a>` tag under `{{ data['how-many-balls'] }}`, change the href attribute from `#` to `/juggling-balls`
 2. In the the `<a>` tag under `{{ data['most-impressive-trick'] }}`, change the href attribute from `#` to `/juggling-trick`
 
-If you select a **Change** link, you’ll go back to the right question page, but your answer will not appear.
+If you select a **Change** link, you’ll go back to the right question page, but your answer will not appear yet.
 
-## Show the user's answer in question 1
+## Show the user’s answer in question 1
 
-Add Nunjucks code to show the user's answer in a radios or checkbox component.
+Radios and checkboxes have a `checked` option to set whether they are selected (checked) or not when the page loads.
 
-Open the `juggling-balls.html` file in your `app/views` folder, and add:
+Open the `juggling-balls.html` file in your `app/views` folder.
 
-- `{{ checked("how-many-balls", "3 or more") }}` inside the first `<input>` tag
-- `{{ checked("how-many-balls", "1 or 2") }}` inside the second `<input>` tag
-- `{{ checked("how-many-balls", "None - I cannot juggle") }}` inside the third `<input>` tag
+For each of the `items`, we’ll add a `checked` value, like this:
 
-For example your first input tag should now be:
-
-```html
-<input class="govuk-radios__input" id="how-many-balls" name="how-many-balls" type="radio" value="3 or more" {{ checked("how-many-balls", "3 or more") }} >
 ```
-
-Make sure the spelling is exactly the same as the 3 `value` attributes you added when you [created your question pages](create-pages).
+    {
+        value: "3 or more",
+        text: "3 or more",
+        checked: checked("how-many-balls", "3 or more")
+    },
+    {
+        value: "1 or 2",
+        text: "1 or 2",
+        checked: checked("how-many-balls", "1 or 2")
+    },
+    {
+        value: "None - I cannot juggle",
+        text: "None - I cannot juggle",
+        checked: checked("how-many-balls", "None - I cannot juggle")
+    }
+```
+In each case make sure the spelling is exactly the same as the `value`.
 
 Go to [http://localhost:3000/juggling-balls](http://localhost:3000/juggling-balls) and check the journey works by selecting an answer, continuing to the next page, then going back.
 
-## Show the user's answer in question 2
+## Show the user’s answer in question 2
+
+Text inputs and textareas have a `value` to set what text appears in them when the page loads.
 
-To show the user's answer in a `textarea`, add the same Nunjucks code you [added to the 'Check your answers' page](show-users-answers#showing-data).
+Open the `juggling-trick.html` file in your `app/views` folder.
 
-1. Open the `juggling-trick.html` file in your `app/views` folder.
-2. Find the `<textarea>` you added earlier.
-3. Add `{{ data['most-impressive-trick'] }}` between the `<textarea>` and `</textarea>` tags. Do not add any space or line breaks.
+Add `value: data['most-impressive-trick']` like this:
+
+```
+{{ govukTextarea({
+    name: "most-impressive-trick",
+    id: "most-impressive-trick",
+    label: {
+        text: "What is your most impressive juggling trick?",
+        classes: "govuk-label--l",
+        isPageHeading: true
+    },
+    value: data['most-impressive-trick']
+}) }}
+```
 
 Go to [http://localhost:3000/juggling-trick](http://localhost:3000/juggling-trick) and check it works by filling in an answer, continuing to the next page, going back, then refreshing your browser.
 

docs/documentation/make-first-prototype/link-pages-together.md

@@ -35,4 +35,4 @@ Go to http://localhost:3000/juggling-trick and select **Continue** to check the
 
 The 'Check your answers' page template links to the ‘Confirmation’ page by default. So you do not need to change the ‘Check your answers’ page.
 
-[Next (add questions to your question pages)](add-questions)
+[Next (use components from the Design System)](use-components)

docs/documentation/make-first-prototype/use-components-2.md

@@ -0,0 +1,33 @@
+# Add a textarea to question 2
+
+1. Go to the [textarea](https://design-system.service.gov.uk/components/textarea/) page of the Design System.
+2. Select the **Nunjucks** tab, then **Copy code**.
+3. Open `juggling-trick.html` in your `app/views` folder.
+4. Replace the 2 example `<p>...</p>` paragraphs with the code you copied. 
+5. Delete the old `<h1>` tag with "What is your most impressive juggling trick?" (again the example code comes with an accessible heading for the question).
+
+### Customise the example code
+
+1. Under `label`, change `text` from "Can you provide more detail?" to "What is your most impressive juggling trick?".
+2. Change the `id` and `name` to `most-impressive-trick`.
+3. We don’t need a hint, so remove it and the comma just before it.
+
+Your component code should now look like this:
+
+```
+{{ govukTextarea({
+  name: "most-impressive-trick",
+  id: "most-impressive-trick",
+  label: {
+    text: "What is your most impressive juggling trick?",
+    classes: "govuk-label--l",
+    isPageHeading: true
+  }
+}) }}
+```
+
+Your page should now look like this:
+
+![Screenshot of the question page with a textarea](/public/images/docs/tutorial-textarea.png)
+
+[Next (Show the user’s answers on your ‘Check your answers’ page)](show-users-answers)

docs/documentation/make-first-prototype/use-components.md

@@ -0,0 +1,72 @@
+# Use components from the Design System
+
+You can copy example code from the GOV.UK Design System to add page elements like radios and text inputs - we call these ‘components’.
+
+## HTML and Nunjucks
+
+HTML is the language used to create web pages.
+
+Nunjucks is another language we can run in the Prototype Kit, to make HTML for us. Short, simple Nunjucks code can create much longer, more complex HTML.
+
+In the Design System, components have both Nunjucks and HTML example code. Either will work in the Prototype Kit.
+
+## Add radios to question 1
+
+1. Go to the [stacked radios](https://design-system.service.gov.uk/components/radios/#stacked-radios) section of the Design System.
+2. Select the **Nunjucks** tab, then **Copy code**.
+3. Open `juggling-balls.html` in your `app/views` folder.
+4. Replace the 2 example `<p>...</p>` paragraphs with the code you copied.
+5. The example comes with a heading that is connected to the answers for accessibility, so delete the old `<h1>` tag with "How many balls can you juggle?".
+
+### Customise the example code
+
+1. Under `legend`, change `text` from "Where do you live?" to "How many balls can you juggle?".
+2. Change the `idPrefix` and `name` to `how-many-balls`.
+3. We only want 3 options not 4, so delete the last of the `items` including the comma from the previous item:
+```
+    ,
+    {
+        value: "northern-ireland",
+        text: "Northern Ireland"
+    }
+```
+4. Change the `value` and `text` in the `items` to:
+  - 3 or more
+  - 1 or 2
+  - None - I cannot juggle
+
+Your component code should now look like this:
+
+```
+{{ govukRadios({
+  idPrefix: "how-many-balls",
+  name: "how-many-balls",
+  fieldset: {
+    legend: {
+      text: "How many balls can you juggle?",
+      isPageHeading: true,
+      classes: "govuk-fieldset__legend--l"
+    }
+  },
+  items: [
+    {
+      value: "3 or more",
+      text: "3 or more"
+    },
+    {
+      value: "1 or 2",
+      text: "1 or 2"
+    },
+    {
+      value: "None - I cannot juggle",
+      text: "None - I cannot juggle"
+    }
+  ]
+}) }}
+```
+
+Your page should now look like this:
+
+![Screenshot of the question page with radios](/public/images/docs/tutorial-radios.png)
+
+[Next (add a textarea to question 2)](use-components-2)

docs/documentation_routes.js

@@ -82,6 +82,10 @@ router.get('/making-pages', function (req, res) {
   res.redirect('/docs/make-first-prototype/create-pages')
 })
 
+router.get('/add-questions', function (req, res) {
+  res.redirect('/docs/make-first-prototype/use-components')
+})
+
 module.exports = router
 
 // Strip off markdown extensions if present and redirect

docs/views/tutorials-and-examples.html

@@ -65,7 +65,7 @@ <h3 class="govuk-heading-s">Get started</h3>
               <a href="/docs/make-first-prototype/link-pages-together">Link your pages together</a>
             </li>
             <li>
-              <a href="/docs/make-first-prototype/add-questions">Add questions</a>
+              <a href="/docs/make-first-prototype/use-components">Use components from the Design System</a>
             </li>
             <li>
               <a href="/docs/make-first-prototype/show-users-answers">Show the user's answers</a>