Configuring JasperReports Library
JasperReports Server's reporting features are built on the JasperReports Library, which is embedded in the server. Many of the options you can configure to change the server's functionality are actually JasperReports Library options. The configuration options can control many aspects of the server's behavior, from the way reports are exported into different file formats, to the default font.
These options can be set at different levels:
• | Global – Applies to all reports generated by the server. Global JasperReports properties are defined in the .../WEB-INF/classes/jasperreports.properties file. |
• | Report – Defined in the JRXML of the report and applies to that specific report. |
• | Element – Defined in the JRXML and applies to specific elements of the report. |
For more information about JasperReports Library configuration, see http://jasperreports.sourceforge.net/config.reference.html.
The following sections highlight a few of the available options:
• | Extending JasperReports Library |
• | Changing the Crosstab Limit |
• | Setting a Global Chart Theme |
• | Disabling Interactivity in the Report Viewer |
• | Disabling Chart Types in Dashboards |
• | Changing the Pro Charts Rendering Engine |
• | Configuring a JavaScript Engine for Graphical Report Rendering |
• | Static Export Properties for High Charts |
• | Enabling PDF Accessibility Features in Tables |
• | Enabling HTML in Tooltips |
Extending JasperReports Library
You can extend JasperReports Library by implementing the public interfaces it exposes.
Such an implementation is usually stored in a JAR (Java Archive) that contains a file called jasperreports_extension.properties, and specifies a factory class used to instantiate an extension registry. The extension registry specifies one or more extension objects, each of which corresponds to a JasperReports Library extension point represented by a Java interface.
Place this JAR on the JasperReports Library classpath, and your extension is automatically available.
For more information, refer to JasperReports Library Ultimate Guide.
Changing the Crosstab Limit
If you use crosstab reports, you may experience Out of Memory errors if the reports are very large or complex. You can configure JasperReports Server to return a message instead of memory errors when users run such crosstabs. To do so, enable the net.sf.jasperreports.crosstab.bucket.measure.limit property and set its maximum value in the following configuration file:
Crosstab Report Configuration Option |
||
Configuration File |
||
.../WEB-INF/classes/jasperreports.properties |
||
Property |
Description |
|
net.sf.jasperreports. |
This value effectively limits the number of cells in a crosstab, which can be computed as follows: (number of crosstab rows) x (number of crosstab columns) x (number of user-defined measures + 1) The default value is 100000. Enter large values to allow your users to create larger, more complicated crosstabs; enter small values to restrict them. If you experience OutOfMemoryExceptions after changing this value, try setting it to a smaller number, or configure your JVM to allow more memory to be used. |
Setting a Global Chart Theme
Chart themes control the look and feel of the charts generated by JasperReports Server. Chart themes can be applied at the level of either the server or the individual report:
• | To apply a theme at the report level, select it when designing the report in Jaspersoft Studio. Note that you can also apply a theme to individual chart elements. Note that a chart theme can be included in a report unit as a resource. In this case the theme is available only to charts in that report unit. |
• | To apply a theme at the server level, copy the chart theme JAR to the correct location and edit its configuration file. |
A chart theme is a JAR file that defines the look and feel of a chart. Once you have created the chart theme JAR file, copy it to the .../WEB-INF/lib directory. Chart themes in this location are available to any chart in the instance of the server. They can also be set as the global chart theme.
To set a theme as the default chart theme, edit the following configuration file:
Global Report Theme |
||
Configuration File |
||
.../WEB-INF/classes/jasperreports.properties |
||
Property |
Description |
|
net.sf.jasperreports. |
The name of a chart theme that is in the .../WEB-INF/lib directory. |
We recommend that you create your chart themes in Jaspersoft Studio. Click File > New > Other > Chart Theme, then use Jaspersoft Studio to archive the new chart theme as a JAR.
|
Chart themes do not apply to Ad Hoc chart views. |
Disabling Interactivity in the Report Viewer
By default, the report viewer's interactivity is enabled, and reports with interactive elements (such as the table component) are interactive when run in the web server and displayed in the viewer. If you don't want your reports to be interactive, you can disable interactivity across all reports by editing the following configuration file.
Interactivity in the Report Viewer |
||
Configuration File |
||
.../WEB-INF/classes/jasperreports.properties |
||
Property |
Description |
|
net.sf.jasperreports. |
By default, this property is set to true; in this case, interactivity is enabled in the report viewer. Set it to false to disable interactivity. |
|
Changing this setting in this configuration file changes the behavior for the entire server. To configure this behavior at the report, table, or column level, edit the report's JRXML properties in Jaspersoft Studio. |
Disabling Chart Types in Dashboards
By default, interactivity is enabled in charts that appear in dashboards, and users can change the chart type by clicking on the chart type selector (gear icon). If you don't want users to modify the chart types, you can disable the chart type selector on all dashboard charts by editing the following configuration file.
Chart Type Selector in Dashboards |
||
Configuration File |
||
.../WEB-INF/classes/jasperreports.properties |
||
Property |
Description |
|
com.jaspersoft.jasperreports. |
By default, this property is set to true; in this case, chart types can be modified in dashboards. Set it to false to prevent users from changing dashboard charts. |
|
Changing this setting in this configuration file changes the behavior for the entire server. To configure this behavior at the report level, edit the report's JRXML properties in Jaspersoft Studio. |
Changing the Pro Charts Rendering Engine
By default, JasperReports Server renders Pro Charts (those based on Fusion Charts) using HTML5. If your browser doesn't support HTML5, the chart won't be rendered unless you change the configuration. Though we don't recommend it, you can instead have these elements rendered by Adobe Flash; in some circumstances, Fusion's Flash solution may pose a security risk.
Note that Pro Charts are available only in the JasperReports Server Professional edition.
To render Pro Charts using HTML5, edit the following configuration file:
Pro Charts Renderer | ||||||||
Configuration File | ||||||||
.../WEB-INF/classes/jasperreports.properties | ||||||||
Property | Description | |||||||
com.jaspersoft.jasperreports. | Determines which of the following renderers is used:
|
Note that this property applies only to reports that rely on Pro Charts and affects only the HTML preview and export.
Typically, this property is set at the server level; to override the server-level setting for a specific Pro Chart report, set this property at the report level, and also specify a second property as shown:
net.sf.jasperreports.print.transfer.fusion=com.jaspersoft.jasperreports.fusion
This allows the reporting engine, JasperReports Library, to recognize the Fusion settings. If this property isn't set, the com.jaspersoft.jasperreports.fusion.charts.render.type property is ignored at the report level.
Configuring a JavaScript Engine for Graphical Report Rendering
Depending on the circumstances, a given graphical element (such as a chart, a map, or a widget) in a report can be rendered in two ways:
• | When run directly in the web UI, the browser itself renders the chart. |
• | When scheduled to run later or run in the background, an external engine renders the chart. |
JasperReports Server uses the Chromium JavaScript engine to generate graphical reports that are run in the background or scheduled. You can use Chrome, Chromium, or any other browser based on Chromium like Microsoft Edge. For information on the compatible versions of browsers, see the Jaspersoft Platform Support Guide. Download the correct version of Chrome/Chromium for your environment and install it on the computer hosting JasperReports Server.
Once Chrome/Chromium is installed, point JasperReports Server to its location. You can configure several processes to use Chrome/Chromium: HighCharts generation, Pro Charts generation (including Pro Widgets and Pro Maps)
These are server-wide settings. In a given server, all charts of the same type (HighCharts or Fusion (Charts Pro, Maps Pro, or Widgets Pro) use the same JavaScript engine. |
To configure JasperReports Server to use Chrome/Chromium for HighCharts generation,
JavaScript Engine Configuration for HighCharts | |
Configuration File | |
.../WEB-INF/js.config.properties | |
Property | Description |
chrome.path | This property points to the engine the server should use Specify the location for Chrome/Chromium, for example: chrome.path = C:/Program Files (x86)/Google/Chrome/Application/chrome.exe Alternatively, to use another browser, such as Edge, specify the respective path. When you use binary installer to install JasperReports Server, you can give the path to Chrome or Chromium in installer during installation and the path gets automatically set in js.config.properties file. When you use WAR file to install JasperReports Server, this property needs to be set in default_master.properties file. When configured in default_master.properties, it gets automatically set in js.config.properties file on deployment. |
chrome.page.timeout | The maximum number of seconds to wait for output from Chrome\Chromium before the chart times out. The default is 150. |
Configuration File | |
.../WEB-INF/classes/jasperreports.properties | |
Property | Description |
net.sf.jasperreports.chrome.argument.no-sandbox | If Tomcat is run as root on Linux, the export of reports net.sf.jasperreports.chrome.argument.no-sandbox=true By default, this is set to false. |
After setting these properties, restart JasperReports Server to enable them.
If you are using JasperReports Server and Chrome/Chromium on a Windows platform, exporting large Fusion reports may cause issues. In those cases, we recommend editing the property as follows:
|
Static Export Properties for High Charts
When you create interactive JasperReports that use Highcharts, and those reports are exported to HTML, the <script> elements in the HTML must reference the correct JavaScript libraries. The following JasperReports Library properties define the library paths:
Static Export Properties for Highcharts |
Configuration File |
.../WEB-INF/classes/jasperreports.properties |
Property |
# Highcharts static export properties com.jaspersoft.jasperreports.highcharts.render.require.js$context.url com.jaspersoft.jasperreports.highcharts.jquery.js$context.url com.jaspersoft.jasperreports.highcharts.highcharts.js$context.url com.jaspersoft.jasperreports.highcharts.highcharts.more.js$context.url com.jaspersoft.jasperreports.highcharts.highcharts.heatmap.js$context.url com.jaspersoft.jasperreports.highcharts.data.service.js$context.url com.jaspersoft.jasperreports.highcharts.default.service.js$context.url com.jaspersoft.jasperreports.highcharts.item.hyperlink.service.js$context.url com.jaspersoft.jasperreports.highcharts.y.axis.service.js$context.url com.jaspersoft.jasperreports.highcharts.dual.pie.service.js$context.url com.jaspersoft.ji.adhoc.highcharts.setting.service.js$context.url com.jaspersoft.jasperreports.highcharts.highcharts.chart.producer.js$context.url |
Each property that ends in $context.url may also have a similar property ending in $url. The $context.url property is used when a request object is available to resolve a context path for the HTML export, and the $url property is used as a fallback.
Not all library paths are defined in the jasperreports.properties file. Some are provided by the environment (such as com.jaspersoft.jasperreports.highcharts.jquery.ui.js), and others are set programmatically by the bean com.jaspersoft.ji.adhoc.jr.AdhocHighchartsSetting-ServiceBundle (in the .../WEB-INF/applicationContext-adhoc.xml file).
Enabling PDF Accessibility Features in Tables
JasperReports Library supports properties and metadata that allow people to create accessible PDF documents that can be read by screen readers. These properties help meet the requirements specified in the Section 508c of the United States Rehabilitation Act of 1973.
JasperReports Library provides the ability to automatically add 508c metadata to table components. When this features is enabled, tables in
Enabling PDF Accessibility Features in Tables | ||
Configuration File | ||
.../WEB-INF/classes/jasperreports.properties | ||
Property | Description | |
net.sf.jasperreports.components.table. | When set to true, metadata for accessibility is automatically generated in JasperReports tables. |
This property can also be set at the report level or table component level to control the automatically generated metadata.
Enabling HTML in Tooltips
To enable HTML in tooltips, edit the following configuration file:
Enabling HTML in Tooltips | ||
Configuration File | ||
.../WEB-INF/classes/jasperreports.properties | ||
Property | Description | |
com.jaspersoft.jasperreports.fusion.value.encoder=legacy | When set to legacy, HTML is enabled for tooltips in Maps and Charts. Note: When this functionality is enabled, visualizations are vulnerable to security issues, such as HTML injection attacks. |
Recommended Comments
There are no comments to display.