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