Skip to content

Latest commit

 

History

History
135 lines (81 loc) · 5.54 KB

README.md

File metadata and controls

135 lines (81 loc) · 5.54 KB
Raw

Documentation

Email template

Email branding

The jinja template can render emails with 1 of 4 different brands.

The 4 brands: GOV.UK, GOV.UK and logo, Your logo and Your logo on a colour

Email templates for services without an associated logo will use the first brand, GOV.UK, by default.

Each of the other brands require certain attributes for the template to render them successfully.

Note: the term 'government identity' refers to logos from the government identity system (PDF, 4.2MB).

The dimensions of logos vary. Their height will be either 27px or 54px, depending on what suits the image. The width will adjust to keep the aspect-ratio.

Accessibility hacks

The following hacks have been added to make the template work with assistive technologies.

Empty alt text replaced with a single space

By convention, an empty value for the alt attribute of images tells user agents the image is presentational and to be ignored from the normal flow.

This rule is not respected by some clients and some screenreaders are therefore announcing the images. What's worse is, because of their having no alt text, the images are announced as the URL of the image.

We found giving these images an alt value of " " makes some screenreaders ignore them and others announce them as 'graphic'.

More details of this problem can be found in pull request #542.

No spacer images

A common hack for HTML emails is to use blank images, set to a dimension to create empty space in your layout.

Because of the issue with alt text, any spacer images are announced to the user, which is not the intention. For this reason we should try not to use them.

Use line break element for layout space

Another common hack is to use space characters encoded as HTML entities (ie &nbsp;), for empty space in your layout. These are announced to users of screenreaders so should not be used. A <br /> tag, which is not part of the content of the document, should be used instead.

Email hacks

HTML emails will be viewed on a large range of client programs and devices. The engine used to render the email can also change. Outlook, for example, has changed its renderer through the versions (see this history of outlook email rendering).

Because of this, our email template relies on hacks to let it display consistently across clients/devices.

Meta tag to turn off format-detection

Adding the following stops phone numbers being turned into links.

Example

<meta content="telephone=no" name="format-detection" />

Duplicate CSS in different parts of the document

Clients will apply CSS depending on how it is defined but this is not consistent so multiple applications are needed.

Examples

CSS duplicated between the document head and inline styles.

  <style type="text/css">
    body { margin:0 !important; }

   <body style="margin: 0">

Styles duplicated between inline CSS and HTML4-style attributes on the element.

  <table
      style="width: 100% !important;"
      width="100%"
  >

Layout using tables

CSS used for layout is ignored by many clients. The pre-CSS method of using tables instead is currently the best way to build layouts that work across the greatest number of clients/devices. See this article on why use tables for layout in emails.

We give all our tables role="presentation" to ensure assistive technologies ignore them. We also zero their border, cell-padding and cell-spacing to ensure clients don't apply their own version of these values.

Conditional comments for Outlook

Microsoft-specific conditional comments can be used to deliver blocks of HTML only to certain versions of Outlook.

See this article on using outlook conditional comments for more detail.

   <!--[if (gte mso 9)|(IE)]>
   ...
   <![endif]-->

Use of !important in CSS

Clients can add their own CSS to emails. Using !important means the preceeding styles have a better chance of overwriting any CSS specific to that client.

Use of inline CSS

Some clients strip CSS out from the head of the email. Using inline CSS ensures elements will still be styled if this happens.

Email preheaders

The first line in the <body> of the template is used by clients to show a preview of the email (see the commit that adds the preheader for details.)

We use CSS to hide it from the email when viewed in full.

Uppercase margin CSS

outlook.com strips margins out from CSS but capitalising them means it ignores them. This form is still recognised as valid CSS by all other clients. See this article on margins in outlook.com for details.

Use of bgcolor instead of background-color in CSS

Support for the CSS property background-color across clients is buggy so we use the HTML4-style bgcolor attribute instead. See this guide on support for background-color.