FixMyStreet: Platform

Customising FixMyStreet templates

This document explains how template inheritance works and how to create your own custom templates.

When it’s building a page, FixMyStreet always looks in your cobrand’s web template directory first: if it finds a template there, it uses it, and if it doesn’t it falls back and uses the base one instead.

base your_cobrand

To see how this works, look at some of the cobrands that already exist in the templates/web directory. You need to create a new directory with your cobrand’s name: for example, do:

mkdir templates/web/fixmypark

Then, to override an existing template, copy it into the templates/web/fixmypark/ directory and edit it there. You must use the same directory and file names as in the parent cobrand (that is, in templates/web/base).

Please note: only make template files for those things you need to do differently; you do not need to copy all the files into your own templates folder. If the change you want to make is very small to the base template, you could consider just adding an IF statement to that parent template instead. The Feeding back page has more details.

One template you will probably want to override is the site-name.html, which contains the name of your site for use in various other templates, and e.g. the site’s <title>. Copy this template into your cobrand like this:

cp templates/web/base/site-name.html templates/web/fixmypark/

Or it’s likely you’ll want to change the footer template, which puts text right at the bottom of every page. Copy the footer template into your cobrand like this:

cp templates/web/base/footer.html templates/web/fixmypark/

The templates use the popular Template Toolkit system — look inside and you’ll see HTML with placeholders like [% THIS %]. The [% INCLUDE ...%] marker pulls in another template, which, just like the footer, you can copy into your own cobrand from fixmystreet or base and edit.

One thing to be careful of: only edit the .html files. FixMyStreet generates .ttc versions, which are cached copies — don't edit these, they automatically get created (and overwritten) when FixMyStreet is running.

The other template you will probably make your own version of is the FAQ which is in templates/web/base/about/faq-en-gb.html. If you translate it too, you will need to rename it accordingly.

Emails

There are also email templates that FixMyStreet uses when it constructs email messages to send out. You can override these in a similar way: look in the templates/email directory and you’ll see cobrands overriding the templates in templates/email/default.

For example, many of the email templates themselves use the small site-name.txt and signature.txt templates, so you may want to override these (by copying them from templates/email/default into your own cobrand’s directory within templates/email, and editing them) even if you’re not changing anything else. On the other hand, you may wish to create new versions of all the emails in order to translate them.

Please do not translate the `Subject:` at the beginning of the first line, as that is used by the code to locate the Subject line of the email.

You may also send out HTML emails, by creating templates with an .html extension as well as the plain text .txt one. In order to save you a lot of time making working HTML emails, you may want to override the _email_color_overrides.html and _email_setting_overrides.html templates to set your own colours/branding, and then only copy other HTML templates to translate or otherwise change the wording.

To preview HTML emails, when running the development server go to /_dev/email/ and click the email you wish to preview.

To include an inline logo in your HTML email, put it at web/cobrands/yourcobrands/images/email-logo.gif and make sure logo_width and logo_height are set appropriately in your _email_color_overrides.html. The email template should then pick it up automatically.