Add a WTForms-compatible textbox macro

This macro:
- accepts a WTForm form field as a parameter
- renders a form field which follows the GOV.UK Elements patterns, both visually
  and in markup terms

It then changes any page which uses either:
- the old, non-WTForms macro or
- the old, WTFforms `render_field` macro

…to use this new macro and removes both of the old ones.

It also adds the option to display hint text above the textbox.

app/assets/stylesheets/main.scss

@@ -22,6 +22,7 @@
 @import '../govuk_elements/public/sass/elements/forms';
 @import '../govuk_elements/public/sass/elements/forms/form-validation';
 @import '../govuk_elements/public/sass/elements/forms/form-block-labels';
+@import '../govuk_elements/public/sass/elements/forms/form-validation';
 @import '../govuk_elements/public/sass/elements/icons';
 @import '../govuk_elements/public/sass/elements/layout';
 @import '../govuk_elements/public/sass/elements/lists';

app/main/forms.py

@@ -1,5 +1,5 @@
 from flask_wtf import Form
-from wtforms import StringField, PasswordField, ValidationError
+from wtforms import StringField, PasswordField, ValidationError, TextAreaField
 from wtforms.validators import DataRequired, Email, Length, Regexp
 from app.main.validators import Blacklist, ValidateUserCodes
 
@@ -121,6 +121,19 @@ class AddServiceForm(Form):
             raise ValidationError('Service name already exists')
 
 
+class ServiceNameForm(Form):
+    service_name = StringField(u'New name')
+
+
+class ConfirmPasswordForm(Form):
+    password = PasswordField(u'Enter password')
+
+
+class TemplateForm(Form):
+    template_name = StringField(u'Template name')
+    template_body = TextAreaField(u'Message')
+
+
 class ForgotPasswordForm(Form):
     email_address = email_address()
 

app/main/views/service_settings.py

@@ -2,6 +2,7 @@ from flask import render_template, redirect, request, url_for, abort
 from flask_login import login_required
 
 from app.main import main
