Merge pull request #123 from alphagov/use-new-value-option

Update documention to use `value` option

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

@@ -14,36 +14,25 @@ If you select a **Change** link, you’ll go back to the right question page, bu
 
 ## Show the user’s answer in question 1
 
-Radios and checkboxes have a `checked` option to set whether they are selected (checked) or not when the page loads.
+The GOV.UK radios component has a `value` option to set which ones are selected when the page loads. (The same option for checkboxes  is called `values` as checkboxes can have more than one selection.)
 
 Open the `juggling-balls.html` file in your `app/views` folder.
 
-For each of the `items`, we’ll add a `checked` value, like this:
+In the `govukRadios` component, add a `value` line, like this:
 
 ```
-    {
-        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")
-    }
+{{ govukRadios({
+  name: "how-many-balls",
+  value: data['how-many-balls'],
+  fieldset: {
+  ...
 ```
-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
 
-Text inputs and textareas have a `value` to set what text appears in them when the page loads.
+Text inputs and textareas also have a `value` option to set what text appears in them when the page loads.
 
 Open the `juggling-trick.html` file in your `app/views` folder.
 

docs/v13/documentation/pass-data.md

@@ -0,0 +1,133 @@
+---
+heading: Pass data from page to page
+---
+
+
+You may want to use or display data a user has entered over a few screens. The kit automatically stores all data entered, so you can show it later.
+
+To clear the data (for example at the end of a user research session) use the **Clear data** link in the footer.
+
+[An example of what passing data looks like in a prototype](./examples/pass-data/vehicle-registration)
+
+## How to use
+
+The kit stores data from inputs using the `name` attribute of the input.
+
+For example, if you have this input:
+
+```
+{{ govukInput({
+    name: 'first-name'
+}) }}
+```
+
+You can show what the user entered later on like this:
+
+```
+<p>
+    {{ data['first-name'] }}
+</p>
+```
+
+### Showing answers in inputs
+
+If a user goes back to a page where they entered data, they would expect to see the answer they gave.
+
+Most inputs use the `value` option:
+
+```
+{{ govukInput({
+    name: 'first-name',
+    value: data['first-name']
+}) }}
+```
+
+For checkboxes the option is `values`, since more than one can be selected.
+
+### Setting default data
+
+You can set default data in your prototype. This will appear without the user having to enter anything. For example, if you want to prototype a journey where a user previously saved their responses and returned to it later to review or update the information already in the prototype.
+
+If the user changes this data in the prototype, their new answers will be saved.
+
+Add default data to this file:
+
+```
+app/data/session-data-defaults.js
+```
+
+For example to set default data for the inputs for 'First name' and 'Over 18' in the examples above, you would have this in your `session-data-defaults.js` file:
+
+```
+module.exports = {
+
+  'first-name': 'Amina',
+  'over-18': 'yes'
+
+}
+```
+
+## Advanced features
+
+### Checkboxes and radios using HTML
+
+If you are using the HTML components instead of Nunjucks, you need to use the `checked` function for radios and checkboxes. For example:
+
+```
+<input class="govuk-checkboxes__input" id="waste-2" name="waste" type="checkbox" value="mines" {{ checked('waste','mines') }}>
+```
+
+### Using the data on the server
+
+You can access the data on the server in a route function
+
+For example for an input with `name="first-name"`:
+
+```
+var firstName = req.session.data['first-name']
+```
+
+### Nested values
+
+For complex data you can use nested values, for example:
+
+```
+{{ govukInput({
+    name: 'claimant[first-name]'
+}) }}
+```
+
+You can show what the user entered later on like this:
+
+```
+<p>
+    {{ data['claimant']['first-name'] }}
+</p>
+```
+
+You can set the value in an input like this:
+
+```
+{{ govukInput({
+    name: 'first-name',
+    value: data['claimant']['first-name']
+}) }}
+```
+
+You can access the data on the server in a route function:
+
+```
+var firstName = req.session.data['claimant']['first-name']
+```
+
+### Ignoring inputs
+
+To prevent an input being stored, use an underscore at the start of the name.
+
+```
+{{ govukInput({
+    name: '_secret'
+}) }}
+```
+
+To use this data you'll have to write your own route.

docs/v13/documentation_routes.js

@@ -88,6 +88,10 @@ router.get('/privacy-policy', function (req, res) {
   res.redirect('/docs/privacy-notice')
 })
 
+router.get('/examples/pass-data', function (req, res) {
+  res.redirect('/pass-data')
+})
+
 module.exports = router
 
 // Strip off markdown extensions if present and redirect