White labeling the application

Contents[Hide]

1. Overview

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

  • Select and modify the Dundas BI web application's styles
  • 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 (optional)

3. Files kept between upgrades

In each Dundas BI web application there are three types of override files. These files are not overwritten during an upgrade:

Override filePurpose
style.override.css Custom CSS styles for a specific tenant
javascript.override.js Custom scripts running at the site level
Html.Override.html Contains HTML which can be manipulated by the corresponding JS code

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

These files are not overwritten when upgrading Dundas BI to a new version. 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 modify that element.

From the main menu, click Admin, expand Setup and then click App Styling.

Application styling
Application styling

Select the CSS style resource file from the list of files and click Details on the toolbar.

Select CSS override file and view details
Select CSS override file and view details

In the Application Styling Resource dialog, enter the following text in the text box to modify the background on the login page.

Tip
Optionally, you can download the file, update it and then upload it to apply the overrides.

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

For class names, prefix the name with a period (.) instead of a hash (#).

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

Click Submit to apply the changes.

6. Custom HTML

Similar to customizing the CSS style resource you can modify HTML.

To add HTML (including <script> elements) to be included in every page of the application, on the App Styling page, select the HTML resource.

Click Details and on the application Styling Resource dialog, enter the HTML code in the text box.

7. Custom JavaScript

JavaScript that is added will be incuded on every page of the application and is executed when the page loads. You could choose to define your own set of common functions in a global variable that can then be called by scripts on dashboards and other views. You can enter JavaScript on the App Styling page or download the JavaScript resource file, edit it and then upload it for the changes to take effect.

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);
        });
    }
};

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

9. Working with localization files

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

9.1. Find the localization text

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 Web.xml file.

9.2. Create a copy of the localization file

From the main menu, click Admin, expand Setup and then click Localization. A list of localization files are displayed on the right.

Localization
Localization

Select the Web CSS override file from the list of files.

Select the Web localization file
Select the Web localization file

Click Copy on the toolbar to create a copy for a new target culture.

Create a copy of the localization file
Create a copy of the localization file

Set the target culture by entering a language code in Target Culture. For more information about language codes and culture settings, see the Localization and multi-language support article.

Click Submit. The newly created localization file with the culture set to en-US is displayed on the list of localization files.

Double-click the file from the list or select it and and click Details on the toolbar.

The Localization dialog displays the content of the localization file. Notice that the Culture Name is the same as the target culture that was chosen previously.

Localization dialog
Localization dialog

To update the localization, you can update the contents of the file directly using the editor on the dialog or you can upload a new localization file containing the required overrides by clicking the Choose File button.

When you 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>

Click Submit.

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.

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

11. 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:
Phone: 9am-6pm, ET, Mon-Fri
Email: 7am-6pm, ET, Mon-Fri