Configuring themes

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.

In the Themes feature, you can modify the look and feel of the Web interface for all users of a particular server by applying custom CSS, HTML, and JavaScript. Use the theme management section to upload, preview, and activate a theme for all users of the server.

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
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
Tip: If you must refer to another file in 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

Managing themes

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.


Feedback