Creating a custom theme

Custom theming lets an administrator override the default Klipfolio light and dark themes and apply their own theme.

A custom theme uses cascading style sheets (CSS) and JavaScript to manipulate the presentation of the application.

A custom theme allows you to create your own visual design by:

  • tailoring the dashboard to better reflect your own brand;
  • tailoring the dashboard to better reflect your client's brand;
  • applying your own customized styling.




Before you begin

  • Your account must be installed with an add-on to allow custom theming.
  • You must have an intermediate understanding of using cascading style-sheets.

Setting up style sheets in the Klipfolio User Interface

  1. Log into your Klipfolio account.
  2. Click Account
  3. Select the Settings tab and click on Branding.
  4. Click the Manage Theme CSS and Images link to make CSS updates. 
  5. Click Edit next to Branding.
  6. Choose Custom to upload your own CSS files. 

Account behaviour

When an account is configured to use a custom theme, the account behaves in the following way.

  1. All users are switched to the custom theme when they next sign-in.
  2. Users are unable to switch between the default light and dark themes.
  3. The application loads the base theme of either light or dark as specified in the custom theme.
  4. On the dashboard, after the default CSS is applied, the application applies the CSS that is defined as the custom theme setting in the Dashboard CSS file.
  5. On the dashboard, after the default CSS is applied, the application applies the JavaScript that is defined as the custom theme setting in the Dashboard CSS file.
  6. On non-dashboard screens, after the default CSS is applied, the application applies the CSS that is defined as the custom theme setting in the Applications CSS file.
  7. On non-dashboard screens, after the default CSS is applied, the application applies the JavaScript that is defined as the custom theme setting in the Applications CSS file.

Base Theme

A custom theme must be based on one of the default Klipfolio light and dark themes. Select the theme that is the closest match in design so that anything not restyled still looks appropriate.

CSS

In your custom theme, you can define one CSS file as an override for the entire application, and one CSS file as an override for the dashboard. These files can contain style overrides for any objects on the page that can be selected using standard CSS selectors.

For example, with CSS overrides, you can :

  • Change the default fonts for the application using publicly available fonts (for domain-specific font packages, you must set up a domain alias)
  • Change the background colors for dashboards, Klips, and other user interface elements
  • Replace default images for buttons and controls with custom images
  • Change padding and margins of objects
  • Hide objects from users

Important: You should test custom CSS changes carefully to ensure there is no negative impact to functionality or the user experience.

You cannot modify the following with CSS:

  • Text strings. For example, you cannot change "My Dashboard" to "Portal".
  • Some Klip visualizations. For example, charts, gauges, and mini-charts.

Hosted Images

Use the Hosted Images feature to upload images for use in custom CSS or JavaScript to the application. Using this feature prevents the display of third-party server warning messages by the web browser and improves overall performance and reliability.

To reference an image file in CSS, use the filename within square brackets . For example,
body {
      background-image: url(‘[myuploaded-image.png]’)
}

Targeting a specific Klip

To adjust the style of one or more specific Klips, you can add one or more classes to the root of any Klip container using the containerClassName. Use the Klip Editor to add this to the Klip’s source code.

For example, add:

"containerClassName": "myclass",

to the root of the Klip, below “layoutConfig”

On the dashboard, the Klip is rendered in a container with the following classes: .klip and .myclass. You can now apply styles to any Klip by using .myclass in a custom CSS file. For example:

.klip.myclass { border:solid 10px orange; }

and/or

.myclass .klip-body { background-color: red; }

You can also specify multiple classes. For example:

"containerClassName": "myclass orange tiny-font ",

With this method, you can mix and match classes on different Klips and streamline your custom CSS.

Targeting a specific dashboard

Currently, you cannot target a specific dashboard.

 

JavaScript

You can run a number of JavaScript files on a dashboard and other pages within the application. JavaScript allows you to make sophisticated runtime changes to the document object model.

Important: You should test custom JavaScript changes carefully to ensure there is no negative impact to functionality or the user experience.

Themes and client accounts

You can define a custom theme for each account. For accounts that have client accounts, each client account can have its own custom theme. Client accounts can also inherit the custom theme of a parent account.

Theme switcher

The theme switcher, located on the dashboard, is disabled and hidden from users when a custom theme is enabled for an account.

 

Mobile

Custom themes have no effect on the mobile user interface.

 

Custom CSS and JavaScript

Attention: Making changes to CSS and JavaScript can create a situation for administrators where the application becomes non-functional or degrades the user experience.

In addition, as the core application evolves, customizations made using CSS and JavaScript may cease to function as intended. Every effort will be made to minimize the potential for disruption, but given the open nature of its capability, it cannot be guaranteed that customizations will be compatible with every update of the software.

Development Tips

You can use the following development tips.

  1. Use your web browser’s built-in development tools to preview changes to CSS in real time.
  2. Use a web browser extension to create and apply custom CSS overrides to your dashboard or application. When you have a working CSS, copy and paste it to a text file, and upload the file to your account.
  3. Use containerClassName to target specific Klips with style overrides.
  4. Use multiple classes with containerClassName to apply cascading styles to Klips.

Resources

You can use the following resources.

Important: Set "Dark" as the base theme, otherwise it may not look correct.

Troubleshooting tip

If you use custom themes and have the Light theme set as your base, you may notice numbers in your data visualizations seem blurred. If this happens, try changing your base theme from Light to Dark. This should correct the white halo effect that’s caused by your base theme colour being referenced for outlines. Note that this change may cause other impacts that can be resolved by modifying your CSS.