Update documentation for the different helper methods

kevindew · kevindew · commit a87ef944c8de · 2020-06-04T10:49:07.000+01:00
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.
diff --git a/doc/smart-answer-flow-development/creating-a-new-smart-answer.md b/doc/smart-answer-flow-development/creating-a-new-smart-answer.md
@@ -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!
@@ -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 %>
 ```
@@ -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!
@@ -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 %>
 ```
@@ -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!
@@ -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 %>
 ```
diff --git a/doc/smart-answers/erb-templates.md b/doc/smart-answers/erb-templates.md
@@ -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 with an argument to indicate the intent:
 
 ```erb
-<% render_content_for :title do %>
-  Some amazing title
+<% text_for :title do %>
+  This is plain text, any HTML characters used will be espaced. Any indentation is automatically removed.
 <% 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](https://github.com/alphagov/govspeak),
+  and will be converted to HTML. Any indentation is automatically removed.
+<% 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.
+See the template page documentation for the available contexts and their allowed formats:
 
 * [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.
diff --git a/doc/smart-answers/erb-templates/landing-page-template.md b/doc/smart-answers/erb-templates/landing-page-template.md
@@ -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 and 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 %>
 ```
 
diff --git a/doc/smart-answers/erb-templates/outcome-templates.md b/doc/smart-answers/erb-templates/outcome-templates.md
@@ -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 and 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 %>
+```
diff --git a/doc/smart-answers/erb-templates/question-templates.md b/doc/smart-answers/erb-templates/question-templates.md
diff --git a/doc/smart-answers/file-structure.md b/doc/smart-answers/file-structure.md
