Themes are stored in a special folder named Themes at the root of the repository and in every organization. Each Themes folder contains a default theme that can't be edited and any number of custom theme folders. Each theme is stored in its own folder and is known by the name of the folder.

The folder named “default” in every Themes folder is a special theme whose contents are controlled by the server. In the Themes folder at the root, the default theme contains the complete definition of every style that makes up the default theme shipped with JasperReports Server. In the Themes folder of every organization, the default is a system generated theme that contains all styles inherited by the given organization. None of the default theme folders can be modified, even by administrators.

This chapter uses the following terminology to distinguish between root-level and organization-level themes.

Every level of organization, including the root, has a designated active theme. If no custom theme is made active, the default theme at every level is the active theme.

The following figure shows the files of the default theme in the Themes folder at the root of the repository. The name of the folder and its subfolders are bold indicating that it's the active theme.

Theme Files

A complete theme consists of the files listed for the default theme, as shown in the previous figure, along with all referenced images. The file samples.css is used only by the View > UI Samples page described in section User Interface Samples. The files overrides_ie7.css and overrides_ie8.css are only loaded with the style sheets when the user’s browser is Internet Explorer 7 or 8, respectively.

The images associated with a theme include all the icons in the user interface and backgrounds for buttons and borders. Several icons and backgrounds can be stored in the same file called a sprite. The theme also includes the favicon.ico file that appears on browser tabs. There are over 70 image files in the default theme.

The default theme stores referenced image files in a folder named images. In a custom theme, there are two ways to change an image of the default theme:

When you modify the CSS rules, you can use any of the following ways to reference image files or any other helper file:

Inheritance

In order to render the user interface, JasperReports Server must load each of the CSS files listed in “Contents of the Root default Theme”. Because each file can be stored in multiple themes, inheritance determines which file to load. To locate the file, the server looks in the following locations, in the order listed below.

For professional edition users:

For community edition users:

When one of the CSS files references an image file or a helper file, including any path to that file, the server looks for that path and filename in the same two locations, in the same order. In this way, each file and image is resolved first in the active theme, and if not found, then in the inherited theme.

The active theme does not need to contain all the files because the inherited theme that is maintained by the server is guaranteed to contain all the files. Maintaining the inherited theme in every organization is the second task of inheritance.

The server maintains the inherited theme in each organization using the same algorithm. Whenever an administrator changes the active theme or modifies a file in the active theme, the server uses the same algorithm to find all files that define the active theme in this organization and makes a copy of them in every child organization. Thus, the active theme at the parent level becomes the inherited theme at the child organization level. For nested levels of organizations, the algorithm repeats on each level after updating the copy of the inherited theme. In this way, any changes are propagated down to every organization, and yet every level can maintain local overrides in its active theme.

CSS Priority Scheme and Custom Overrides

Once inheritance determines which files to load, the standard CSS priority scheme determines which rules are visible, based on the order in which files are loaded.

This leads to two general ways of developing custom themes:

For example, if you want to increase the size of text on all the buttons in the default theme, you can do this with a few rules in the overrides_custom.css file. You may need to adjust the spacing for certain buttons, but the idea is you only need to change a limited number of rules.

An example of these extensive changes would be if you want to increase the size of the buttons themselves in the default theme. You would need to rewrite the majority of the rules in the buttons.css file and create images for the new buttons. In this case, it is much easier to copy the buttons.css file than to copy dozens of rules into the overrides_custom.css file. You could still use the overrides_custom.css file to adjust the spacing of elements around the buttons, because there would be fewer of those rules to modify.

We recommend using the custom overrides method for most custom themes. A custom theme that changes simple appearances such as colors, fonts, and spacing has relatively few rules and is easily manageable in a single file. And many changes can be made by copying and modifying image files in the custom theme, without writing any CSS rules. Only if you change the fundamental layout or appearance of the user interface, should you consider copying and modifying the other CSS file.

Copying and modifying CSS files is more prone to error, and is slightly less flexible due to file-based inheritance. Your copy of the file must contain all of the CSS rules as the original. If any rules are accidentally deleted or modified, even by a single character, the theme may not work properly. Also, the unmodified rules in the copy of your file now override any updates made to the same file in a parent organization.

For example, if you copy a file that defines gray buttons with plain text and you change the CSS rule to make the text bold, you have created a theme with bold, gray buttons. However, if the theme on the parent organization or system theme is modified so that buttons are blue, your file overrides the new inherited color, and you still have bold, gray buttons. If you had defined the bold text as a single rule in the overrides_custom.css file, your theme would show bold, blue buttons now.