OX Cloud is Open-Xchange´s fully hosted email service that includes:

• OX App Suite deployed in Open-Xchange Data Centres
• Onboarding and Go-To-Market Support
• Customer Service Support

According to the level of customization needed, customers will be able to choose from two different OX Cloud Solutions:

• OX Cloud: ideal for customers ready to go all-in on a 100% standardized cloud offering without the need for any customization
• OX Custom Cloud: Ideal for customers that need some flexibility in addition to the standard solution

OX Cloud and OX Custom Cloud allow customers to change the appearance of OX App Suite and offer their end-users an experience that recalls their brands: a limited set of options can be configured dynamically via UI settings in the configuration. This dynamic theming allows each brand to have its own logo in the top left corner, and its own highlight color instead of the default blue color. Optionally, additional settings can adjust the colors of certain highlights like selected items, keyboard focus, and clickable areas when the mouse pointer hovers over them.

The Open-Xchange documentation contains the  full documentation of dynamic theming. Please note that it includes settings that are not available in OX Cloud and OX Custom Cloud (e.g. styling of the login screen). Only settings described below are supported in OX Cloud.

Pre-requisites

While this article describes the actual configuration of the theme, some pre-requisites are not described here. You will have to set them up as described below.

Logo

If you want to show your own logo, you need an image of the logo. The image format can technically be anything supported by web browsers. But the preferred format is SVG to have the best quality, and with typical logos, the smallest size. Alternatively, a PNG image with at least the double resolution for high-DPI screens can also be used. More details about best practices and recommendations for the various types of logos can be found here.

Logos are typically collected during the onboarding phase and hosted by OX Cloud but in case more different logos are required (e.g. to allow since customers an own logo) images need to be hosted and available via HTTPS from a web server with a valid TLS certificate. To actually use the logo, you will need its URL. It will be referred to as $logourl in the Configuration section below.

An additional logo can be used for the dark theme. It will be referred as $logourldark in the Configuration section below.

Provisioning

The configuration is performed by using the API on a context or reseller via provisioning. The API reference how to do this for the whole brand can be found here.

OX Cloud also supports theming per context using the API if required.

Configuration

The simplest possible configuration is just to set the main highlight color. The UI setting for this is called mainColor. Its value can be any valid CSS color specification. In this example we will set it to #aa5500:

{
    "mainColor": "#aa5500"
}

Here is a complete payload example for the API request to configure a brand:

HTTP POST /cloudapi/v2/brand/theme

Payload (application/json)
{
  "mainColor": "#aa5500",
  "linkColor": "#283f73",
  "toolbarColor": "#283f73",
  "logoUrlLight": "http://example.com/light.png",
  "logoUrlDark": "http://example.com/dark.png",
  "logoWidth": "60",
  "logoHeight": "auto",
  "topbarBackground": "#283f73",
  "topbarHover": "rgba(0, 0, 0, 0.3)",
  "topbarColor": "#ddd",
  "topbarSelected": "#eee",
  "listSelected": "#aaa",
  "listHover": "#f7f7f7",
  "listSelectedFocus": "#283f73",
  "folderBackground": "#f5f5f5",
  "folderSelected": "rgba(0, 0, 0, 0.1)",
  "folderHover": "rgba(0, 0, 0, 0.05)",
  "folderSelectedFocus": "#283f73",
  "mailDetailCSS": "body { color: #000 !important } h1 { color: red}",
  "serverContact": "My Example Org | <a href=contactPath target=\"_blank\">Contact</a>"
}

This results in changing from the original colors:

to the following:

As you can see, the color is used as a background color with white text. This means that this color should be relatively dark to preserve contrast. Similar restrictions, either dark or light, apply to all other configurable colors.

Logo

Next, let's add the logo. Besides specifying the URL of the logo using logoUrlLight, you need to specify its size using logoWidth and logoHeight. When either width or height is set to auto, the image is scaled by browsers to preserve the aspect ratio. Each of the dimensions can be specified as a plain number, which is interpreted as pixels, or as a string which includes a CSS unit. The height is limited by the top bar to 64 pixels. The width is limited only by the other contents of the top bar and the browser width. Please take into account mobile screens in portrait orientation. These can be as small as 320 pixels. The default logo is 60 pixels wide, and its height is set to auto.

