Configuring themes

Edit online

You can change the look and feel of the web interface by using themes with custom CSS, HTML, and JavaScript code. You can upload, preview, and activate themes for all users on the server.

Note: Carefully examine and understand the theme files before uploading them to the server. It is possible for the HTML or JavaScript content to be manipulated by an attacker to perform malicious actions. Only upload trusted files.

For theme sample files, visit https://jazz.net/wiki/bin/view/Main/WebUITheming.

Adding custom CSS

A theme can contain one or more CSS files. The CSS files in a theme can either create new CSS rules, or override existing rules. If a CSS rule that is defined in an active theme exactly matches a CSS rule that is defined by the Jazz® Team Server, the CSS rule from the active theme takes precedence.

Tip: If you want to alter the appearance of an interface element, use a tool like Firebug to inspect the DOM node and see what CSS rules affect its appearance. You can then create a theme that overrides those rules in order to alter how the element is displayed.

Adding custom HTML

You can insert custom HTML code into some "theme nodes" of the web interface. Each theme node looks for a certain HTML file in the active theme compressed file. If the HTML file exists, the HTML that is in the theme node is replaced with the HTML code in the theme file. There are four theme nodes where custom HTML code can be inserted by a theme:
  • html/aboveBanner.html - A theme node above the main banner of the web interface
  • html/footerLeft.html - A theme node at the left of the page footer
  • html/footerCenter.html - A theme node at the center of the page footer
  • html/footerRight.html - A theme node at the right of the page footer
  • html/loginFooter.html - A theme node at the bottom of the login page. This theme node is available in version 4.0 and later.
Important: The /html directory must be in the root of the active theme compressed file.

Adding custom JavaScript

A compressed file that contains the theme can also contain custom JavaScript files. All custom JavaScript is evaluated when the page loads, so it is possible to define new Dojo modules and instantiate them when the page loads. The only limitation is that the custom JavaScript codes cannot override the existing JavaScript module definitions.

In addition to running custom JavaScript, you also have the option of creating dijit._Widget instances to populate each of the theme nodes of your custom HTML. Your custom JavaScript code can provide a widget with the appropriate name, and it is instantiated and added to the page as a child of the corresponding theme node:
  • jazz.theme.AboveBannerWidget - Corresponds to the theme node above the main banner of the web interface
  • jazz.theme.FooterLeftWidget - Corresponds to the theme node at the left of the page footer
  • jazz.theme.FooterCenterWidget - Corresponds to the theme node at the center of the page footer
  • jazz.theme.FooterRightWidget - Corresponds to the theme node at the right of the page footer
  • jazz.theme.LoginFooter - Corresponds to the theme node over the license message on the login page. This theme node is available in version 4.0 and later.
    Note: If customizing the login page by using JavaScript does not work, use HTML instead.
Tip: If you must refer to another file in the compressed file for the theme from your JavaScript code, use jazz.util.theming.themeFileUrl(pathInYourZip). This function calculates the URL for any file in the compressed file at run time.

Organizing theme files in a compressed file

  • All CSS files can be anywhere in the compressed file structure.
  • All CSS files in the compressed file are applied to every page.
  • All HTML files that are inserted into a theme node must be at the exact path that is specified by that node.
  • All Javascript files can be anywhere in the compressed file structure.
  • All Javascript files in the compressed file are evaluated when the page loads.
  • The directory structure in the compressed file is preserved.
  • All files and folders for a theme must be in a single compressed file.
  • The compressed file can have any name.

Managing themes

You will manage the themes in the admin page of Jazz Team Server or any IBM® Engineering Lifecycle Management application. Log in to the web interface as administrator, select the Server tab and click Themes under the Configuration navigation menu.

Uploading a new theme

Enter a label for the theme. Click Browse and select the compressed file for your theme. Click Upload. After the file is uploaded successfully, it is displayed in the list of themes under the Manage Theme Styles section.

Previewing a theme

It is important to preview a theme before you activate it for the whole site. To preview a theme, click the Preview link next to theme name. Previewing a theme enables you to browse the web interface for testing the changes you expect to see from your theme. To test your JavaScript, look in the browser console for any error messages. If your JavaScript code contains errors, they do not affect the rest of the web interface, but some of your custom JavaScript might not run.

To stop previewing a theme, remove the ?previewTheme=<THEME_NAME> query argument from the URL.

Tip: Ensure that you preview your theme in different browsers before you activate it. HTML, JavaScript, or CSS code that looks good and works correctly in one browser might not work as you intended on other browsers.

Activating a theme

After you have previewed your theme and you are ready to apply it for all users on your server, click the Activate link. If you want to go back to the original look and feel, you can click the Activate link next to the default theme.

For theme sample files, visit https://jazz.net/wiki/bin/view/Main/WebUITheming.