• Home

White labeling the application

Contents[Hide]

1. Overview

This article shows how to white label the Dundas BI web application. You will learn how to do the following:

  • Select styles within the Dundas BI web application
  • Modify the styles in the override files
  • Customize images
  • Customize displayed text using localization overrides
  • Add your own JavaScript or HTML to be included throughout the application
  • Maintain your custom files between versions

2. Getting started

The following prerequisites must be installed on your computer:

  • A Dundas BI web application
  • Google Chrome, or another browser that allows elements in the page to be inspected
  • Notepad, or another way to edit and save CSS files

3. Keep files between upgrades

In each Dundas BI web application there are three override folders:

  • [BIWebsite]Content\Override - Contains the file style.override.css for your custom styles.
  • [BIWebsite]Scripts\Override - Contains the file javascript.override.js  for custom scripts that run at the site level.
  • [BIWebsite]Override - Contains the file Html.Override.html, for HTML that should be included in every page. You could add HTML here to be manipulated in JavaScript.

The images located in the [BIWebsite]Content\Images\favicon folder are also not replaced during upgrade.

These folders are safe when upgrading Dundas BI to a new version as their contents are never replaced. They are the only folders that should be used for customizing the application, with the exception of new files placed in a whitelabel folder to avoid the potential for naming conflicts, as described below for images. All other Dundas BI Web Application files may be overwritten during the upgrade process.

4. Selecting styles

This section shows how to use Google Chrome to extract IDs and classes from page elements. Specifically, we are going to select the element used as the background of the login page to change its color.

Pull up the Dundas BI login page.

Dundas BI login page
Dundas BI login page

Press F12, or open the developer tools from the browser menu.

Google Chrome's developer tools
Google Chrome's developer tools

In the Elements tab, click the element inspector icon next to the tabs in the toolbar (if using Chrome):

Element inspector
Element inspector

Now click on the page background. You will notice that it selects the page element <div id="loginPage-content">. We will now modify the element with this ID in our style override file.

Login page content selected
Login page content selected

5. Modifying styles

In the previous section we selected an element. In this section we will change that element using the style override file. This file is located at: [BIWebsite]Content\Override\style.override.css.

Open Notepad or another editor, and open the style override file. (You may need to right-click your editing program in the start menu and choose Run as administrator to be able to save changes to files if they are under the Program Files folder.)

If it is a new deployment you will get a file with the following:

/* Add any CSS overrides in this document */

Now we want to modify the background of the login page, which we can do with the following text:

/* Add any CSS overrides in this document */
/* Main page background */
#loginPage-content
{
    background-color: #e8f0ff; 
}

Note
Some styles may require adding !important after the value for it to take precedence.

Save the file and reload the page to see the changes applied:

After style override
After style override

6. Working with images

To change an image, we first must add it to the BI website.

Create a whitelabel folder in the [BIWebsite]Content\Images folder.

White label image folder
White label image folder

Copy your new image to the folder you just created. For example, [BIWebsite]Content\Images\whitelabel\logo.png.

In order to change an image we need to first select the image element on the page and get its class.

Dundas BI login logo selected
Dundas BI login logo selected

The logo has the class loginPage-logo, and is located inside an element with the ID loginPage-contentHeader. In the style.override.css file, we can target elements within this element that also have the matching class with the following text:

/* Logo */
#loginPage-contentHeader .loginPage-logo 
{
    background-image: url(../Images/whitelabel/logo.png);
    background-position: center center;
    background-repeat: no-repeat;
    background-size: contain;
}

After adding the override for the logo we should get the following:

Dundas BI login logo changed
Dundas BI login logo changed

7. Working with localized text

You can change any of the text in the Dundas BI interface in the localization XML files.

To start white labeling localized text we first must find the where the localized text is located. In our example, we want to localize the text Log on to Dundas BI in the page title.

Dundas BI login page tab
Dundas BI login page tab

This is found in the [BIWebsite]\App_Data\Localization\en\Web.xml. Rather than writing directly to this file we will create an override folder and file. This is done in order to avoid changes being wiped out during upgrades.

Create a folder named override within the localization\en folder.

Localized folder
Localized folder

Create an XML file with the same name as the one you want to override, but ending with .override.xml instead of just .xml. For example, if you want to override Web.xml, you would create a file called Web.override.xml in the override folder.

Web override localized file
Web override localized file

Populate the override file. It should be the same format as the regular localization files, but only needs to contain the strings you want to override.

<?xml version="1.0" encoding="utf-8" ?>
<localization xmlns="http://dundas.com/schemas/BI/localization.xsd" 
                   culture="en" 
                   moduleId="21259D43-EE4C-4B06-B73F-C9C2CDCE60C6">
    <group name="LogOnView">
        <string key="GS_LogOn_Title">Log on to CTT</string>
    </group>
</localization>

Restart the application pool or IIS for the changes to take effect.

Tip
You can also white label the default names of files created by Dundas BI. For example, override the value of GS_ImportExport_FilePrefix (you can find it in Dundas.Core.xml) to change the prefix of exported DBIE files.

8. Modifying the favicon

To modify the favorite icon displayed next to the page title by the browser, modify all of the images located in the folder [BIWebsite]Content\Images\favicon.

Note
These images will not be replaced during upgrade.

After the changes, the browser tab looks like the following:

Tab icon and text changed
Tab icon and text changed

9. Custom HTML and JavaScript

To add HTML (including <script> elements) to be included in every page of the application, modify the [BIWebsite]Override\Html.Override.html file.

JavaScript added to the file [BIWebsite]Scripts\Override\javascript.override.js will be executed when the page loads.

You could choose to use this file to define your own set of common functions in a global variable that can then be called by scripts on dashboards and other views. For example:

window.corporateLibrary = {

    palette: ["#418cf0", "#fcb441", "#e0400a", "#056492", "#bfbfbf", "#1a3c69", "#e1e480", "#119cdd", "#cb6a49", "#005cdb", "#f4d288", "#506381", "#f1b9a8", "#e0830a", "#7893be"],

    applyPaletteColors: function (colorRules) {
        var discreteRules = colorRules.filter(function (rule) {
            return rule instanceof dundas.controls.DiscreteColorRule;
        });
        discreteRules.forEach(function (rule, index) {
            var colorString = corporateLibrary.palette[index % corporateLibrary.palette.length];
            rule.value = dundas.controls.Color.fromString(colorString);
        });
    }
};

You can also add other JavaScript files in the same folder and include references to them or load them.

10. See also

Dundas Data Visualization, Inc.
500-250 Ferrand Drive
Toronto, ON, Canada
M3C 3G8

North America: 1.800.463.1492
International: 1.416.467.5100

Dundas Support Hours: 7am-6pm, ET, Mon-Fri