Introduction

Meridix Platform has support for branding/theming through a Theme provider pipeline.

The following parts of the system can be customized to give your Meridix installation a different look and feel

• Logotypes
• Fonts
• UI colors
• Icons
• Page sections/containers
• Menus (only appearance, not content)
• Report chart colors
• XLSX / XLS exported charts colors
• XLSX / XLS Call specification export
• Module names (multi-language support)
• Report names (multi-language support)
• Measurement object type names (multi-language support)
• Link URLs (e.g. support link)
• Help section iFrame content

The login page is fully customizable where the complete page can be changed to match your company profile. 

Using custom themes

Overview

A theme in Meridix Platform is a set of files (CSS, images, scripts) that are contained in a directory with a specific structure (see below). There is a default theme folder defined that the system uses in no other theme. If a custom theme is defined but a required resource is not included the system falls back on the default theme resource. This means that you can choose to only include the resources that you have changed in the theme structure.

The custom themes should be created with the defined structure (it's recommended to use the default theme as a template) and compress (GZIP) the folder into a file with the name ThemeName.zip where ThemeName is the name of the Theme. There is also an option available to make the theme design phase easier (see On external server as folder structure).

Custom theme location options

There are three ways that the theme resources can be exposed to the Meridix installation.

Locally on the server

The folder (not zipped) should be defined locally in the installation root under the folder [drive]:/[webapp_path]/Themes/ThemeName
In this case, no Theme base URL needs to be defined.
This option is not available on Meridix hosted installations.

As an uploaded theme package (zipped archive)

The zipped theme file should be uploaded to the system on the page Administration->Settings->Theme settings inside the Meridix Platform. When a theme is set and the package type is Theme package, Meridix Platform loads and extracts the custom theme to an internal temporary folder and loads the resources from that location for future requests.
When uploading a new version of an existing theme the package mechanism creates a checksum based on the content of the package and compares it to any existing extracted packages with the same name. If the content has changed (i.e. the checksum) the new package replaces the existing one.
The name of the zip file should be the theme name. Do not add the .zip extension to your theme name setting in the Meridix Platform. This is added automatically if the package type is set to the Theme package.

On external server as folder structure (development only)

The theme folder (not zipped) should be available to the Meridix server on a publicly accessible URL where each individual resource can be accessed with the URL [ThemeBaseUrl]/[ThemeName]/[ThemeResourceRelativePath] ex: http://mycompany.com/Themes/CustomTheme/css/base.css where the http://mycompany.com/Themes is the Theme base URL part and CustomTheme is Theme name and css/base.css is the ThemeResourceRelativePath.

In this case, each time a resource is requested (and not found in the server cache) the system loads the resource from the external resource URL internally and caches the resource for future requests.
This method is only recommended during the development of new themes because it requires the Meridix installation to make several HTTP requests to get the theme content. But it's the easiest way to design new themes since you can change the content on a server controlled by you and it will be used by the Meridix installation.

Configure Meridix Platform to use a custom theme package

To change the current theme settings login into your Meridix installation and go to Administration->Settings->Theme settings

The following settings can be changed:

Theme name
The name of the theme if not set or an empty theme is defined it will use the default theme (Default = "Default"). This value is case-sensitive.

Theme base URL
The base URL location of the theme [folder]. This URL has to be accessible by the Meridix Platform server through HTTP(S). Ex: http://mycompany.com/meridixthemes/[theme name]

Theme package type

• Theme package = The theme content is uploaded as a zipped theme package.
• Remote folder = The theme content is available as a folder/directory structure

Theme server cache duration
The number of seconds that the server caches the theme resource before going to the source (external HTTP URL). This value can be set to small (ex: 2 seconds) during the design phase to prevent stale data from being sent to the client. The default value is 7200 seconds.

Theme client cache duration
The number of seconds that the clients are requested to cache the theme resource before going to the source (external HTTP URL). This value can be set to small (ex: 2 seconds) during the design phase to prevent stale data from being used by the client. The default value is 7200 seconds.

Disable minification
The system minifies CSS and javascript files by default. This setting allows you to disable this feature.

Disable Gzip compression
The system gzip compresses all resources before sending them to the clients. This setting allows you to disable this feature.

So if your custom theme is located on the publicly available URL http://mycompany.com/meridixthemes/customtheme1/ the Theme name should be custometheme1 and the Theme base URL should be http://mycompany.com/meridixthemes/

Theme packages and resources

The theme resource handler (Theme.ashx)

All themeable resources that are loaded in the Meridix Platform are loaded through a resource URL that is independent of the physical location of the resource. Any predefined and custom resources are loaded based on their relative location within the package e.g. an image named logo.gif in a folder named logotypes would have the relative path logotypes/logo.gif and to access this resource through the Theme provider you would need to specify the following URL Theme.ashx?logotypes/logo.gif to access this resource.

URLs containing the Theme.ashx handler is treated specially by the system so you can always call it as a local resource from your current path, so if you are working on the page /Root/Sub/Sub/Page the Theme.ashx can be called as it were present at /Root/Sub/Sub/Page/Theme.ashx.

The theme resource handler also handles caching (both client and server-side) with both an Etag header as well as an expires header based on the settings defined in Meridix Platform. It also takes care of the minification of CSS and javascript files so you do not need to minify them in your theme package. All resources are Gzip compressed if the request contains the header Accept-Encoding with gzip defined (this feature can be disabled).

So if you need to include a custom image (images/custom/myimage.png) and use it from a CSS rule in e.g. base.css you can define it as below and the theme handler will take care of the rest.

.informationDiv 
{
	background-image: url('Theme.ashx?images/custom/myimage.png');
}

The Theme.ashx supports localized resources by replacing the resource path placeholder values {lang-culture} and {lang} with the current culture. Ex: when the page is in Swedish the place holder {lang-culture} will be replaced with sv-SE and {lang} will be replaced with sv if it exists within the resource path. The used language is loaded from the request cookie MERIDIXSTUDIO.language [value: lang].
If a resource is localized the theme package must contain a resource for each of the activated languages in the system. Otherwise, a theme resource exception will be thrown when trying to load a non-existing localized resource.  
*This feature is only available from version 3.7 and later. 

.informationDiv  
{ 
	background-image: url('Theme.ashx?images/custom/myimage_{lang-culture}.png'); 
	// Is translated to Theme.ashx?images/custom/myimage_sv-SE.png on the server side if the current culture is set to sv-SE 
	
	background-image: url('Theme.ashx?images/custom/myimage_{lang}.png');  
	// Is translated to Theme.ashx?images/custom/myimage_sv.png on the server side if the current culture is set to sv-SE or a neutral sv culture 
}

Theme package structure

The theme package (zip file or folder) should be structured as below (see the individual folder/file descriptions in the next section).
You can add additional files and folders and make use of them through the Theme.ashx handler if needed. If a required file does not exist in a custom theme package the default theme resource is used. Its recommended to include all resources even the ones that haven't been changed from the default template in a custom theme since then the theme pipeline is not required to use the fallback mechanism.

• Branding and theming#config
  • Branding and theming#ui_colors.json
• CSS
  • Branding and theming#base.css
  • Branding and theming#login_page.css
  • Branding and theming#help_popup.css
• Branding and theming#images
  • Branding and theming#favicon_default.ico
  • flag_eng.png
  • flag_swe.png
  • icon_{description}_{size}.png (multiple)
  • ....
  • load_animation_{description}.gif (multiple)
  • ....
• Branding and theming#scripts
  • Branding and theming#login_page.js
• Branding and theming#telerik
  • common
    • grid
  • CSS
    • Calendar.Metro.css
    • ComboBox.Metro.css
    • Grid.Metro.css
    • Input.Metro.css
    • Menu.Metro.css
    • TabStrip.Metro.css
    • TreeView.Metro.css
  • metro
    • Calendar
      • sprite.gif
    • ComboBox
      • rcbSprite.png
    • Grid
      • AddRecord.gif
      • Cancel.gif
      • Delete.gif
      • Edit.gif
      • export.gif
      • Filter.gif
      • loading_small.gif
      • MoveDown.gif
      • MoveUp.gif
      • PagingFirst.gif
      • PagingLast.gif
      • PagingNext.gif
      • PagingPrev.gif
      • Refresh.gif
      • rgDrag.gif
      • SingeMinus.gif
      • SinglePlus.gif
      • SortAsc.gif
      • SortDesc.gif
      • sprite.gif
      • Update.gif
    • Input
      • sprite.gif
    • Menu
      • rmExpandArrows.png
    • TabStrip
      • TabStripStates.png
    • TreeView
      • LoadingIcon.gif
      • PlusMinus.png
      • TriState.png

Theme package resource descriptions

The CSS files in the default theme package (that can be downloaded) include comments that describe the rules. But you will probably also need to inspect a live installation with e.g. Firebug or Chrome developer tools to get a complete understanding of the theme resource usages.

All pages in the system contain a script reference to Jquery and Jquery UI.

config/

This folder contains theme resources that are not regular web resources e.g. CSS or JavaScript files. See the descriptions for each file for information about how it is used.

config/ui_colors.json

This file is in JSON format and contains an array of objects that has a Key, a MainRgb, and a SecondRgb property. Each of these properties is mapped to different formating settings server-side. The key describes their usage e.g. ui.chart.color.Red contains the RGB colors for all red chart elements. You can change these RGB values to map the theme palette to a color scheme that matches your theme.

ui.chart.color.XXXX is the chart colors in the web user interface.
export.color.XXXX is the colors used in the Excel exports (xlsx and xls).

Not all keys use both MainRgb and SecondRgb, if a SecondRgb is requested on the server-side but not defined the MainRgb is used. 

/* Color name ref: http://msdn.microsoft.com/en-us/library/system.drawing.color.aspx
The colors should be in the format RGB (hex) or named ex: Blue or LightGreen
*/
[
/* These colors is used for the charts in the UI */
{"Key": "ui.chart.color.Yellow","MainRgb": "#FFD700","SecondRgb": "#FFFF00"},       /* Gold-Yellow */
{"Key": "ui.chart.color.Green","MainRgb": "#228B22","SecondRgb": "#32CD32"},        /* ForestGreen-LimeGreen */
{"Key": "ui.chart.color.Orange","MainRgb": "#FF8C00","SecondRgb": "#FFA500"},       /* DarkOrange-Orange */
....Stripped for brevity

/* These colors is used for the exports exports */
{"Key": "export.color.HeaderRow_MainColor","MainRgb": "#E4E4E5"},
{"Key": "export.color.HeaderRow_SubColor","MainRgb": "#FFFFFF"},
{"Key": "export.color.HeaderRow_BottomBorderColor","MainRgb": "#A9A9A8"},
{"Key": "export.color.HeaderRow_ColumnSeparatorColor","MainRgb": "#CFCFD0"},
{"Key": "export.color.ContentRow_AlternateRowBackgroundColor","MainRgb": "#FFFFC5"},
{"Key": "export.color.CallSpecification_IncomingAnsweredColor","MainRgb": "#C5E28A"},
{"Key": "export.color.CallSpecification_IncomingAbandonedColor","MainRgb": "#FFA697"},
{"Key": "export.color.CallSpecification_OutgoingAnsweredColor","MainRgb": "#99BBD7"},
{"Key": "export.color.CallSpecification_OutgoingAbandonedColor","MainRgb": "#FFCA89"},
{"Key": "export.color.CallSpecification_IncomingBackgroundColor","MainRgb": "#FFFFFF"},
{"Key": "export.color.CallSpecification_OutgoingBackgroundColor","MainRgb": "#E6E6E5"},
{"Key": "export.color.Comment_BackgroundColor","MainRgb": "#FAFAFB"},
{"Key": "export.color.Comment_LineColor","MainRgb": "#A9A9A8"},
{"Key": "export.color.ColumnDescriptions_ContentBackgroundColor","MainRgb": "#FFFFFF"},
{"Key": "export.chart.color.Green","MainRgb": "#00CC00"},
{"Key": "export.chart.color.Blue","MainRgb": "#79BCFF"},
....Stripped for brevity
]

CSS/

This folder contains CSS files used by the default template theme.

css/base.css

This is the main CSS file that is included on every page.

css/login_page.css

This CSS file is included on the login page and can be used to customize the login user interface. Unlike the other pages in the system, this page is fully customizable and all layout CSS is included in this file.

css/help_popup.css

This CSS file is included in all popup windows e.g. help popups.

images/

This folder contains all images and icons for the theme. The name of the image contains a size and a short description. Use e.g. Firebug to find out what a particular image in the default theme is named.

images/favicon_default.ico

This .ico image is used as a favicon in the browsers that support favicons.

scripts/

This folder contains script files used by the theme.

scripts/login_page.js

This javascript file is included on the login page and can be used to customize the DOM with e.g. JQuery.

telerik/

Meridix Platform uses several Telerik controls from their ASP.Net AJAX suite. These controls can be customized with CSS files. The system used a modified version of a Telerik theme called Metro.
Not all resources in this folder are used in the current version. 

The telerik control styling is described at http://www.telerik.com/help/aspnet-ajax

telerik/common/

Contains common resources for the Telerik controls

telerik/css/

This folder contains CSS files that control the appearance of several UI components e.g. the menu. Each CSS file is named ControlType.Metro.css. So if you want to change the appearance of the menu you should edit the file Menu.Metro.css

telerik/metro/

This folder contains other resources that the telerik controls depend on, each control has a subfolder with the name ControlType so if you want to edit any images used in the menu go to the subfolder Menu and make your changes to the image there.

Theme package property hooks/placeholders

All css/less/html/text files have support for placeholders which allow a theme package to load properties from the property provider pipeline. The format is as defined below. Not that it can be surrounded by comments /* */ and still be replaced and uncommented. The reason is that it shall be valid Sass or Less etc.

The format is {=property|property-key-here|default-value-here}

The property key can be any existing or non-existing value in any of the property pipeline sources. If not found, the default value will be used.

/* background-color: {=property|theme.banner-background-color|#005f65}; */

background-color: {=property|theme.banner-background-color|#005f65};

/* color: {=property|theme.banner-color|#005f65}; */

color: {=property|theme.banner-color|#005f65};

any-prop: {=property|custom-name|default-value-if-not-exist};

{=property|custom-name|default-value-if-not-exist};

The main reason for this feature is to allow easy tweaks of an existing theme package to allow e.g. resellers/wholesale customers to get custom branding without the need to have individual theme packages for each.