Themes are stored in a special folder named Themes that appear at the root of the repository and in every organization. Each Themes folder contains a default theme that cannot 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 organization Themes, 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. In the following table, the main folder of any organization is named Organization, and active-theme is the name of the theme folder that has been activated:
| Name | Folder | Description |
| root > Themes > default | The unmodified user interface of JasperReports Server, as it appears at first installation. The default theme is defined in the default folder in the Themes folder at the root of the repository. | |
| root > Themes > active-theme | The active theme set at the root level. All users in all organizations see this theme unless there is an organization-specific theme that is activated. The system theme is also used for the login page. When JasperReports Server is first installed, the default theme is active, so it is also the system theme. | |
| Organization > Themes > default | The combination of all active themes in the parent organizations of a given organization, according to the inheritance rules. For any given organization, the theme inherited by that organization is stored in the default folder of that organization’s Themes folder. | |
| Organization > Themes > active-theme | The theme that users of a given organization can see, because an administrator has made it active at the organization or system level. Users see a combination of the active and inherited theme, depending on the files in the active theme and the inheritance rules. |
| | 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 such that the UI becomes unusable. In this situation you must re-install JasperReports Server to recover. |
The following figure shows the default theme in the Themes folder at the root of the repository. The name of the folder (and its subfolders) are bold to indicate that it is the active theme.
| The default Theme in the Root Themes Folder |
| |
Theme Files
A complete theme consists of the files listed for the default theme, as shown in “The default Theme in the Root Themes Folder”, along with all referenced images. In addition, the default theme contains the file samples.css that is only used 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 set of files in the default theme was updated in 4.7. Custom themes developed prior to 4.7 may require upgrading in order to work with the new set of files. For more information see the upgrade procedures in the JasperReports Server Installation Guide. |
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 approximately 60 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:
| • | Use 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 redefine the location where the new image can be found. |
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 Mechanism
In order to render the user interface, Jasper Reports Server must load each of the theme files. Because each file can be stored in multiple themes, the inheritance mechanism determines which file to load.
The server loads each of the CSS files listed in “The default Theme in the Root Themes Folder”. To locate the file, the server looks in the following locations, in the orders listed below.
For professional edition users:
| 1. | The active theme folder for the user’s organization. |
| 2. | The inherited theme stored in the folder named <organization>/Themes/default. |
For other users:
| 1. | The active theme folder. |
| 2. | The inherited theme stored in the folder named /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 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 the inheritance mechanism.
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. 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.
| | Propagating changes to the inherited themes is computationally intensive and can take several moments after making a change to a theme. However, determining inheritance when changes are made is an effective trade-off so that CSS files for rendering client request are resolved nearly instantly. |
CSS Priority Scheme and Custom Overrides
Once the inheritance mechanism 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 inheritance mechanism uses the new files 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.
Jaspersoft recommends 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 the file-based inheritance mechanism. 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 can copy a file that defines gray buttons with plain text, and you change the CSS rule to make the text bold, to create 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.
Recommended Comments
There are no comments to display.