Customizing the User Interface

JasperReports Server is highly customizable because it is built on the Spring Framework and uses web standards such as Cascading Style Sheets (CSS) and JavaServer Pages (JSP). When the server is embedded in a web application or portal, its user interface (UI) can be customized to extend functionality and better reflect the parent application.

As with any large web application, the logic to generate the JasperReports Server UI is complex and relies on several mechanisms. They are listed here from simplest to most complex.

Themes – The themes mechanism exposes the CSS of the UI through the repository. This makes it easy for administrators change to the appearance of the UI, such as images, colors, font size, spacing, and even the general layout. The theme mechanism is described in detail in the JasperReports Server Administrator Guide. Refer to that document first.
SiteMesh – The SiteMesh decorator mechanism creates the header and footer for every page of the server. Decorators provide a quick way to edit the overall appearance of the web app, such as branding and copyright.
Java Server Pages (JSP) and JavaScript – These are the templates and logic, respectively, that generate the pages of JasperReports Server. Edit these files to change the content of individual pages or the way a page is generated. This chapter assumes you are familiar with JSP and JavaScript syntax.
Action Model – This mechanism provides a simple way to edit any menu in JasperReports Server. The simple XML syntax lets you remove default menu items, restrict their visibility based on roles, and add new menu items if you have implemented an action.
Spring MVC (Model, View, and Controller) and Spring Web Flow are frameworks for creating states and transitions that represent a business process in a web application. By creating custom flows, you can add your own sequence of pages that integrate with the server.

Themes can be modified in a running server and changes can be seen immediately by all users. For all other types of customization, you need to edit the files that are deployed in the web app. If you are modifying files in the web application, you then need to redeploy the web app in the app server. In some cases, you need to modify source code, in which case you must re-compile the source code and redeploy the web app in the app server.

This chapter includes the following sections:

Changing the UI With Themes
Customizing the UI With Web App Files
Customizing the Branding with SiteMesh
Customizing JSP and JavaScript for the Login Page
Setting the Home Page
Customizing the Report Rendering Page
Customizing Menus
Working With Custom Java Classes
Adding a Custom JSP Page in a Spring Web Flow
Adding Custom Export Channels

The information in this chapter applies to JasperReports Server 4.7 and later. For previous versions of the server, refer to the corresponding version of the JasperReports Server Ultimate Guide.

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.

This chapter assumes that you are proficient with CSS and with J2EE application development and configuration.

Some of the changes described here are cosmetic, but others affect the core behavior of the server. Use extreme caution when making the described edits, because inadvertent changes might cause JasperReports Server to fail. Jaspersoft recommends that you make all customizations in an isolated test environment before applying them in your production environment.