Themes are stored in a special folder named Themes at the root of the repository. The 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 the Themes folder is a special theme whose contents are controlled by the server. The default theme contains the complete definition of every style that makes up the default theme shipped with JasperReports Server. The default theme folder cannot be modified, even by administrators.
| | You cannot modify the files of the default theme through the repository. If you try to do so by circumventing the repository, you could inadvertently change rules and make the UI unusable. If this happens, you'll need to re-install JasperReports Server to recover. |
This chapter uses the following terminology to distinguish between themes.
If no custom theme is made active, the default theme 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.
| Contents of the default 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 provided for reference when creating themes. 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 image files for the default theme are stored in a folder named images. In a custom theme, there are two ways to change an image of the default theme:
| • | Create a folder named images and an image file with the same name as the one you want to replace. |
| • | Modify the corresponding CSS rules to specify the name and location of a different image. |
When you modify the CSS rules, you can use any of the following ways to reference image files or any other helper file:
| • | Directly in the theme folder. In this case the file is referenced without a path, for example "myfile.png" in CSS. |
| • | In any folder path located in the theme folder. For example, your custom CSS file could refer to "MyImages/myfile.png" if you create a folder named MyImages in the theme folder and upload your images there. |
| • | Anywhere on the Internet. Following the CSS standard, your custom CSS can refer to images or any helper file with a regular URL. |
Inheritance
In order to render the user interface, JasperReports Server must load each of the CSS files listed in “Contents of the 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.
| 1. | The active theme folder: /Themes/<active-theme> |
| 2. | The default theme stored in /Themes/default. |
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 default theme.
The active theme does not need to contain all the files because the default theme is guaranteed to contain all the files.
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.
| • | If you modify the user interface extensively, you can use the existing structure of CSS files in the default theme. In this case, copy the relevant files from the default theme, make your modifications, and save the files in your new theme. The new files are inherited when you activate the theme. |
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.
Recommended Comments
There are no comments to display.