Things we don’t do with SMS messages any more:
- put paragraphs in them (we use `<br>` tags instead, to allow for
multiple linebreaks)
- pick them using radio buttons
- render the template’s name as part of the template
- render the phone number that the message will be sent from as part of
the template
Previous implementations of this functionality mutated the base form
class, which broke a bunch of stuff.
I want to make sure that getting this form for one placeholder doesn’t
change other forms that have already been instantiated for other
placeholders.
Mutation is scary.
Because we put the step in the URL, users could:
- skip ahead to a later step
- navigate to a step which doesn’t exist (ie an index greater than the
number of placeholders)
This commit adds some checks to do the sensible thing in the unlikely
event that either of these situations occur.
Calculating the number of pages in a letter is quite slow. And the send
yourself a test pages need to load _fast_. Since filling in placeholders
is very unlikely to change the number of pages in the resultant letter,
it’s pretty safe to cache that count, and makes the subsequent pages
load a lot faster.
People are going to hammer through this form _fast_, so not making them
click into the form field on every page load is a nice enhancement.
Reuses the code written to do this on the page where you enter your
verification code.
You might need to scroll this page quite a lot to see where a
placeholder appears in your template – especially if you have a long
email or letter.
One of the things I’m trying to stop happening so much is a lot of
scrolling back and forth. This would happen if you were scrolling down
to see the placeholder, then back up to fill in its value.
So this commit makes the textbox ‘sticky’, ie it always stays at the top
of the viewport, even when you scroll down. This lets you see the
placeholder and the textbox side by side, no matter how long the
template is.
The code to do this mostly comes from the GOV.UK Frontend Toolkit
(documented here: d9489a9870/docs/javascript.md (stick-at-top-when-scrolling)).
I had to add some extra CSS to make it look good when it overlaps the
content of the page, which the GOV.UK Frontend Toolkit implementation
doesn’t really anticipate.
The send yourself a test feature is useful for two things:
- constructing an email/text message/letter without uploading a CSV file
- seeing what the thing your going to send will look like (either by
getting it in your inbox or downloading the PDF)
- learning the concept of placeholders, ie understanding they’re thing
that gets populated with _stuff_
The problem we’re seeing is that the current UI breaks when a template
has a lot of placeholders. This is especially apparent with letter
templates, which have a minimum of 7 placeholders by virtue of the
address.
The idea behind having the form fields side-by-side was to help people
understand the relationship between their spreadsheet columns and the
placeholders. But this means that the page was doing a lot of work,
trying to teach:
- replacement of placeholders
- link between placeholders and spreadsheet columns
The latter is better explained by the example spreadsheet shown on the
upload page. So it can safely be removed from the send yourself a test
page – in other words the fields don’t need to be shown side by side.
Showing them one-at-a-time works well because:
- it’s really obvious, even on first use, what the page is asking you to
do
- as your step through each placeholder, you see the message build up
with the data you’ve entered – you’re learning how replacement of
placeholders works by repetition
This also means adding a matching endpoint for viewing each step of
making the test letter as a PDF/PNG because we can’t reuse the view of
the template without any placeholders filled any more.
It’s easier to work out what the errors are in your file if you can
see the big red error message right next to the contents of your file.
When users get errors they tend to go back and forth between the error
message and the view of the file, not the message and the template
preview.
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.
‘Print a test letter’ seems to be closer to what people’s expectations
of what this feature does are.
The word ‘generate’ sounded too much like something the system was
doing, rather than something you, the user, were doing.
Having to scroll past the template preview is fine for a short text
message, but annoying and confusing for a long letter. We even have
people completely missing what the page is for, because they don’t go
all the way to the bottom.
This change makes more sense now that we have a page for previewing a
template (not one long page with all the templates). You’re already
pretty confident that you’re using the right template on this page. It’s
just there as a double-check, and to help people understand where the
columns in the example file are coming from.
It doesn’t need to be a bullet point for each format. We tested this in
research with DWP staff yesterday and it didn’t cause any problems. I
also think it’s nicer for the UI to tell you what you need to do, rather
than tell you what it can “accept”.
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.
