Many components of the user interface are created from the source code. The entire process from designing the UI in source files to displaying the UI in the server is very complex, with several interacting mechanisms. JasperReports Server uses the Spring Framework based on compiled Java beans, but the layout of the UI is also controlled by Java Server Pages (JSP files), the SiteMesh framework that decorates pages, and the CSS files seen in the previous section. Some of these mechanisms use additional XML files for configuration.
There are essentially two kinds of files that are involved in creating the UI:
| • | Interpreted files such as JSP, XML, and CSS that the server processes in order to generate the UI. The advantage of interpreted files is that you can modify them in a running instance and have them take effect immediately (as with CSS), or after restarting the server (as with JSP). Much of the UI can be customized with interpreted files. |
| • | Compiled Java files that define the underlying behavior of the server, for example, what happens when you click a button to run a report. These are Java beans that are used in the Spring framework, where they are also called Spring beans. |
In order to change the behavior of a Java file, you must recompile it, rebuild the server, and redeploy it in an application server. Therefore, to change UI features controlled by Java files, you must have the source code distribution and a testing environment to build and deploy the server. For more information, see Working With Custom Java Classes.
File Locations
Interpreted files are located in the JasperReports Server web application, known as <js‑webapp>. Depending on your deployment and your needs, there are several ways to work with the interpreted files, which in turn determine the definition of <js-webapp> that you use.
| File Location | <js-webapp> Path |
| Installed server | Once you have installed your server, either through a platform installer or any other deployment, the files are deployed in a running application server. The location depends on the application server where you installed JasperReports Server. If you used the bundled Apache Tomcat application server, the files are located in: <js-webapp> = <js-install>/apache-tomcat/webapps/jasperserver[-pro] For other application servers, see Modifying WAR Files. After modifying the UI files (except CSS), reload the web app to see the changes. This is the easiest way to customize files, because you can see your changes almost immediately. However, your changes are limited to this one instance of the server. |
| WAR file distribution | When you download the WAR (web archive) file distribution, you can customize your deployment of JasperReports Server and possibly install it on several machines. The WAR file distribution also includes the UI files in the following location: <js-webapp> = <js-install>/jasperserver[-pro].war To modify files with the WAR file, see Modifying WAR Files. After modifying the WAR file distribution, you need to deploy it to your application server, as described in the JasperReports Server Installation Guide. But every time you redeploy your modified WAR file, your UI changes are included. |
| Source code | The JasperReports Server source code also contains the original versions of the interpreted files. If you maintain other customizations in the source code, you can modify the UI files as well. The files in the source code are located in: <js-webapp> = <js-src>/jasperserver/jasperserver-war/src/main/webapp When building the source, these files are copied into the WAR file that you must then deploy into a running application server. See the JasperReports Server Source Build Guide for more information. The advantage of working with the source code is that you can always generate the server with your customized UI files. |
| | When working with the WAR file distribution or source code, you usually modify files in an installed server for testing. But after testing, you copy the changes into your WAR file or source code. |
JavaScript and JSP Folders
Inside the JasperReports Server web application, the various JavaScript and JSP files are organized as follows:
| • | JavaScript files are all in the <js-webapp>/scripts folder. File names contain module and subcomponent names, for example <js-webapp>/scripts/adhoc.chart.js. |
| • | JSP files are split up under the <js-webapp>/WEB-INF/jsp folder: |
| • | The <js-webapp>/WEB-INF/jsp/templates folder contains UI components such as panels, lists, menu, and dialogs. |
| • | The <js-webapp>/WEB-INF/jsp/modules folder contains flow-specific pages: |
| • | The main layout and subpanel JSP files are directly in modules. |
| • | Each feature has subfolders for its various JSPs. |
Modifying WAR Files
When modifying UI files in application servers other than Apache Tomcat or in the WAR file distribution, the web application is kept as a single WAR (web archive) file. To modify files inside the WAR file, you must extract, modify and replace the files. The following example shows one way to do this from the Windows command line (the commands are similar in Linux).
In this example, <path/filename> refers to the relative path and name of the file to modify within the WAR file:
After modifying files in the running application or reloading the web application, you may need to perform the following steps, depending on your application server:
| 1. | Clear the application server's work folder. In the case of Apache Tomcat, you would delete all files and folders in the <tomcat>/work folder. |
| 2. | Click Refresh on your browser. |
| 3. | In some cases, you may need to restart the application server. |
Reloading the JasperReports Server Web App
When you customize interpreted files such as the JSP, JavaScript, and properties files, you need to reload them in the JasperReports Server web application to take effect. The standard installation of the server only includes shortcut actions for starting and stopping the bundled application server and database server. If you have other web applications that you don’t want to stop, or if you are doing a lot of customization and testing, it is simpler and quicker to simply reload the web app without restarting the application server.
Each different application server has its own management console that lets you view and control the web apps that are deployed. This example shows how to manage the JasperReports Server web app in the bundled Apache Tomcat.
| 1. | If you have not configured any users on your Apache Tomcat server, you must first add a user and give him the manager role. To do this: |
| a. | Edit the file <js-install>/apache-tomcat/conf/tomcat-users.xml. |
| b. | Create a user if necessary and give it the manager role. You can give the user any name and password you prefer. |
| c. | Restart your Apache Tomcat server for this change to take effect. |
| 2. | Once you have created a manager user, open the Apache Tomcat Manager page in a browser: http://<host>:<port>/manager/html/, where <host> and <port> are where you installed the server. For a default installation, use http://localhost:8080/manager/html/. |
| 3. | When prompted, log in with your manager user credentials. |
| 4. | On the Apache Tomcat management interface, scroll down to find the jasperserver[-pro] application, and click Reload. |
| 5. | After you confirm you want to reload the web app, wait until the page reloads, then open the JasperReports Server login page to see your changes. If the manager doesn’t reload, there was likely an error in the files, and you must then stop and restart the app server. |
Recommended Comments
There are no comments to display.