title: Dynamic Theming The dynamic theme plugin allows to have custom colors and logo without creating a real theme for each possible color combination. The customization information is stored in the Configuration Cascade and applied at runtime; once for the login screen, and then again immediately after login. This is necessary because before the login, the user's identity (and therefore the context ID) is not known yet. The only available information which can be used to select a theme is the domain name, i.e. the brand.

Installation

The theme generator consists of the single package open-xchange-dynamic-theme, which is installed on the OX middleware.

Enabling the Plugin

The plugin is enabled or disabled by the capability dynamic-theme, e.g. in a file /opt/open-xchange/etc/dynamic-theme.properties set

com.openexchange.capability.dynamic-theme=true

When using the plugin, the actual theme should be the built-in default theme. To prevent all users from changing it and hide the theme selector in the preferences, set the property io.ox/core//theme to read-only. To do this, change the file /opt/open-xchange/etc/meta/appsuite.yaml as follows:

io.ox/core//theme:
    protected: true

If some users won't use dynamic themes, this approach won't work. Instead, the theme selector can be disabled an enabled by controlling the list of available themes. The theme selector is hidden if the list is empty. To be able to do that with the Configuration Cascade, the entire list of themes needs to be specified as a single JSON value, e.g. by changing the file /opt/open-xchange/etc/settings/appsuite.properties as follows:

io.ox/core/settingOptions//themes={"default":"Default Theme"}

Then, to hide the theme selector for users with a dynamic theme, use the Configuration Cascade to change the value to {}.

Specifying a Theme

The package installs the file /opt/open-xchange/etc/settings/open-xchange-dynamic-theme.properties, which contains the global defaults for the custom theme settings. Any of the settings contained in that file can be changed per-context or at any other granularity supported by the Configuration Cascade. The individual settings are as follows:

In the configuration file, each variable name must be preceded by 'io.ox/dynamic-theme//'. When referring to the value of other variables on the right side of the equals sign, (like in the default value of linkColor) the variable names must be preceded by '@io-ox-dynamic-theme-'. headerLogo and logoURL can be relative (to /appsuite/), or absolute. When using absolute URLs to point to different hosts, use the form //hostname/path to keep the protocol (HTTP or HTTPS) and avoid any unnecessary security warnings.

The colors can be any CSS color, as long as the restriction of the "Dark/Light" column are respected. Colors marked "dark" specify dark backgrounds with white text/icons. If the specified color is too light, accessibility will suffer. Similarly for colors labeled "light".

Theming the Login Screen

Since the login screen does not have access to a user's configuration before the user logs in, all configuration is done via /opt/open-xchange/etc/as-config.yml. The settings in the following table apply to the login screen:

Each of these settings should be placed under the key dynamicTheme like in the following example:

default:
  hosts: all
  dynamicTheme:
    loginColor: "#040"
    headerPrefixColor: "#fff"

Migration from 7.8

The configuration settings have changed between versions 7.8 and 7.10. To avoid having to upgrade all context- and user-specific entries at once, some of the new settings will be overwritten by the corresponding old settings, if the old settings are present and non-empty.

Since ConfigCascade only processes values which are present at the server level, a .properties file with the necessary legacy settings needs to be added in /opt/open-xchange/etc/settings:

io.ox/dynamic-theme//frameColor=
io.ox/dynamic-theme//selectionColor=

The default values in the file need to be empty to allow them being overwritten with the new values once the settings of a user or a context have been upgraded. Any new global defaults should be specified using the new settings in open-xchange-dynamic-theme.properties.