There are a bunch of services that just have one text message template
and one email template.
In this case the template navigation is essentially the same as the
list of templates – a user can just differentiate by looking at the two
templates. Adding the nav would just be noise in this case.
There are lots of services that only send emails, or only send text
messages. For these services, being able to filter the list of templates
but type is pointless – it won’t cut the list down at all.
This commit adds some logic to only show the navigation if the service
has some variety of template types.
When users are trying to find a template there’s a fair chance that they
know whether or not it’s an email/text message/(letter) that they’re
looking for.
Making them scroll past a whole bunch of templates of a different type
means it will take them longer to find the template they are looking
for.
We already have search on the templates page, but this is only good for
where they can remember the name of the template. This will be
sometimes but not always.
This commit adds some navigation to filter down the list of templates to
only show one type at a time. By default it will show all templates. It
adapts the pattern we use for filtering notifications by
sending/failed/delivered, but without the counts of how many things are
in each bucket (I don’t think there’s any value in knowing you have X
text message templates; on this page you only really care
about the one template you’re looking for).
_Note: required re-arranging the functions in `templates.py`. The route
for `/template/:uuid` needs to come before the route for
`template/:string` otherwise Flask tries to interpret a template’s ID
as its type.
The CSV upload route has always quietly ignored excess personalisation.
We changed the API to do the same here:
https://github.com/alphagov/notifications-api/pull/853
This means that removing a placeholder from a template is never a
breaking change, because the data that you were providing to populate it
is now just ignored.
So we don’t need to show the interstitial page in this case.
Right now showing all the pages in full is the only way we have of
showing a letter that makes sense to our users. Maybe in the future we
show some kind of truncated version, but the end of the first page is
not a good place to truncate the letter.
This commit just extracts the code for showing multiple pages from the
template view, refactors it for reuse, and includes it in the send
views.
This is a term that one of our research participants used to describe
the big bold text that starts each letter. I think it’s quite a nice
plain english term for it.
Also changes the formatting guidance to use the word heading instead of
title, for consistency.
In research we’ve seen two problems with the click-to-see-PDF thing:
- it’s not very intuitive that the letter is clickable, or what you
can expect when clicking the letter
- people get lost of stuck in the PDF view because it opens in the same
tab, or they open it in a new tab and then get find their way back, or
…
So this commit changes the show template page to show the entire
contents of the letter, same as we do for emails and text messages.
Right now it only does it on the view template page. I think we’ll have
to work out a way of showing some kind of truncated version on the _Send
yourself a test_ and _Preview_ pages. But that’s for later.
This is a hangover from when we had separate email/SMS template pages.
If the view doesn’t use a parameter Flask adds it to the querystring. So
we were getting URLs that ended in `?template_type=sms`, to no effect.
Users were having trouble finding the delete template link. It sort of
made sense having it on the edit page before we had the view template
page. But it doesn’t make sense now – having to choose to ‘edit’ the
template before you can delete is counterintuitive.
The single template page is where you go to choose an action to perform
on your template. Deleting is a good example of an action you can
perform on a template.
So this commit moves the delete link from the edit template page to the
view template page.
It also puts the confirm banner on same page as the delete link
The idea being that, in order to make a decision about whether to delete
the template, it’s useful to be able to see the template you’re
deleting. There’s no user need to edit the template before you delete
it.
This is another problem with sanitising HTML, this with with it getting
encoded where it shouldn’t be. The result was, when editing a template,
the API getting sent an encoded rather than raw version of the subject
(for letters and emails).
The reason this happened is because BeautifulSoup behaves in an
unexpected way.
When accessing the `value` attribute of an `input` BeautifulSoup returns
an unencoded version of the contents. In other words it returns what the
user would see in the page, not what is in the raw HTML of the page.
This meant that we were trying too hard to see an `&` instead of a
`&` in our tests[1]. So things were actually working fine before adding
the call to `escape_html`[2], but from the output of the tests it didn’t
look like HTML was getting escaped.
So this commit fixes the bug by removing the call to `escape_html` and
adding a test that looks at the raw HTML, to complement the existing
test which looks at just the `value` attribute.
1. Relevant test added here: https://github.com/alphagov/notifications-admin/pull/1178/files#diff-f2eb304b93cc383727c0ab7fc8fbd464R289
2. Call added here: https://github.com/alphagov/notifications-admin/pull/1178/files#diff-f0af582449ebf426f27f37e38f310057R252
while PDFs work on paas, they only do that because it turns out the
python buildpack happens to have imagemagick preinstalled - if that
ever changes then it'd break. so move those to the template preview
service. This also means we can get rid of weazyprint and wand
dependencies
The breaking change page wasn’t properly accounting for the fact that
letter recipients span multiple columns – it was assuming they’d only
take up one column like they do for email and SMS.
This commit fixes:
- the number of column headers (A, B, C, …) to be correct
- the count of columns (you will need X columns in your file) to be
correct
It then parameterises the test to look at a case where a recipient is
in one column (email) and multiple columns (letter).
pass in the base URL - if not set in the environment this is set to
localhost, but on paas we can pull this out of vcap_services so that
letters render properly on paas
When adding a letter it’s hard to know how the stuff you’re typing is
going to look. So rather than go straight to the edit form let’s show
users a blank letter. They can then choose which part of it they want
to edit first. And will have a better idea of how their changes are
going to show up.
In research we also saw nervousness around saving a template and wanting
to ‘preview’ it first. Hopefully this flow will make people feel less
precious about saving a template because they’ve already done it once
just by creating the template.
When you add a new template the next thing you want to do is probably:
- send a test
- edit it after seeing what it looks like
So let’s redirect you straight to the page where you can do these
things.
This is especially important for letters where we want to tighten the
edit/feedback loop.
Because we have space there’s no need to hide this now. Makes it less
confusing to have parts of the email appear/disappear as you’re clicking
through the flow.
Not everyone knows how to use `ctrl` + `f`, and it’s not scoped to
just the list of templates.
The template you want to work with is often not the first one in the
list, but ordering by created at is useful for other reasons (mainly
around first time use).
This commit adds a find as you type control which aims to give users a
quick way of getting to the template they want to work with.
When a team has lots of templates the choose template page gets very
long. It gets hard to find the template that you are looking for.
Our initial reckon was that teams would not be giving their templates
very useful names, and therefore a preview would be helpful. What we
have found is that:
- teams actually do give their templates useful names, and refer to
these template names elsewhere
- the previews are less useful for emails and text messages, because
they have so much content (which for emails also makes it harder to
`ctrl` + `f` the template name)
The other problem we found was that this page presented the user with
a _lot_ of options. For each template there were 4 actions, plus the
click-to-preview action for letters, plus the ‘see previous version’
action for templates that had been edited multiple times. It was a very
busy page.
And the final problem (that we recently introduced) was that there was
no way, other than the visual cues, to know whether a template was a
letter, email, or text message.
So this commit strips back the choose template page to be very focused
on finding the right template, by only showing the template name and
type. The user can then click through to a page that shows just a single
template, and perform actions relevant to that template from that page.
The breaking change page temporarily holds the changes in hidden inputs
on the page. The messages content it gets from the `.content` property
on the subject. This is raw and not transformed in any way, so fine.
For the subject it gets the value from the `.subject` attribute on the
template. For email templates, this will be transformed to highlight
placeholders with `<span class='placeholder'>…`. This means that when
the change is confirmed, it’s this encoded version that gets sent to the
API. Which is bad, because we then save `<span class='placeholder'>` in
the database.
This commit changes the page to look at the `._subject` attribute
instead, which is the internal, untransformed version of the subject.
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.
