You can modify the look of theJasperReports Server user interface by creating a theme: a collection of CSS files and associated images that specify the appearance for all or part of the user interface. A theme controls how the interface appears - for example fonts, colors, spacing, lines, and image elements of the UI. The following sections show how to use themes to change the logo and favicon, change colors and fonts, change the amount of white space in the user interface, and hide user interface elements. Using themes, you customize the branding of the server or completely remove the branding for embedding.
A theme does not control what appears, such as the contents of menus or the effect of clicking a button. A theme also does not provide any security; hidden elements can still be accessed using the correct URL. For more extensive changes, you need to change the JSP files that control the logic of the server and determine what users see, not just how they see it. These additional customizations are described elsewhere in this guide.
Theme files are stored in the repository and can be downloaded, uploaded, and made active through the UI while the server is running. You don’t need to recompile any JasperReports Server source code, or to restart the server. For information on how to create, upload, and administer themes, see the JasperReports Server Administrator Guide.
Keep the following tips in mind when working with themes:
| • | Plan your theme deployment carefully and test it with end-users to ensure it works the way you intend. |
| • | The server must be running and you must be logged in as an administrator to modify themes. Modifications take effect when you make your new theme files active. You not do not need to recompile any code or restart the server. |
| • | You must create or modify your CSS files in an external editor. Once you have modified the files you want, you can create a theme folder directly in the repository, or you can create a theme folder offline and upload it as a ZIP archive file. Use the method that works best for you. |
| • | Your themes can be as simple or as complex as you want. You can combine multiple customizations in a single theme; you can also override one file in your theme with another file. |
| • | In multi-organization deployments, themes defined in a parent organization are expressed in child organizations. Depending on your needs, you may want to implement your theme at the root level or at an organization level. You can also create a set of common customizations in a parent organization and override them in individual child organizations. See the JasperReports Server Administrator Guide for details on the organization hierarchy and how it works with themes. |
Changing the Logo and Favicon
One very simple way to customize JasperReports Server is to replace the Jaspersoft logo and/or favicon with your own images.
The Jaspersoft logo is white on a transparent border and is displayed on the blue background of the default theme. Make sure your logo is visible on this background. You can also change the background color to match your logo, as explained in Changing Colors and Fonts. There are two ways to change the logo in CSS:
| • | If your logo is roughly the same size or has the same dimensions as the Jaspersoft logo, replace the logo file. The Jaspersoft logo is 115 pixels wide by 20 pixels high. |
| • | If your logo cannot be resized or has different dimensions, change the CSS to load your own logo file. |
You can also change the favicon:
| • | To change the favicon, replace the favicon file. The favicon is 16 pixels wide by 16 pixels high and is saved as a .ico file. |
In addition to the logo and favicon, there are other customizations you can do to change the branding of the server. See Editing decorator.jsp for Rebranding.
Replacing the Jaspersoft Files
One way to replace the Jaspersoft logo and/or favicion is to create a file with the same file name as the file that is provided with the server. When you create a theme with this file in the same path as the logo or favicon file, it is displayed instead. This is the easiest customization.
To replace the Jaspersoft logo and/or favicon file with your own:
| 1. | Create a new theme or modify an existing one. |
| 2. | If necessary, add a folder named images to the theme. |
| 3. | To replace the logo, convert your logo or image to the PNG format and save it with the filename logo.png. Then copy the new logo.png to the images folder. |
| 4. | To replace the favicon, convert your favicon to the ICO format and save it with the filename favicon.png. Then copy the new favion.png to the images folder. |
| 5. | Upload and activate the new theme to the chosen location, then click your browser’s Refresh button. |
| | There are several ways to upload themes or individual theme files. You may also upload CSS files and images into an active theme if you already have a custom theme created on the server. For implementation details, see the JasperReports Server Administrator Guide. |
Your logo appears in the top-left corner of every page:
| |
| MyCompany Logo on Home Page |
Modifying the CSS File
Another way to replace the logo is to use your own files and modify the CSS files in the theme so that they reference them. This creates a new filename and path. Use this procedure if your logo cannot be resized to fit in the same space, or if the dimensions of your logo have a different ratio. The Jaspersoft logo is 20 pixels high by 115 pixels wide.
To modify the CSS file to use your own logo file:
| 1. | Create a new theme or modify an existing one. In this theme, you can place your image file in any folder structure you want. |
| 2. | If necessary, copy the overrides_custom.css file from the default theme to the main folder of your theme. |
| 3. | Edit the overrides_custom.css file and add rules such as the following. In this example, the logo is a file called MyCompanyLogo.png in a folder called MyImages and is 40px x 230px. Adjust all pixel values based on the size of your image: |
| | The IDs and classes that are used in the CSS are dependent on the JSP source code for the server. To find out which IDs and property values are used, you need to look at the JSP files. Alternatively, you can inspect the HTML and CSS returned by the server in a browser tool such as Firebug. For more information, see the JasperReports Server Administrator Guide. |
| 4. | Upload and activate the new theme with your images and CSS file, then click your browser’s Refresh button. |
Changing Colors and Fonts
Changing colors, fonts, size, and spacing throughout the UI is very simple with the themes mechanism. However, creating a complete theme that modifies all aspects of the user interface involves changing many CSS rules and re-creating many images of buttons and window decorations.
To provide an example of theme customizations, the sample data installed with JasperReports Server includes two alternate themes: pods_summer and jasper_dark. Each theme makes many changes to the default appearance, mostly a new color scheme. You can activate a theme to see its effect, and you can download its files to see how it works.
| Appearance of the Sample Theme pods_summer |
| |
Like most small-scale customizations, the pods_summer theme uses a single overrides_custom.css file and several image files. The image files have the same names as those in the default theme, so when the theme is activated, they automatically replace the default images.
Just as an example of the CSS involved in modifying a theme, some of the customizations that appear in the figure “Appearance of the Sample Theme pods_summer” are:
| • | New logo as described in Changing the Logo and Favicon. |
| • | Horizontal gradient image for the banner, along with a different color: |
| • | New color for main menu text, a darker green: |
| • | A new image file for the green button bar used for the main menu |
Sprites are image files that contain multiple images. The CSS rules that reference them give a vertical and horizontal offset for reading an individual image from the file. For some buttons and bars, the sprite contains a long image to accommodate any width, and an end cap to be placed at the desired width. For icon sprites, the images often reflect the various icon states, such as enabled, disabled, mouse-over, and pressed.
When customizing the theme images, having multiple images in one file is helpful because it allows you to work with many related images together in an image editor, instead of dealing with numerous files. For example, you can easily change the color hue for all buttons in a sprite file at the same time.
Recommended Comments
There are no comments to display.