App Suite Cloud

Page tree

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 1 of 3 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 Private Cloud: Ideal for customers requiring high-level customization and complex requirements in terms of product and support.

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

OX Private Cloud allows customers to have unique brand requirements: for this type of customer, a custom theme package needs to be installed.

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.

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.

The image needs 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 setting user attributes on a context or reseller via provisioning. To be able to do this, your script will need the SOAP client object $OXResellerContextService, the access credentials object $oxaascreds and the context ID $cid, as described in OX Cloud hands-on-provisioning.

Configuration

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

mainColor
my %config = (
    "io.ox/dynamic-theme//mainColor" => "#aa5500"
);

The rest of the code which performs the actual SOAP calls will always be the same, and will not be mentioned in later snippets anymore:

Applying the configuration
my @attrs;
push @attrs, \SOAP::Data->value(
    SOAP::Data->name("key" => "config"),
    SOAP::Data->name("value" => \SOAP::Data->value(
      map {
        SOAP::Data->name("entries" => \SOAP::Data->value(
                SOAP::Data->name("key" => $_),
                SOAP::Data->name("value" => $config{$_})
        ))
          } keys %config
    ))
);

my $context = SOAP::Data->type("Context")->value(
    \SOAP::Data->value(
        SOAP::Data->name("id" => $cid),
        SOAP::Data->name("userAttributes" =>
            \SOAP::Data->value(
                SOAP::Data->name("entries" => @attrs)
            )
        )
    )
);

my $result = $OXResellerContextService->change($context, $oxaascreds);
if ($result->fault()) {
    print STDERR "Error changing context with name $ctxname:\n" .
        $result->faultstring() . "\n";
    next;
}

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 io.ox/dynamic-theme//logoURL, you need to specify its size using io.ox/dynamic-theme//logoWidth and io.ox/dynamic-theme//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.

The io.ox/dynamic-theme//logoURL property can be specified as a string or as an object ({ light: <url>, dark: <url> }). Specifying it as an object allows configuring an additional logo for the dark theme that will be applied when the dark theme is selected. Specifying it as a string, the same logo will be applied for dark and non-dark themes.

An example with a logo twice the size of the default logo:

logo
my %config = (
    "io.ox/dynamic-theme//mainColor" => "#aa5500",
    "io.ox/dynamic-theme//logoURL" => "{\"light\": \"$logourl\", \"dark\": \"$logourldark\"}",
    "io.ox/dynamic-theme//logoWidth" => 120,
    "io.ox/dynamic-theme//logoHeight" => "auto"
);

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 io.ox/dynamic-theme//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 io.ox/dynamic-theme//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:

top bar
my %config = (
    "io.ox/dynamic-theme//mainColor" => "#aa5500",
    "io.ox/dynamic-theme//logoURL" => "{\"light\": \"$logourl\", \"dark\": \"$logourldark\"}",
    "io.ox/dynamic-theme//logoWidth" => 120,
    "io.ox/dynamic-theme//logoHeight" => "auto",
    "io.ox/dynamic-theme//topbarBackground" => "#552a00",
    "io.ox/dynamic-theme//topbarHover" => "#aa5500"
);

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 io.ox/dynamic-theme//linkColor and io.ox/dynamic-theme//toolbarColor.  The color still needs to be dark enough to be readable on white background, so we set it to blue:

linkColor
my %config = (
    "io.ox/dynamic-theme//mainColor" => "#aa5500",
    "io.ox/dynamic-theme//logoURL" => "{\"light\": \"$logourl\", \"dark\": \"$logourldark\"}",
    "io.ox/dynamic-theme//logoWidth" => 120,
    "io.ox/dynamic-theme//logoHeight" => "auto",
    "io.ox/dynamic-theme//topbarBackground" => "#552a00"
    "io.ox/dynamic-theme//topbarHover" => "#aa5500",
    "io.ox/dynamic-theme//linkColor" => "#0000aa"
	"io.ox/dynamic-theme//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 io.ox/dynamic-theme//listSelectedFocus, a dark color;
  • Selected items when the list does not have the keyboard focus use io.ox/dynamic-theme//listSelected, a light color;
  • Hovering with the mouse pointer uses io.ox/dynamic-theme//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:

list view
my %config = (
    "io.ox/dynamic-theme//mainColor" => "#aa5500",
    "io.ox/dynamic-theme//logoURL" => "{\"light\": \"$logourl\", \"dark\": \"$logourldark\"}",
    "io.ox/dynamic-theme//logoWidth" => 120,
    "io.ox/dynamic-theme//logoHeight" => "auto",
    "io.ox/dynamic-theme//topbarBackground" => "#552a00"
    "io.ox/dynamic-theme//topbarHover" => "#aa5500",
    "io.ox/dynamic-theme//linkColor" => "#0000aa",
	"io.ox/dynamic-theme//toolbarColor" => "#0000aa",
    "io.ox/dynamic-theme//listSelectedFocus" => "#aa8055",
    "io.ox/dynamic-theme//listSelected" => "#cccccc",
    "io.ox/dynamic-theme//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 io.ox/dynamic-theme//folderSelectedFocus, io.ox/dynamic-theme//folderSelected and io.ox/dynamic-theme//folderhover, respectively.

In addition the background of the entire folder tree can be adjusted using io.ox/dynamic-theme//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:

folder tree
my %config = (
    "io.ox/dynamic-theme//mainColor" => "#aa5500",
    "io.ox/dynamic-theme//logoURL" => "{\"light\": \"$logourl\", \"dark\": \"$logourldark\"}",
    "io.ox/dynamic-theme//logoWidth" => 120,
    "io.ox/dynamic-theme//logoHeight" => "auto",
    "io.ox/dynamic-theme//topbarBackground" => "#552a00"
    "io.ox/dynamic-theme//topbarHover" => "#aa5500",
    "io.ox/dynamic-theme//linkColor" => "#0000aa",
	"io.ox/dynamic-theme//toolbarColor" => "#0000aa",
    "io.ox/dynamic-theme//listSelectedFocus" => "#aa8055",
    "io.ox/dynamic-theme//listSelected" => "#cccccc",
    "io.ox/dynamic-theme//listHover" => "#ffffaa",
    "io.ox/dynamic-theme//folderBackground" => "#ffffff",
    "io.ox/dynamic-theme//folderSelectedFocus" => "#aa8055",
    "io.ox/dynamic-theme//folderSelected" => "#cccccc",
    "io.ox/dynamic-theme//folderHover" => "#ffffaa"
);

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

And then with the focus in the folder tree:

  • No labels