OMERO.web UI customization support

[knabar]

Motivation

https://github.com/ome/omero-web/pull/505 proposes to either outright change or add additional configuration settings to control the scripts and activities buttons in the UI.

While reviewing the UI for accessibility and usability and correcting shortcomings is great, it likely should not be done for individual UI elements and without some review of potential impact to all users.

Proposals

1. Custom CSS

Add new setting to inject a custom CSS file or URL, e.g.:

   $ omero config set omero.web.include_css '/your/path/to/custom/styles.css'

Note: There already is the setting omero.web.base_include_template that allows injection of any HTML at the bottom of the page, which is great for scripts, but CSS should be loaded in the header.

2. Extend templating support

Existing option to use custom templates:

$ omero config append omero.web.template_dirs '"/your/path/to/templates/"'

Django templates are a powerful way to customize pages, but better documentation and examples are needed.

When new areas are identified for customization, adding new {% block %} targets in the templates is preferable over creating new configuration options.

For common customizations that are not necessarily desired or helpful to the larger community, we could create a new collection or repository of templates that can be dropped into an OMERO.web installation.

Current Documentation

https://omero.readthedocs.io/en/stable/sysadmins/customization.html https://omero.readthedocs.io/en/stable/developers/Web/WritingTemplates.html#content-blocks

[sbesson]

Also cross-linking to https://github.com/ome/omero-web/pull/425 which included discussions about extending and overriding templates in the context of OMERO.web apps.

[will-moore]

The Custom CSS is a good idea. Let's do it. I guess we just need to decide which pages get it (maybe all of them in omero-web)? Documentation will need to stress that we might make CSS changes to the UI that would break a user's customisation without it being a "major" release. So users will need to test their custom css on each update (although the webclient UI doesn't change very much).

I guess the base_include_template setting could be used for adding JavaScript (and html) to a page? Probably just need better docs for that one too.

All the current documentation on templates is for creating your own pages that look like the webclient pages, rather than overwriting/extending the existing webclient UI.