Skip to content

Commit

Permalink
Update documentation for the different helper methods
Browse files Browse the repository at this point in the history
This updates the documentation to remove references to .govspeak.erb
files and to make suggestions of which helper method (text_for,
govspeak_for, html_for) in each scenario.

Along the way I noticed that the label field may not be working (issue
prior to these changes) so I left a note about that so the next person
who wants it can investigate.

I removed the information on error_* as I believe that is mostly set on
a custom basis so doesn't need to be included in the general
documentation.
  • Loading branch information
kevindew committed May 20, 2020
1 parent dab6a71 commit 46e215c
Show file tree
Hide file tree
Showing 6 changed files with 145 additions and 116 deletions.
18 changes: 9 additions & 9 deletions doc/smart-answer-flow-development/creating-a-new-smart-answer.md
Original file line number Diff line number Diff line change
Expand Up @@ -43,7 +43,7 @@ Create a new file for our landing page template.

```
$ mkdir lib/smart_answer_flows/example-smart-answer
$ touch lib/smart_answer_flows/example-smart-answer/example_smart_answer.govspeak.erb
$ touch lib/smart_answer_flows/example-smart-answer/example_smart_answer.erb
```

Although the landing page template needs to exist, it doesn't actually need to contain anything!
Expand All @@ -53,11 +53,11 @@ Assuming you're still running `rails server`, visit [http://localhost:3000/examp
Open the new landing page template your editor and copy/paste the following content:

```erb
<% render_content_for :title do %>
<% text_for :title do %>
Smart Answer title
<% end %>
<% render_content_for :body do %>
<% govspeak_for :body do %>
Landing page body.
<% end %>
```
Expand All @@ -74,7 +74,7 @@ Create a new file for our question page template.

```
$ mkdir lib/smart_answer_flows/example-smart-answer/questions
$ touch lib/smart_answer_flows/example-smart-answer/questions/question_1.govspeak.erb
$ touch lib/smart_answer_flows/example-smart-answer/questions/question_1.erb
```

Although the question page template needs to exist, it doesn't actually need to contain anything!
Expand All @@ -84,11 +84,11 @@ Assuming you're still running `rails server`, visit [http://localhost:3000/examp
Open the new question page template in your editor and copy/paste the following content:

```erb
<% render_content_for :title do %>
<% text_for :title do %>
Question page title
<% end %>
<% render_content_for :body do %>
<% govspeak_for :body do %>
Question page body.
<% end %>
```
Expand All @@ -105,7 +105,7 @@ Create a new file for our outcome page template.

```
$ mkdir lib/smart_answer_flows/example-smart-answer/outcomes
$ touch lib/smart_answer_flows/example-smart-answer/outcomes/outcome_1.govspeak.erb
$ touch lib/smart_answer_flows/example-smart-answer/outcomes/outcome_1.erb
```

Although the question page template needs to exist, it doesn't actually need to contain anything!
Expand All @@ -115,11 +115,11 @@ Assuming you're still running `rails server`, visit [http://localhost:3000/examp
Open the new outcome page template in your editor and copy/paste the following content:

```erb
<% render_content_for :title do %>
<% text_for :title do %>
Outcome page title
<% end %>
<% render_content_for :body do %>
<% govspeak_for :body do %>
Outcome page body.
<% end %>
```
Expand Down
21 changes: 12 additions & 9 deletions doc/smart-answers/erb-templates.md
Original file line number Diff line number Diff line change
@@ -1,27 +1,30 @@
# ERB templates

Content is defined in `render_content_for` blocks and with the name of the intent of the content:
Content is defined using one of three helpers to indicate the format:

```erb
<% render_content_for :title do %>
Some amazing title
<% text_for :title do %>
This is plain text, any HTML characters used will be espaced
<% end %>
```

The type of content can be explicitly set with the `format:` option:
```erb
<% govspeak_for :body do %>
This uses the GOV.UK markdown dialect, govspeak, and will be converted to
HTML.
<% end %>
```

```erb
<% render_content_for :title, format: :html do %>
<h1>Some amazing title</h1>
<% html_for :body do %>
<p>This is HTML, used when we need fine grained control over content</p>
<% end %>
```

We support Govspeak (`:govspeak`), plain text (`:text`) and HTML (`:html`). See docs for template pages for the default formats of different content blocks.
For examples of which of these to use in which contexts see relevant documentation for different contexts:

* [Landing page templates](erb-templates/landing-page-template.md)
* [Question templates](erb-templates/question-templates.md)
* [Outcome templates](erb-templates/outcome-templates.md)

