For some reason we were rebuilding `new_template` as a dictionary,
without the `placeholders` attribute. This meant that we were never
actually counting the placeholders, just counting the length of `None`
and adding 1 to it.
So this commit fixes that, beefs up the tests, and makes sure that
everything is pluralised properly.
Right now we have separate pages for email and text message templates.
In the future we will also have a separate page for letter templates.
This commit changes Notify to only have one page for all templates.
What is the problem?
---
The left-hand navigation is getting quite crowded, at 8 items for a
service that can send letters. Research suggests that the number of
objects an average human can hold in working memory is 7 ± 2 [1]. So
we’re at the limit of how many items the navigation should have.
In the future we will need to search/sort/filter templates by attributes
other than type, for example:
- show me the ‘confirmation’ templates
- show me the most recently used templates
- show me all templates containing the placeholder `((ref_no))`
These are hypothetical for now, but these needs (or others) may become
real in the future. At this point pre-filtering the list of templates
by type would restrict what searches a user could do. So by making this
change now we’re in a better position to iterate the design in the
future.
What’s the change?
---
This commit replaces the ‘Email templates’, ‘Text message templates’ and
‘Letter templates’ pages with one page called ‘Templates’.
This new templates page shows all the templates for the service, sorted
by most recently created first (as before).
To add a new template there is a new page with a form asking you what
kind of template you want to create. This is necessary because in the
past we knew what kind of template you wanted to create based on the
kind you were looking at.
What’s the impact of this change on new users?
---
This change alters the onboarding process slightly. We still want to
take people through the empty templates page from the call-to-action on
the dashboard because it helps them understand that to send a message
using Notify you need a template. But because we don’t have separate
pages for emails/text messages we will have to send users through the
extra step of choosing what kind of template to create. This is a bit
clunkier on first use but:
- it still gets the point across
- it takes them through the actual flow they will be using to create new
templates in the future (ie they’re learning how to use Notify, not
just being taken through a special onboarding route)
I’m not too worried about this change in terms of the experience for new
users. Furthermore, by making it now we get to validate whether it’s
causing any problems in the lab research booked for next week.
What’s the impact of this change on current services?
---
Looking at the top 15 services by number of templates[2], most are using
either text messages or emails. So this change would not have a
significant impact on these services because the page will not get any
longer. In other words we wouldn’t be making it worse for them.
Those services who do use both are not using as many templates. The
worst-case scenario is SSCS, who have 16 templates, evenly split between
email and text messages. So they would go from having 8 templates per
page to 16, which is still less than half the number that HMPO or
Digital Marketplace are managing.
References
---
1. https://en.wikipedia.org/wiki/The_Magical_Number_Seven,_Plus_or_Minus_Two
2. Template usage by service
Service name | Template count | Template types
---------------------------------------|----------------|---------------
Her Majesty's Passport Office | 40 | sms
Digital Marketplace | 40 | email
GovWifi-Staging | 19 | sms
GovWifi | 18 | sms
Digital Apprenticeship Service | 16 | email
SSCS | 16 | both
Crown Commercial Service MI Collection | 15 | email
Help with Prison Visits | 12 | both
Digital Future | 12 | email
Export Licensing Service | 11 | email
Civil Money Claims | 9 | both
DVLA Drivers Medical Service | 9 | sms
GOV.UK Notify | 8 | both
Manage your benefit overpayments | 8 | both
Tax Renewals | 8 | both
The url was not being properly formed, missing the tempalte_id, meaning the back button on the page did not work.
This fixes that, includes a check of the url for the back button.
There is a check that the template can not be created as priority if the user is not a platform admin.
There is a check that the template can not change the `priority` unless they are a platform admin.
Right now we can show what a letter template looks like as a PDF or PNG.
This commit completes the work so this is also possible when:
- showing a template with the placeholders replaced
- showing any version of a template
Also removes dependency on `Exception().message`, which was deprecated
in Python 2.6. See
97f82d565f
for full details.
The breaking change page was taking the rendered template and saving
that if the user confirmed the change. This meant that templates could
be saved with `<span class="placeholder">…</span>` in their subject line
for example.
This commit fixes it so that it uses whatever data the user submitted,
not the rendered version of this.
The PDF preview is all good, but it’s hard, finickeity and feels dirty
to embed a PDF in a web page. It’s a more natural thing to embed an
image in a web page.
So this commit adds another endpoint to return an image of a letter
template. It generates this image from the PDF preview, so the stack
looks like:
1. `template.png` (generated in admin)
2. `template.pdf` (generated in admin)
3. HTML preview (generated by a `Renderer` in utils)
4. `Template` instance
5. serialised template from API
6. Template stored in database
The library used to convert the PDF to an image is Wand[1], which binds
to ImageMagick underneath. So in order to get this working locally on a
Mac you will probably need to do:
`brew install imagemagick ghostscript cairo pango`.
To get it working on Ubuntu/EC2 is an exercise left to the reader…
1. http://docs.wand-py.org/en/0.4.4/
Previewing a letter is different to previewing an email or text message
because:
- a letter has a layout
- the layout is fixed, ie it doesn’t depend on the user’s device
- the ‘send yourself a test’ feature won’t be as useful because it has
a lead time, so the feedback loop will be much longer
For these reasons a HTML-only preview of the letter won’t be enough (we
don’t think). A PDF is more appropriate because:
- it can replicate the layout of the letter exactly
- it is a print format, so the user could even print themselves a copy
locally to get a feel for how it will look
This commit makes use of Flask WeasyPrint [1] to take a HTML
representation of the letter, convert it to a PDF and serve it back to
the user.
The actual work to generate the HTML and specify the layout is done in
utils, same as we do for rendering other messages.
1. https://pythonhosted.org/Flask-WeasyPrint/
Implements https://github.com/alphagov/notifications-utils/pull/81
Handles addresses as multiple columns:
- in ‘Send yourself a test’
- in example CSV files
- in validating that a CSV file has recipients (eg at least an ‘address
line 1’ and ‘postcode’ column)
- when showing the contents of a CSV file
As few UI changes as possible, once we have the thing working end-to-end
we can think about how the UI might need to work differently.
Let users create/edit/delete letter templates.
Let them upload a CSV file or send a test against a letter template.
Big assumption at the moment is that addresses only have one line, and
therefore one column in the CSV file.
When you edit a template, you’re probably going to do something with
it straight afterwards, eg send yourself a test.
We could make it easy to find the template you’ve just saved by putting
it at the top of the pile. This gets confusing for other reasons (order
of templates will constantly shift about).
So this commit changes the flow to take you to the single page for the
template you’ve just edited.
Now that the example on the breaking changes page looks more like a spreadsheet,
we should do the same thing for the downloadable example on the send page.
When a user adds or removes placeholders in their template we should consider
this a ‘breaking change’ and warn them accordingly.
Implementing this mostly relies on using
https://github.com/alphagov/notifications-utils/pull/37
Temporarily storing the new template until the user confirms that they want to
make the changes in done using hidden fields. This is a bit hacky, but the
complexity of making sessions interact with WTForms was just too much to handle.
This commit also changes the example spreadsheet that we show on this page to
look more like a spreadsheet.
> At the moment, we have an all email templates page, and an edit an
> individual page.
>
> This gets messy when we refer to templates like the dashboard and the
> activity views. We solve this currently by using anchor links to the
> list page, but this is clunky.
>
> So lets add it, then update the links on the dash and activity to the
> new view page.
>
> Should be a link from the view a single template page, to the template
> hub page.
https://www.pivotaltracker.com/story/show/117349227
Each service on the list is linked to the dashboard page of the service.
The platform admin user can see/edit templates, see/invite users, see/edit service settings.
The platform admin user can not send messages, see/edit api keys and developer docs.
The same `.html` file is shared between adding a template and editing a
template.
The page heading needs to be contextual to the URL, either ‘add’ or ‘edit’.
Somewhere along the way this got lost; this commit reinstates it.
The email pattern looked a bit shonky when displayed in a narrower column. This
commit fixes it by making the email’s metadata (eg subject, from) into a table,
which it sort of is. This means that it is more flexible about the size of
container in which it sits.
This commit parameterises all methods in the send view so that they can send
either emails or SMS messages.
It works out what kind of message it is sending from the `template_type`
property of the template object.
This means that the `Template` util class needs to know about these properties,
which means that this commit depends on:
https://github.com/alphagov/notifications-utils/pull/2
This commit does _not_ add tests for sending emails. The existing tests for
sending SMS still pass, but actually sending emails is outside the scope of
this story.
Templates now have:
- a type (email or sms)
- a subject (if they are email templates)
We don’t want two completely separate view files for email and SMS, because they
would have an enormous amount of repetition.
So this commit adds
- different templates for SMS and email templates
- different form objects for SMS and email templates
…and wires them up.
The ‘manage templates’ page was almost identical to the ‘send text messages’
page.
This commit consolidates them into one and makes them all hang together.
Part of this means tweaks to the javascript so that files upload as soon as
you’ve chosen them.
Since placeholders (almost) work now, it’s worth telling people what the syntax
is.
This commit also removes the ‘template type’ picker, since you can only create
SMS templates at the moment. This will be revisited when we start looking at how
you add an email template.
