Introduction

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

The web UI layout CSS is not part of the default theming support but it can be altered if desired by overriding CSS rules in on of the themable CSS files.

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 apperance 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 companys profile.

Using custom themes

Overview

A theme in Meridix studio is a set of files (css, images, scripts) that is contained in a directory with a specific structure (see below). There is a default theme folder that the systems uses in no other theme is defined. If a custom theme is defined but a requiered 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 (its 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 is 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 a uploaded theme package (zipped archive)

The zipped theme file should be uploaded to the system on the page Administration->Settings->Theme settings inside Meridix Studio. When a theme is set and the package type is Theme package Meridix Studio 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 changes (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 Meridix Studio this is added automatically if the package type is set to Theme package).

On external server as folder structure (development only)

The theme folder (not zipped) should be available to the Meridix server on a public accessible URL where each individual resouce 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 the caches the resource for future requests.
This method is only recommended during developent of new themes because it requiers the Meridix installation to make several HTTP requests to get the theme content. But its 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.

Should not be used in a production environment since it forces the server to make several HTTP requests to get the resources. So when you have used this method during the design phase compress the folder to a zip file with the name [ThemeName].zip and upload it as a theme package inside Meridix Studio. (Remember to change the Theme package type from Remote folder to Theme package)

Configure Meridix Studio to use a custom theme package

Only users with the role System Administrators can change theme settings

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 have to be accessible by the Meridix studio 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 being sent to the client. 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 being used by the client. 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 compress 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/

When you have changed the theme settings you may need to logout of the system before you can see your changes. Depending on the previous theme settings (cache durations) the old theme resources can be cached both locally or on the server for a while. You may also need to clear your browser cache to force a new GET request for previously cached resources.

Theme packages and resources

The theme resource handler (Theme.ashx)

All themable resources that are loaded in Meridix Studio is loaded through a resource URL that is independent of the physical location of the resource. Any predifined 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 containg the Theme.ashx handler is treated specially by the system so you can always call is 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 aswell as an expires header based on the settings definied in Meridix Studio. It also takes care of minification of css and javascript files so you do not need to minify them in your theme package, and 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 defined it as below and the theme handler will take care of the the rest.

Use Theme.ashx from CSS

.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 exist 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 or else an theme resource exception will be thrown when trying to load an 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 requiered 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 hasent been changed from the default template in a custom theme since then the theme pipeline is not required to use the fallback mechanism.

The default theme can be downloaded inside Meridix Studio (at the bottom of Administration->Settings->Theme Settings) and be used as a template. (download and unzip to a local folder and make your changes).
All the folders below should be on the root level of a Theme package.

config
- ui_colors.json
css
images
- favicon_default.ico
- flag_eng.png
- flag_swe.png
- icon_{description}_{size}.png (multiple)
- ....
- load_animation_{description}.gif (multiple)
- ....
scripts
- login_page.js
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) includes comments that describes 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 contains a script refence 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 uses both MainRgb and SecondRgb, if a SecondRgb is requested on the server side but not defiend the MainRgb is used.

There is a user interface for editing the JSON data at http://lab.meridix.se/colortweaker/

ui_colors.json

/* 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 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 Studio uses several Telerik controls from their ASP.Net AJAX suite. These controls can be customzied with CSS files. The systemes used a modified version of a Telerik theme called Metro.
Not all resources in this folder is used at 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 apperance of serveral UI components e.g. the menu. Each CSS file is named ControlType.Metro.css. So if you want to change the apperance 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 sub folder 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 replaces 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 som custom branding without the need to have individual theme packages for each.

Branding and theming