We remove all leading spaces from the content in the `render_content_for` blocks for Govspeak and Text formats. This allows us to indent the content in the `render_content_for` blocks without having to worry about it affecting the generated HTML when it's processed using Govspeak.

Any state variable defined in the flow is available to be used in the ERB template. See [storing data](storing-data.md) for the various ways that you can set state variables.
49 changes: 29 additions & 20 deletions doc/smart-answers/erb-templates/landing-page-template.md
Original file line number Diff line number Diff line change
@@ -1,44 +1,53 @@
# Landing page template

Landing page templates live in `lib/smart_answer_flows/<flow-name>/<flow-name-with-underscores>.govspeak.erb`.
Landing page templates live in `lib/smart_answer_flows/<flow-name>/<flow-name-with-underscores>.erb`.

## Content types

The templates can contain content for any of the following keys:

### `:title`

* Default format is `:text`
* Used as the heading (currently "h1")
Used as the h1 heading, can only be text. Example:

### `:meta_description`

* Default format is `:text`
* Used as the content for the [meta description tag][meta-description]
```erb
<% text_for :title do %>
Look up Meursing code
<% end %>
```

### `:body`
### `:meta_description`

* Default format is `:govspeak`
* Used to generate the main content (appearing above the start button)
Used as the content for the [meta description tag][meta-description]. Can only be text. Example:

### `:post_body`
```erb
<% text_for :meta_description do %>
Look up the additional code (Meursing code) required for import or export of goods containing certain types of milk and sugars
<% end %>
```

* Default format is `:govspeak`
* Used to generate supplementary content (appearing below the start button)
### `:body`

## Example
Used to generate the main content (appearing above the start button). Expected to be govspeak or HTML. Example:

```erb
<% render_content_for :title do %>
Look up Meursing code
<% govspeak_for :body do %>
Use this tool to look up the additional code (Meursing code) for import or export of goods containing certain types of milk and sugars covered Regulation (EC) No. 1216/09.
<% end %>
```

<% render_content_for :meta_description do %>
Look up the additional code (Meursing code) required for import or export of goods containing certain types of milk and sugars
```erb
<% html_for :body do %>
<p>Use this tool to look up the additional code (Meursing code) for import or export of goods containing certain types of milk and sugars covered Regulation (EC) No. 1216/09.</p>
<% end %>
```
### `:post_body`

<% render_content_for :body do %>
Use this tool to look up the additional code (Meursing code) for import or export of goods containing certain types of milk and sugars covered Regulation (EC) No. 1216/09.
Used to generate supplementary content (appearing below the start button). Expected to be govspeak or HTML. Example:

```erb
<% govspeak_for :post_body do %>
Code of measuring practice became globally effective in May 2015.
<% end %>
```

Expand Down
37 changes: 20 additions & 17 deletions doc/smart-answers/erb-templates/outcome-templates.md
Original file line number Diff line number Diff line change
@@ -1,40 +1,43 @@
# Outcome templates

Outcome templates live in `lib/smart_answer_flows/<flow-name>/outcomes/<outcome-name>.govspeak.erb`.
Outcome templates live in `lib/smart_answer_flows/<flow-name>/outcomes/<outcome-name>.erb`.

## Content types

The templates can contain content for any of the following keys:

### `:title`

* Default format is `:text`
* Used as the heading (currently "h1")

### `:body`

* Default format is `:govspeak`
* Used as the main text

### `next_steps(govspeak)`

* Default format is `:govspeak`
* Used to generate "next steps" content (at top of a right-hand sidebar)

## Example
Used as the h1 heading, can only be text. Example:

```erb
<% render_content_for :title do %>
<% text_for :title do %>
<% unless calculator.has_commodity_code? %>
The product composition you indicated is not possible.
<% else %>
The Meursing code for a product with this composition is 7<%= calculator.commodity_code %>.
<% end %>
<% end %>
```

### `:body`

<% render_content_for :body do %>
Used to generate the main content. Expected to be govspeak or HTML. Example:

```erb
<% govspeak_for :body do %>
<% if calculator.has_commodity_code? %>
Use these four digits together with the ten-digit commodity code from Trade Tariff.
<% end %>
<% end %>
```

### `next_steps`

Used to generate the "next steps" content (at the top of the right-hand sidebar). Expected to be govspeak or HTML. Example:

```erb
<% govspeak_for :next_steps do %>
Find out what happens to [ownerless property](/unclaimed-estates-bona-vacantia "Ownerless property (bona vacantia)")
<% end %>
```
Loading

0 comments on commit 46e215c

Please sign in to comment.