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

Each installed instance of Dundas BI includes a folder containing the Dundas BI web application along with images, CSS, and other files downloaded by users. If required, you can add to or create folders named Override or whitelabel for your own custom files.

For example, the images and override files in the following locations are not replaced after an upgrade:

  • [BIWebsite]\wwwroot\Content\Images\favicon
  • [BIWebsite]\wwwroot\Content\Images\whitelabel
  • [BIWebsite]\wwwroot\Content\Override
  • [BIWebsite]\wwwroot\Scripts\Override
  • [BIWebsite]\wwwroot\Override

All other Dundas BI web application files on disk may be overwritten when upgrading an installed instance to a new version.

If Dundas BI is deployed on multiple servers, for example as a server farm, your custom files will need to be added to each installed instance location.

Note
Beginning with version 7, you do not need to add or modify CSS, JavaScript, HTML, or localization files directly on disk and can instead use the App Styling and Localization screens in administration as shown below, which will take effect across your server farm.

3.1. Upgrading to Dundas BI version 7

After upgrading to Dundas BI version 7 or higher, some override files from previous versions are converted into resources and are stored in the application database. Use the Administration interface described later in this article to customize these overrides.

The table shows examples of how the following override files are handled when upgrading to version 7 or higher:

Override fileConverted toPurpose
style.override.css CSS style resource Custom CSS styles
javascript.override.js JavaScript resource Custom scripts running at the site level
Html.Override.html HTML resource Contains HTML to include on each page
[localization].override.xml Localization resource Contains localized or customized application text

Other override files from previous versions with the same file extensions as above are moved to their respective folder under the BIWebsite\wwwroot folder. Other types of custom files such as images can be found in the BIWebsite\Content.migrated folder and can be moved to the \wwwroot folder.

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

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 from the list and click Details on the toolbar.

Select the CSS override resource and view its details
Select the CSS override resource and view its 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 resource as a 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, go to the App Styling page in Admin, and select the HTML resource.

Click Details and enter or upload your HTML code into the Application Styling Resource dialog.

7. Custom JavaScript

JavaScript that is added will be included 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.

On the App Styling page in Admin, select the JavaScript resource. Click Details, then enter or upload your JavaScript.

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]\wwwroot\Content\Images folder.

White label image folder
White label image folder

Copy your new image to the folder you just created. For example, [BIWebsite]\wwwroot\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 CSS style resource, 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(../Content/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 resources.

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

9.2. Create a copy of the localization resource

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

Localization
Localization

Select the Web resource from the list, then click Copy in the toolbar to create an override.

Create a copy of the localization resource
Create a copy of the localization resource

When overriding, you can enter the same Target Culture name as the original localization resource (for example, en for English). You can also enter a different culture name if you want to translate the text shown throughout the application to another language. For more information about language tags and localizing Dundas BI for other languages, see the Localization and multi-language support article.

Click Submit. The newly created localization resource is displayed on the list. It will be identified as an Override if the target culture is the same as the original localization.

Double-click the new resource or select it and click Details on the toolbar.

In the Localization dialog, you can update the resource directly using the editor, or you can upload a new localization resource 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 resources, but only needs to contain the strings you want to override. For example:

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

You may need to restart the application pool of the web server 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) 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]\wwwroot\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