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.
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.