Customizing Styles, Fonts and Graphics

Configuration

Set a system property or an environment variable named CADENZA_THEMES_PATH (see Environment Variables, System Properties and Other Runtime Configuration Options) to point to the base directory where your custom theme is located.

To override the Cadenza default styles, you may provide for example a custom theme.js file as part of your theme:

<CADENZA_THEMES_PATH>/default/js/theme.js

How to Modify Styles

For style changes you may provide these files: The Theme API file theme.js and the customerGlobal.css.

You should start and if possible limit yourself to the Theme API using theme.js since that is the most maintainable.

The customerGlobal.css file is your fallback if you need to override any additional CSS selectors. It’s not recommended to do that and should only be done in exceptional cases. It is not guaranteed that styles in the customerGlobal.css file will work also with future Cadenza versions.

Images that are referenced in the theme.js or the customerGlobal.css can be placed in the folder themes/default/images.

After changing styles it is recommended to do a cache-ignoring page refresh in the used browser(s) to ensure all changes are applied correctly: - Windows/Linux: Hold CTRL and press F5 - this works for all supported browsers in Windows and Linux. - Mac: Hold Shift and click the reload button - this works for Chrome and Firefox in macOS.

Using the Theming API With the theme.js File

The idea of the Theming API is to provide a defined set of styling properties, which make the customization of Cadenza easy and maintainable.

In contrast to customization using the customerGlobal.css file, customization using the Theming API should still work after upgrading to a new version of Cadenza - or at least there is a simple upgrade path.

Creating a theme.js File

The styling properties are defined in the themes/default/js/theme.js file. This section gives an overview over the currently supported properties.

Changes to the theme.js are taken into account at runtime without any further intermediate step. Therefore, make sure that you always save the file in a consistent state.
Example theme.js File:
Disy.theme = {
  'primary-color': '#004d29',
  'default-font-size': '14px',
  'default-font-family': 'Gudea, Roboto, Arial, Helvetica, sans-serif',
  'login-center': true,
}

Changing Colors

Colors are defined using the hexadecimal or the rgba() functional notation, e.g. #ff0000 or rgba(255, 0, 0, 1) for the color "red".

More info: https://developer.mozilla.org/en-US/docs/Web/CSS/color_value#rgb_colors

Color Properties

default-color – The default text color

Many more UI colors like the background of the map controls are derived from that. Set it to e.g. #ff0000 (red) to get an overview what is affected.

This property has a big impact on the accessibility of Cadenza Web and hence should be changed with care. Only solid, dark colors should be used.

Default value: '#353B44'

link-color – The link color

Default value: '#195aa6'

visited-link-color – The color of visited links

Default value: '#660099'

primary-color – The primary brand color

This color is used for headings and highlighting. Be sure to choose a rather dark color, which works for headings on a light background and as background color for white text.

This property is important for the communication of highlighting to the user. So it is important for both, accessibility and branding.

If you’re unsure, what "dark color" means: The Web Content Accessibility Guidelines (WCAG) recommend a contrast ratio between text and background color of at least (!) 3:1. Check the contrast ratio of lightgray text and your primary-color here: https://contrast-ratio.com/#%23ebeced-on-%232370B7

Default value: '#2370b7'

Customising Typography

Follow these steps to use custom fonts in the theme.js:

  1. Add the font files to the theme directory, e.g. themes/default/fonts/VeraSerifBold.ttf.

  2. Add the required @font-face definitions to the customerGlobal.css:

    @font-face {
  font-family: "Bitstream Vera Serif Bold";
  src: url("../../fonts/VeraSerifBold.ttf");
}

    The URL is relative to the CSS file.

  3. Use the font-family in the theme.js:

    Disy.theme {
  'default-font-family': '"Bitstream Vera Serif Bold", serif'
}

You might also adapt the default-font-size property to restore the known sizes and proportions of Cadenza.

In Web, fonts are usually defined with fallback alternatives, for when a font is not installed on the user’s system.

More info: https://www.smashingmagazine.com/2009/09/complete-guide-to-css-font-stacks/

Typography Properties

default-font-size – The default font size

This should usually not be changed, but it’s useful if you changed the default-font-family (see below) to a font, which looks smaller or bigger.

Default value: '14px'

default-font-family – The default font family

Default value: '"Titillium Web", Arial, Helvetica, sans-serif'

default-font-icon-offset – An offset to fix the vertical alignment of icons when a default-font-family is defined

Depending on the metrics of the default font (ascender, descender, etc.) the vertical alignment of icons that are floating in the text may not be correct. To fix this, you can define a factor for the default-font-size with which the icons are translated vertically.

If no default-font-family is defined, icons are translated slightly to the top.

Default value: -0.1 (0 if a default-font-family is defined.)

heading-font-family – The font family for accentuating headings

Default value: '"Titillium Web", Arial, Helvetica, sans-serif'

Styling Navigation

main-header-bg and view-header-bg – Backgrounds of the main and view navigation headers

You can use any valid CSS background value, which is supported in all relevant browsers (see the Cadenza Web system requirements). These are for example colors, images or gradients.

These properties have a big visual impact and hence are important for branding.

Default value main-header-bg: Same as primary-color
Default value view-header-bg: '#ffffff'

More info on the CSS background property: https://developer.mozilla.org/docs/Web/CSS/background

main-header-invert and view-header-invert – Make the text color of the navigation bars white

If main-header-bg or view-header-bg are rather dark, you should consider activating main-header-invert or view-header-invert respectively for better readability. In this case, the default-color setting is overridden.

Default value main-header-invert: true
Default value view-header-invert: false

main-header-height – The height of the main navigation header

Default value: '40px'

Styling Login

login-center – Center the login form and its contents on the screen

Default value: false

The login-aside property is ignored if this is true.

login-bg – The background color of the login page

Default value: Same as primary-color

login-invert – Make the text color of the login form white

Default value: true

login-aside – Show the optional panel aside the login form

Set this to true if you added contents to the accessAside template. This property is ignored if login-center is true.

Default value: true

login-banner-height – The height of the login banner

Set this if you added contents to the loginBanner template.

Default value: '0px'

Styling Workbooks

worksheet-bg – The background color of worksheets

Default value: #ffffff

workbook-view-border – Show the border of workbook views

Default value: false

workbook-view-bg – The background color of workbook views

Default value: #ffffff

workbook-add-layer-button-primary – Make Add layer button variant "primary"

Default value: false

Enabling or Disabling Features

There is a section in theme.js that contains feature toggles that allows to enable or disable specific features of the web UI.

For example, the following would enable highlighting of the last clicked node in the navigator:

Disy.theme = {
  ...
  features: {
    'nav-tree-highlight-last-clicked-node': true,
  }
}
Controlling the Availability of Certain Cadenza Features describes more parameters that affect the availability of Cadenza features.

Feature Toggles

nav-tree-highlight-last-clicked-node

Controls the highlighting of the last clicked item in the navigation tree.

With this feature enabled, when a user clicks on an item in the navigation tree (not a folder), it becomes highlighted. The highlighting remains until another item is clicked in the same browser tab. In different browser tabs, different items can be highlighted.

Default value: false

Custom CSS

If the theming API is not sufficient for your needs you have a fallback customization possibility through the use of customerGlobal.css. With this file you can override any existing CSS style in Cadenza as it is always loaded last.

Only use this file if you have no other option and the theme.js approach is not sufficient for your needs. As soon as you start overwriting specific CSS styles you are coupled to Cadenzas CSS selectors and look and feel and this may change between versions.