Improve customizability and consistency of templates

[clokep]

Some new templates were added recently that dealt with SSO (#7102, #7240, #7279, #7067), but I think this is a wider issue.

There's a few oddities with the templates used in Synapse:

• Some are hard-coded HTML embedded in Python (this is non-ideal due to no syntax highlighting in editors, etc as well as not being customizable).
• Some "templates" are loaded as raw HTML files, but some are treated as Jinja2. (Note also that some of those are loaded during the configuration step, while some are loaded while handlers are initialized.)
• There's a variety of template directories that must be configured: account_validity, saml2_config, sso, email, user_consent.
• Some of those template directories also allow you to customize the names of templates, while others use hard-coded names (e.g. the account_renewed_html_path setting vs. SSO uses hard-coded names).

I think there's a few concrete things we could do to improve this situation:

• Use a single template directory and allow the user to configure it in a single place.
• Treat all template files as Jinja (even if they don't have variable expressions there could be other reasons you'd want it to be Jinja).
• Hard-code all template names and document them well.
• (Somewhat unrelated, but...) Fix We should fall back to the default templates if we don't find a particular template in the custom template directory #6583 so that missing templates don't break Synapse.

[richvdh]

Some of those template directories also allow you to customize the names of templates, while others use hard-coded names (e.g. the account_renewed_html_path setting vs. SSO uses hard-coded names).

I think the settings that allow you to customise the template names are now deprecated?

[babolivier]

I'm not aware of deprecation for account_renewed_html_path, but it should probably be deprecated.

[clokep]

I think the settings that allow you to customise the template names are now deprecated?

Then this would be a good opportunity to clean them up! 😄

[clokep]

Another idea, per #8444 (comment):

I don't know if it's worth renaming the templates to indicate that they're not pure HTML - e.g. ansible community seems to have gravitated towards ".html.j2" for something that needs templating before it's usable.

[richvdh]

on a related but somewhat tangential note, there are also some static files in https://github.com/matrix-org/synapse/tree/master/synapse/static, whose content or styling might want customising too. It would be nice to give the admin the option to do so.

[clokep]

• Some are hard-coded HTML embedded in Python (this is non-ideal due to no syntax highlighting in editors, etc as well as not being customizable).

This was solved in #8444.

• Some "templates" are loaded as raw HTML files, but some are treated as Jinja2. (Note also that some of those are loaded during the configuration step, while some are loaded while handlers are initialized.)

This was solved in #8037.

[reivilibre]

Another idea, per #8444 (comment):

I don't know if it's worth renaming the templates to indicate that they're not pure HTML - e.g. ansible community seems to have gravitated towards ".html.j2" for something that needs templating before it's usable.

at least Kate (KDE's Advanced Text Editor) understands .html.j2 and offers highlighting for both HTML and Jinja2 at once, so use of this extension seems like a win to me

[babolivier]

#10596 consolidates all custom template directories into one.

Edit: it has been merged, and support for legacy template directories is scheduled to be removed in October.

[richvdh]

Is this now, basically, done? We could remove the deprecated "pick a template name" options but generally I feel like they are fairly harmless?

[richvdh]

support for legacy template directories is scheduled to be removed in October.

opened #10735 to track this

[clokep]

Is this now, basically, done? We could remove the deprecated "pick a template name" options but generally I feel like they are fairly harmless?

I think that's all that's remaining, yes!

I do find less having fewer config options a good goal, but I'm not sure that's worth it in this case.

[richvdh]

alright, I'm going to close this then.