Customizing HTML Email Templates

In addition to the standard email templates that are provided by Arches, from version 7.5 is possible to customize (“customise”, if not spelled in the US) HTML email templates in your Arches project to include such things as branding, logos, custom text and other elements specific to a given instance.

A developer will need to customize the starting templates and add any extra context items to the settings file which are required by the templates.

Templates and their Locations

Main Templates

The starting templates provided when you create a new project are:

• Download Read Email Notification

• General Notification

• Package Load Completion Notification

These templates are located in the following directory: <project name>/templates/emails/

They overwrite the out-of-the-box templates found in the arches install directory. If you do not wish the arches install directory versions to be overwritten then remove these templates from the project directory.

They consist of static text and variables. The variables are used to render the email with the appropriate context items. The variables are enclosed in double curly braces, e.g. {{ variable_name }}.

Templates for Common Styling and Formatting

There are also three files supplied which are referenced in the above templates as includes. These files allow for common styling and formatting to be applied to all the HTML email templates. These files are: - custom_email_css.htm - custom_email_footer.htm - custom_email_header.htm

Initially the above files are empty.

The files are located in the following directory: <project name>/templates

When adding an image logo, you may wish to do so in Base64 encoded format to ensure the images appear as expected in the email. There are a number of online tools that can be used to convert an image to Base64 format.

Extra Context Items

In some instances, you may wish to add extra context items which are used by the template to render the email. These context items are stored in the EXTRA_EMAIL_CONTEXT setting within the settings.py or settings_local.py file.

The starting default EXTRA_EMAIL_CONTEXT object contains the value for Salutation and a expiration date that is based on the CELERY_SEARCH_EXPORT_EXPIRES setting.

For the sake of consistency, if you are using common templated text across templates while not in the default context items, it is recommended that you add it to the EXTRA_EMAIL_CONTEXT setting.

For example, if you have a common email address that you wish to use across all templates, you could add it to the EXTRA_EMAIL_CONTEXT setting as follows:

EXTRA_EMAIL_CONTEXT = {
        "salutation": ("Hi"),
        "expiration":(
                datetime.now()
                + timedelta(seconds=CELERY_SEARCH_EXPORT_EXPIRES)
        ).strftime("%A, %d %B %Y"),
        "email_address": ("person@example.org"),
}

You would then be able to use the tag {{ email_address }} to render the email address in your template(s).

Other Considerations

You are advised, when creating customized HTML email templates, to ensure the templates are accessible. For further information on configuring your templates to be accessible, see the Accessibility section.