+from app.main.forms import ConfirmPasswordForm, ServiceNameForm
 
 service = {
     'name': 'Service name',
@@ -20,10 +21,15 @@ def service_settings():
 
 @main.route("/service-settings/name", methods=['GET', 'POST'])
 def name():
+
+    form = ServiceNameForm()
+    form.service_name.data = 'Service name'
+
     if request.method == 'GET':
         return render_template(
             'views/service-settings/name.html',
-            service=service
+            service=service,
+            form=form
         )
     elif request.method == 'POST':
         return redirect(url_for('.confirm_name_change'))
@@ -31,10 +37,14 @@ def name():
 
 @main.route("/service-settings/name/confirm", methods=['GET', 'POST'])
 def confirm_name_change():
+
+    form = ConfirmPasswordForm()
+
     if request.method == 'GET':
         return render_template(
             'views/service-settings/confirm.html',
-            heading='Change your service name'
+            heading='Change your service name',
+            form=form
         )
     elif request.method == 'POST':
         return redirect(url_for('.service_settings'))
@@ -64,11 +74,15 @@ def status():
 
 @main.route("/service-settings/status/confirm", methods=['GET', 'POST'])
 def confirm_status_change():
+
+    form = ConfirmPasswordForm()
+
     if request.method == 'GET':
         return render_template(
             'views/service-settings/confirm.html',
             heading='Turn off all outgoing notifications',
-            destructive=True
+            destructive=True,
+            form=form
         )
     elif request.method == 'POST':
         return redirect(url_for('.service_settings'))
@@ -87,11 +101,15 @@ def delete():
 
 @main.route("/service-settings/delete/confirm", methods=['GET', 'POST'])
 def confirm_delete():
+
+    form = ConfirmPasswordForm()
+
     if request.method == 'GET':
         return render_template(
             'views/service-settings/confirm.html',
             heading='Delete this service from Notify',
-            destructive=True
+            destructive=True,
+            form=form
         )
     elif request.method == 'POST':
         return redirect(url_for('.dashboard'))

app/main/views/styleguide.py

@@ -1,7 +1,24 @@
 from flask import render_template
+from flask_wtf import Form
+from wtforms import StringField, PasswordField, TextAreaField, validators
 from app.main import main
 
 
 @main.route('/_styleguide')
 def styleguide():
-    return render_template('views/styleguide.html')
+
+    class FormExamples(Form):
+        username = StringField(u'Username')
+        password = PasswordField(u'Password', [validators.required()])
+        message = TextAreaField(u'Message')
+
+    form = FormExamples()
+
+    form.message.data = "Your vehicle tax for ((registration number)) is due on ((date)). Renew online at www.gov.uk/vehicle-tax"  # noqa
+
+    form.validate()
+
+    return render_template(
+        'views/styleguide.html',
+        form=form
+    )

app/main/views/templates.py

@@ -1,6 +1,7 @@
 from flask import request, render_template, redirect, url_for
 
 from app.main import main
+from app.main.forms import TemplateForm
 
 
 @main.route("/templates")
@@ -10,12 +11,17 @@ def manage_templates():
 
 @main.route("/templates/template", methods=['GET', 'POST'])
 def add_template():
+
+    form = TemplateForm()
+
+    form.template_name.data = 'Reminder'
+    form.template_body.data = 'Vehicle tax: Your vehicle tax for ((registration number)) expires on ((date)). Tax your vehicle at www.gov.uk/vehicle-tax'  # noqa
+
     if request.method == 'GET':
         return render_template(
             'views/edit-template.html',
-            template_name='Reminder',
-            template_body='Vehicle tax: Your vehicle tax for ((registration number)) expires on ((date)). Tax your vehicle at www.gov.uk/vehicle-tax',  # noqa
-            h1='Edit template'
+            h1='Edit template',
+            form=form
         )
     elif request.method == 'POST':
         return redirect(url_for('.manage_templates'))
@@ -23,10 +29,14 @@ def add_template():
 
 @main.route("/templates/template/add", methods=['GET', 'POST'])
 def edit_template():
+
+    form = TemplateForm()
+
     if request.method == 'GET':
         return render_template(
             'views/edit-template.html',
-            h1='Add template'
+            h1='Add template',
+            form=form
         )
     elif request.method == 'POST':
         return redirect(url_for('.manage_templates'))

app/templates/admin_template.html

@@ -1,4 +1,3 @@
-{%- from "components/form-field.html" import render_field %}
 {% extends "govuk_template.html" %}
 
 {% block head %}

app/templates/components/form-field.html

@@ -1,12 +0,0 @@
-{% macro render_field(field) %}
-  <dt>{{ field.label }}
-  <dd>{{ field(**kwargs)|safe }}
-  {% if field.errors %}
-    <ul class=error>
-    {% for error in field.errors %}
-      <li>{{ error }}</li>
-    {% endfor %}
-    </ul>
-  {% endif %}
-  </dd>
-{% endmacro %}

app/templates/components/textbox.html

@@ -1,15 +1,21 @@
-{% macro textbox(name, label, value='', small=True, highlight_tags=False, password=False) %}
-  <div class="form-group">
-    <label class="form-label" for="{{ name }}">{{ label }}</label>
-    {% if small %}
-      <input class="form-control" id="{{ name }}" name="{{ name }}" type="{{ 'password' if password else 'text' }}" value="{{ value }}">
-    {% else %}
-      <textarea
-        class="form-control {% if highlight_tags %}textbox-highlight-textbox{% endif %}"
-        id="{{ name }}" name="{{ name }}"
-        cols="30" rows="10"
-        {% if highlight_tags %}data-module='highlight-tags'{% endif %}
-      >{{ value }}</textarea>
-    {% endif %}
+{% macro textbox(field, hint=False, highlight_tags=False) %}
+  <div class="form-group{% if field.errors %} error{% endif %}">
+    <label class="form-label" for="{{ field.name }}">
+      {{ field.label }}
+      {% if hint %}
+        <span class="form-hint">
+          {{ hint }}
+        </span>
+      {% endif %}
+      {% if field.errors %}
+        <span class="error-message">
+          {{ field.errors[0] }}
+        </span>
+      {% endif %}
+    </label>
+    {{ field(**{
+      'class': 'form-control textbox-highlight-textbox' if highlight_tags else 'form-control',
+      'data-module': 'highlight-tags' if highlight_tags else ''
+    }) }}
   </div>
 {% endmacro %}

app/templates/views/add-service.html

@@ -1,5 +1,5 @@
 {% extends "admin_template.html" %}
-{% from "components/form-field.html" import render_field %}
+{% from "components/textbox.html" import textbox %}
 
 {% block page_title %}
 GOV.UK Notify | Set up service
@@ -17,9 +17,8 @@ GOV.UK Notify | Set up service
 				<li>as your email sender name</li>
 			</ul>
 
-		<form autocomplete="off" action="" method="post">
-			{{ form.hidden_tag() }}
-			{{ render_field(form.service_name, class='form-control-2-3') }}
+		<form autocomplete="off" method="post">
+			{{ textbox(form.service_name) }}
 
 			<p>
 			<button class="button" href="dashboard" role="button">Continue</button>

app/templates/views/edit-template.html

@@ -11,8 +11,8 @@ GOV.UK Notify | Edit template
 		<h1 class="heading-xlarge">{{ h1 }}</h1>
 
 		<form method="post">
-			{{ textbox(name='template_name', label='Template name', value=template_name) }}
-			{{ textbox(name='template_body', label='Message', small=False, value=template_body, highlight_tags=True) }}
+			{{ textbox(form.template_name) }}
+			{{ textbox(form.template_body, highlight_tags=True) }}
 			{{ page_footer(
 				'Save and continue',
 				back_link=url_for('.dashboard'),

app/templates/views/email-not-received.html

@@ -1,4 +1,5 @@
 {% extends "admin_template.html" %}
+{% from "components/textbox.html" import textbox %}
 {% from "components/page-footer.html" import page_footer %}
 
 {% block page_title %}
@@ -14,13 +15,10 @@ GOV.UK Notify
     <p>Check your email address is correct and then resend the confirmation code.</p>
       <p>
       </p>
-      <form autocomplete="off" action="" method="post">
-          {{ form.hidden_tag() }}
-          {{ render_field(form.email_address, class='form-control-2-3') }}
-          <span class="font-xsmall">Your email address must end in .gov.uk</span>
-          <p>
-          </p>
-          {{ page_footer('Resend confirmation code') }}
+      <form autocomplete="off" method="post">
+        {{ textbox(form.email_address) }}
+        <span class="font-xsmall">Your email address must end in .gov.uk</span>
+        {{ page_footer('Resend confirmation code') }}
       </form>
   </div>
 </div>

app/templates/views/forgot-password.html

@@ -1,4 +1,6 @@
 {% extends "admin_template.html" %}
+{% from "components/textbox.html" import textbox %}
+{% from "components/page-footer.html" import page_footer %}
 
 {% block page_title %}
 GOV.UK Notify
@@ -12,13 +14,11 @@ GOV.UK Notify
 
     <p>If you have forgotten your password, we can send you an email to create a new password.</p>
 
-    <form autocomplete="off" action="" method="post">
-	  {{ form.hidden_tag() }}
-	  {{ render_field(form.email_address, class='form-control-2-3') }}
-      <p>
-      <button class="button" role="button">Send email</button>
-      </p>
+    <form autocomplete="off" method="post">
+  	  {{ textbox(form.email_address) }}
+      {{ page_footer("Send email") }}
     </form>
+
   </div>
 </div>
 

app/templates/views/new-password.html

@@ -1,4 +1,6 @@
 {% extends "admin_template.html" %}
+{% from "components/textbox.html" import textbox %}
+{% from "components/page-footer.html" import page_footer %}
 
 {% block page_title %}
 GOV.UK Notify
@@ -13,17 +15,9 @@ GOV.UK Notify
 
 		<p> You can now create a new password for your account.</p>
 
-		<form action="" autocomplete="off" method="post">
-			{{ form.hidden_tag() }}
-		<p>
-  		  {{ render_field(form.new_password, class="form-control-1-4", type="password") }}
-  		<span class="font-xsmall">Your password must have at least 10 characters</span>
-  		</p>
-
-  		<p>
-  		<button class="button" role="button">Continue</button>
-  		</p>
-
+		<form method="post" autocomplete="off">
+		  {{ textbox(form.new_password, hint="Your password must have at least 10 characters") }}
+  		{{ page_footer("Continue") }}
 		</form>
 		{% else %}
 			Message about email address does not exist. Some one needs to figure out the words here.

app/templates/views/register.html

@@ -1,4 +1,5 @@
 {% extends "admin_template.html" %}
+{% from "components/textbox.html" import textbox %}
 {% from "components/page-footer.html" import page_footer %}
 
 {% block page_title %}
@@ -16,12 +17,10 @@ GOV.UK Notify | Create an account
    		<form autocomplete="off" action="" method="post">
 			{{ form.hidden_tag() }}
 
-			{{ render_field(form.name, class='form-control-2-3') }}
-			{{ render_field(form.email_address, class='form-control-2-3') }}
-			<span class="font-xsmall">Your email address must end in .gov.uk</span>
-			{{ render_field(form.mobile_number, class='form-control-2-3') }}
-			{{ render_field(form.password, class='form-control-2-3') }}
-			<span class="font-xsmall">Your password must have at least 10 characters</span></label>
+			{{ textbox(form.name) }}
+			{{ textbox(form.email_address, hint="Your email address must end in .gov.uk") }}
+			{{ textbox(form.mobile_number) }}
+			{{ textbox(form.password, hint="Your password must have at least 10 characters") }}
 			{{ page_footer("Continue") }}
 		</form>
 	</div>

app/templates/views/service-settings/confirm.html

@@ -14,7 +14,7 @@ GOV.UK Notify | Service settings
     <div class="column-three-quarters">
 
     <form method="post">
-      {{ textbox('new_name', 'Enter your password', password=True) }}
+      {{ textbox(form.password) }}
       {{ page_footer(
         'Confirm',
         destructive=destructive,

app/templates/views/service-settings/name.html

@@ -13,12 +13,15 @@ GOV.UK Notify | Service settings
   <div class="grid-row">
     <div class="column-three-quarters">
 
-      <p>
-        Your service name ({{ service.name }}) is included in every sent notification
-      </p>
+      <p>Users will see your service name:</p>
+
+      <ul class="list-bullet">
+        <li>at the start of every text message, eg ‘Vehicle tax: we received your payment, thank you’</li>
+        <li>as your email sender name</li>
+      </ul>
 
       <form method="post">
-        {{ textbox('new_name', 'New name', value=service.name) }}
+        {{ textbox(form.service_name) }}
         {{ page_footer(
           'Save',
           back_link=url_for('.service_settings')

app/templates/views/signin.html

@@ -1,4 +1,5 @@
 {% extends "admin_template.html" %}
+{% from "components/textbox.html" import textbox %}
 {% from "components/page-footer.html" import page_footer %}
 
 {% block page_title %}
@@ -13,14 +14,10 @@ Sign in
 
 		<p>If you do not have an account, you can <a href="register">register for one now</a>.</p>
 
-		<form autocomplete="off" action="" method="post">
-			{{ form.hidden_tag() }}
-			{{ render_field(form.email_address, class='form-control-2-3') }}
-			{{ render_field(form.password, class='form-control-2-3') }}
-			<p>
-			<span class="font-xsmall"><a href="{{url_for('main.forgot_password')}}">Forgotten password?</a></span>
-			</p>
-			{{ page_footer("Continue") }}
+		<form autocomplete="off" method="post">
+			{{ textbox(form.email_address) }}
+			{{ textbox(form.password) }}
+			{{ page_footer("Continue", back_link="#", back_link_text="Forgotten password?") }}
 		</form>
 	</div>
 </div>

app/templates/views/styleguide.html

@@ -148,15 +148,8 @@
   {% endcall %}
 
   <h2 class="heading-large">Textbox</h2>
-
-  {{ textbox('name', 'Username') }}
-  {{ textbox('password', 'Password', password=True) }}
-  {{ textbox(
-    'message',
-    "Message",
-    value="Your vehicle tax for ((registration number)) is due on ((date)). Renew online at www.gov.uk/vehicle-tax",
-    small=False,
-    highlight_tags=True
-  ) }}
+  {{ textbox(form.username) }}
+  {{ textbox(form.password) }}
+  {{ textbox(form.message, highlight_tags=True) }}
 
 {% endblock %}

app/templates/views/text-not-received.html

@@ -1,4 +1,5 @@
 {% extends "admin_template.html" %}
+{% from "components/textbox.html" import textbox %}
 {% from "components/page-footer.html" import page_footer %}
 
 {% block page_title %}
@@ -13,9 +14,8 @@ GOV.UK Notify
 
     <p>Check your mobile phone number is correct and then resend the confirmation code.</p>
 
-      <form autocomplete="off" action="" method="post">
-        {{ form.hidden_tag() }}
-        {{ render_field(form.mobile_number, class='form-control-2-3') }}
+      <form autocomplete="off" method="post">
+        {{ textbox(form.mobile_number) }}
         {{ page_footer("Resend confirmation code") }}
       </form>
   </div>

app/templates/views/two-factor.html

@@ -1,4 +1,5 @@
 {% extends "admin_template.html" %}
+{% from "components/textbox.html" import textbox %}
 {% from "components/page-footer.html" import page_footer %}
 
 {% block page_title %}
@@ -14,9 +15,8 @@ GOV.UK Notify | Text verification
 		<p>We've sent you a text message with a verification code.</p>
 
 
-		<form autocomplete="off" action="" method="post">
-			{{ form.hidden_tag() }}
-			{{ render_field(form.sms_code, class='form-control-1-4') }}
+		<form autocomplete="off" method="post">
+			{{ textbox(form.sms_code) }}
 			<span class="font-xsmall"><a href="{{ url_for('.verification_code_not_received') }}">I haven't received a text</a></span>
 			{{ page_footer("Continue") }}
 		</form>

app/templates/views/verify.html

@@ -1,4 +1,5 @@
 {% extends "admin_template.html" %}
+{% from "components/textbox.html" import textbox %}
 {% from "components/page-footer.html" import page_footer %}
 
 {% block page_title %}
@@ -13,11 +14,10 @@ GOV.UK Notify | Confirm email address and mobile number
 
 		<p>We've sent you confirmation codes by email and text message. You need to enter both codes here.</p>
 
-		<form  autocomplete="off" action="" method="post">
-			{{ form.hidden_tag() }}
-			{{ render_field(form.email_code, class='form-control-1-4') }}
+		<form autocomplete="off" method="post">
+			{{ textbox(form.email_code) }}
 			<span class="font-xsmall"><a href="{{ url_for('.check_and_resend_email_code')}}">I haven't received an email</a></span>
-			{{ render_field(form.sms_code, class='form-control-1-4') }}
+			{{ textbox(form.sms_code) }}
 			<span class="font-xsmall"><a href="{{ url_for('.check_and_resend_text_code') }}">I haven't received a text</a></span>
 			{{ page_footer("Continue") }}
 		</form>