If the logo is a raster image (e.g. a PNG), then the image should be at least twice the specified size. This is required to avoid magnification artifacts on modern high-resolution displays, which have more than one actual pixel for every CSS pixel.

An example:

{
	"logoUrlLight": "http://example.com/light.png",
	"logoUrlDark": "http://example.com/dark.png"
}

The result looks as follows with light theme:

The result looks as follows with dark theme:

With this, the theme is already complete. But depending on the selected main color, some adjustments may be needed. The rest of the examples describes such optional adjustments.

Top bar

One adjustment may be needed because of the red dot over the mail icon, which indicates unread mails. If the main color is too similar, this dot will be hard to see. As a fix, we make the color of the top bar darker using the setting topbarBackground.

By default, highlighted items in the top bar (items with keyboard focus and items under the mouse pointer) have a 30% darker background (their background color is set to rgba(0, 0, 0.3)). If the top bar color is already dark, it might be necessary to use the setting topbarHover to set a brighter highlight color. Note, that it should still be dark enough to be used with white text. In the example, we set it to the original main color:

{
    "mainColor": "#aa5500",
    "logoUrlLight": "$logourl",
    "logoWidth": 120,
    "logoHeight": "auto",
    "topbarBackground": "#552a00",
    "topbarHover": "#aa5500"
}

Links

By default, the main color is also used for the text color of links and other clickable elements, such as the toolbar buttons, on a white or light background. For color palettes which have two highlight colors, or if the main color is not distinctive enough to differentiate links from normal text, the color of links can be set separately with linkColor and toolbarColor.  The color still needs to be dark enough to be readable on white background, so we set it to blue:

{
    "mainColor": "#aa5500",
    "logoUrlLight": "$logourl",
    "logoWidth": 120,
    "logoHeight": "auto",
    "topbarBackground": "#552a00",
    "topbarHover": "#aa5500",
    "linkColor": "#0000aa",
	"toolbarColor": "#0000aa"
}

List view

The background color of items in the main list view can be adjusted independently for each possible state of an item:

• Selected elements when the list has the keyboard focus use listSelectedFocus, a dark color;
• Selected items when the list does not have the keyboard focus use listSelected, a light color;
• Hovering with the mouse pointer uses listHover, a light color.

Usually, the two light colors above are a shade of gray or close to gray, to indicate that they do not have the keyboard focus. In the bexample, we use a slightly less saturated version of the main color for selected elements with focus, a slightly darker gray for the selection without focus, and a light yellow for mouse hover:

{
    "mainColor": "#aa5500",
    "logoUrlLight": "$logourl",
    "logoWidth": 120,
    "logoHeight": "auto",
    "topbarBackground": "#552a00"
    "topbarHover": "#aa5500",
    "linkColor": "#0000aa",
	"toolbarColor": "#0000aa",
    "listSelectedFocus": "#aa8055",
    "listSelected": "#cccccc",
    "listHover": "#ffffaa"
}

The selection without focus is visible when the user clicks outside the list view:

The selection with focus and hover colors are visible when the user actively works with the list view:

Folder tree

The final configurable part is the folder tree on the left side. Like the main list, it supports the three different states for selection with and without focus, and mouse hover. The settings are folderSelectedFocus,folderSelected and folderhover, respectively.

In addition the background of the entire folder tree can be adjusted using folderBackground. In the example, we remove it entirely by setting it to white. The other colors will be set to the same values as the corresponding colors in the main list:

{
    "mainColor": "#aa5500",
    "logoUrlLight": "$logourl",
    "logoWidth": 120,
    "logoHeight": "auto",
    "topbarBackground": "#552a00"
    "topbarHover": "#aa5500",
    "linkColor": "#0000aa",
	"toolbarColor": "#0000aa",
    "listSelectedFocus": "#aa8055",
    "listSelected": "#cccccc",
    "listHover": "#ffffaa",
    "folderBackground": "#ffffff",
    "folderSelectedFocus": "#aa8055",
    "folderSelected": "#cccccc",
    "folderHover": "#ffffaa"
}

And the final result looks like this, first with the focus somewhere else:

And then with the focus in the folder tree: