Added filters page and link from how-tos

app/views/how-tos/filters.html

@@ -0,0 +1,168 @@
+{% extends "layout.html" %}
+
+{% block pageTitle %}
+Filters - NHS prototype kit
+{% endblock %}
+
+{% block beforeContent %}
+  {% include "how-tos/includes/breadcrumb.html" %}
+{% endblock %}
+
+{% block content %}
+
+<div class="nhsuk-grid-row">
+  <div class="nhsuk-grid-column-three-quarters">
+    <h1>Filters</h1>
+    <p class="nhsuk-lede-text">
+      Change how text is displayed.
+      </p>
+
+    <p>
+      To use filters, you need to know how to
+      <a href="passing-data-page">pass data from page to page</a>.
+    </p>
+
+    <p>
+      The kit stores data from all answers that users give in a prototype, so
+      that you can use or show the answers later. To change the format of how
+      these answers appear, you can apply filters. You can:</p>
+
+    <ul class="nshuk-list nhsuk-list-bullet">
+      <li>use existing Nunjucks filters</li>
+      <li>add a filter</li>
+      <li>use filters from other projects (recommended for advanced users only)</li>
+    </ul>
+    <h2 class="nhsuk-heading-m">Use existing Nunjucks filters</h2>
+    <p>
+      You can
+      <a
+        href="https://mozilla.github.io/nunjucks/templating.html#builtin-filters"
+        >use existing Nunjucks filters</a
+      >
+      in the kit. For example, you can use the Nunjucks
+      <code>upper</code> filter to change the format of text to upper case:
+    </p>
+
+    <pre
+      class="app-pre"
+    ><code class="app-code">{{ "{{data['name'] | upper }}" | escape }}</code></pre>
+
+    <h2 class="nhsuk-heading-m">Add a filter</h2>
+    <p>
+      Add your own filters to the <code>filters.js</code> file. Filters are
+      written in JavaScript. 
+    </p>
+    <p>Creating filters may need help from a developer, but if someone else has made one you can paste them in to your filters.js file. 
+
+      </p>
+      <h3 class="nhsuk-heading-s">Use examples that are already in your filters.js file</h3>
+      <p>
+      You can see some examples in the file.</p>
+    <p>For example, find and copy this code in your file:
+    </p>
+
+    <pre
+  class="app-pre"
+>
+<code class="app-code">filters.sayHi = function(name,tone) {
+      return (tone == 'formal' ? 'Greetings' : 'Hi') + ' ' + name + '!'
+    }</code></pre>
+
+<p>Then find this line (usually line 39)
+  <pre
+  class="app-pre"
+>
+<code class="app-code">------------------------------------------------------------------ */</code></pre>
+
+</p>
+
+<p>Then paste the code you just copied and save your changes. You will be able to the filter on on a page: </p>
+
+<pre
+class="app-pre"
+><code class="app-code">{{ "{{ 'Joel' | greetings('formal') }}" | escape }} </code></pre>
+
+
+  <p>It will show as 'Greetings, Joel!'. </p>
+
+
+  <h3 class="nhsuk-heading-s">Make a filter that changes some text to sentence case</h3>
+
+    <p>This filter will let you change text to sentence case, for example from "a test" to "A test". </p>
+
+    <pre
+      class="app-pre"
+    >
+<code class="app-code">filters.sentenceCase = function (input){
+  // check the input
+  // blank: do not do anything
+  if (!input) return ''; 
+   // not text: do not do anything
+  if (typeof input !== 'string') return input;
+  // is a string/text
+  // text: change first character to uppercase and put it back in the string
+  return input.charAt(0).toUpperCase() + input.slice(1); 
+};</code></pre>
+
+
+  <p>When you have added it to your filters.js file, you can use it on a page like this:</p>
+    <pre
+      class="app-pre"
+    ><code class="app-code">{{ "{{ data['name'] | sentenceCase }}" | escape }} </code></pre>
+
+
+
+    <h3 class="nhsuk-heading-s">Make a filter that uses HTML</h3>
+    <p>If you want to use HTML in a filter, write the filter:</p>
+    <pre
+      class="app-pre"
+    ><code class="app-code">{{"filters.bold = function (content) {
+  return '<strong>' + content + '</strong>';
+  // remember to use the 'safe' filter afterwards to get the HTML formatting
+}" | escape }} </code></pre>
+    <p>Then use it on a page with the extra filter <code>safe</code>:</p>
+    <pre
+      class="app-pre"
+    ><code class="app-code">{{"{{ data['name'] | bold | safe }}" | escape }}</code></pre>
+    <p>
+      Using <code>safe</code> makes the text show with the HTML formatting and not just the code
+      <code>{{"<strong></strong>" | escape }}</code>.
+    </p>
+
+    <p>You can also use these filters together:</p>
+    <pre
+      class="app-pre"
+    ><code class="app-code">{{ "{{ data['name'] | upper | bold | safe }}" | escape }}</code></pre>
+
+    <h2 class="nhsuk-heading-m">Use filters from other projects (recommended for advanced users only)</h2>
+    <p>
+      If you are confident with Javascript, you can get filters from other places. 
+      </p>
+
+
+         <p>If your filters you are trying to use start with 'add Filter' (for example the <a href="https://mozilla.github.io/nunjucks/api.html#custom-filters">Custom Filters in the Nunjucks documentation</a>), you will need to change them to work in the NHS prototype kit.
+          </p><p>
+          For example, if you have a filter like this:</p>
+          <pre
+          class="app-pre"
+        ><code class="app-code">env.addFilter('shorten', function(str, count) {
+          return str.slice(0, count || 5);
+      }); </code></pre>
+
+      <p>change <code>env.addFilter('shorten, function',</code> to <code>filters.shorten = function</code> and remove <code>)</code> at the end.</p>
+      <p>The code will then look like this:</p>
+      <pre
+      class="app-pre"
+    ><code class="app-code">filters.shorten = function(str, count) {
+      return str.slice(0, count || 5);
+  };</code></pre>
+
+      <p>One project with a lot of tools is the XGOV-UK Prototype Filters plugin. If you want to use this plugin, you will need to change your <code>filters.js</code> file using the instructions for 'Using with earlier versions of the Prototype Kit'.
+    </p>
+    <p>
+      <a href="https://x-govuk.github.io/govuk-prototype-filters/get-started/">Go to the X-GOV.UK GOV.UK Prototype filters project</a>
+    </p>
+
+  </div>
+</div>
+{% endblock %}

app/views/how-tos/index.html

@@ -91,6 +91,8 @@ <h2 class="nhsuk-heading-s">General use</h2>
         <li><a href="/how-tos/components">Using components</a></li>
         <li><a href="/how-tos/passing-data-page">Passing data page to page</a></li>
         <li><a href="/how-tos/branching">Branching</a> – show a different page based on user input</li>
+        <li><a href="/how-tos/filters">Filters</a> - change how text is displayed</li>
+
       </ul>
 
         <h2 class="nhsuk-heading-s">Share your prototype</h2>