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 to use.

These options can be set at different levels of granularity: Global (applies to all reports generated by the server), Report (defined in the JRXML and applies to a specific report), and Element (defined in the JRXML and applies to specific elements of the report). Global properties are defined in the .../WEB-INF/classes/jasperreports.properties file.

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
Enabling the XHTML or HTML Exporters
Enabling Flash or HTML5 for Pro Charts
Configuring a JavaScript Engine for Graphical Report Rendering

Extending JasperReports Library

You can extendJasperReports Library by implementing the public interfaces it exposes.

Such an implementation is usually stored in a JAR (Java Archive) file that contains a file called jasperreports_extension.properties, specifies a factory class. The specified 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. To do so, edit the following configuration file:

Crosstab Report Configuration Option

Configuration File

.../WEB-INF/classes/jasperreports.properties

Property

Description

net.sf.jasperreports.
crosstab.bucket.
measure.limit

This value represents the maximum number of cells multiplied by the number of measures in the crosstab. 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 iReport Designer. Note that you can also apply a theme to individual chart elements, as well. Note that a chart theme can be included in a report unit as a resource; in this case, the theme is only available 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 may 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.
chart.ChartTheme

The name of a chart theme that is in the .../WEB-INF/lib directory.

Jaspersoft recommends that you create your chart themes in Jaspersoft iReport Designer. Click File>New>Chart Theme, then use Jaspersoft iReport Designer 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

Be default, the report viewer’s interactivity is enabled: reports with interactive elements (such as the table component) are interactive when they are 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 the entire server by editing a configuration file.

Interactivity in the Report Viewer

Configuration File

.../WEB-INF/classes/jasperreports.properties

Property

Description

net.sf.jasperreports.
components.table.interactive

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. You can also configure this behavior at the report, table, or column level by edging the report’s JRXML properties.

Enabling the XHTML or HTML Exporters

By default, JasperReports Server exports HTML format using an HTML-based exporter. Unlike the default exporters from previous versions of the server (html and xhtml), the new HTML exporter (html2) is more forgiving when exporting reports that have overlapping elements while still preventing text from being cut off due to font metrics issues.

This setting affects all cases when HTML is exported, including when reports are exported from the report viewer and when they are scheduled to produce HTML output.

To use an older HTML exporter in JasperReports Server, edit the following configuration file:

HTML Exporters

Configuration File

.../WEB-INF/classes/jasperreports.properties

Property

Description

com.jaspersoft.jasperreports.
export.html.type

Determines which of the HTML exporters is used. Valid values are:

html2 is the default HTML exporter. It handles overlapping report elements more gracefully than the other exporters.
xhtml was the default HTML exporter in versions from 4.5 to 5.0. Jaspersoft continues to support this exporter. It handles overlapping report elements more gracefully that the html exporter. However, it is subject to font metric mismatches between client browsers, which can result in text being cut off.
html was the default HTML exporter in versions of JasperReports Server prior to 4.2. Jaspersoft continues to support this exporter. It doesn’t handle overlapping elements as gracefully as the other exporters.

Note that the properties are mutually exclusive; you can only have one uncommented at a time.

As of JasperReports Server version 5.5, if your reports include interactive elements such as the table component (which supports sorting and filtering in the HTML viewer), you must use the html2 exporter in order to enable the interactive features; the html and xhtml exporters don’t support them.

Enabling Flash or HTML5 for Pro Charts

By default, JasperReports Server renders Pro Charts (those based on Fusion Charts) using Adobe Flash. If Flash isn’t found in the client environment, the server renders the chart using HTML5, instead. For example, Pro Charts displayed on devices that run Apple’s iOS operating system are rendered using HTML5 because Flash isn’t available. Note that not all browsers support HTML5.

Note that Pro Charts are only available in the JasperReports Server professional edition.

You can configure the server to default to HTML5 when rendering Pro Charts. In this case, if your browser doesn’t support HTML5, the chart isn’t rendered.

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.
fusion.charts.render.type

Determines which of the following renderers is used:

flash is the default renderer for Pro Charts. If Flash isn’t available, the server tries to render the chart in HTML5.
html5 is the newest renderer for Pro Charts. Use it if you can’t support Flash.

Note that this property only applies to reports that rely on Pro Charts and only affects 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, you must 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 it is run directly in the web UI, the browser itself renders the chart.
When it is scheduled to run later or runs in the background, an internal engine renders the chart.

By default, JasperReports Server’s internal JavaScript engine is Rhino, which is an excellent solution for most cases; most JasperReports Server users can accept this default. However, under certain circumstances, you may want to use a different engine. Investigate using a different engine if you encounter any of the following when running chart-based reports in the background or when they are scheduled:

Poor performance when generating complex charts or charts that contain large volumes of data.
Out of memory messages.
Incorrect scaling when certain Pro Chart reports are printed.
Results that don’t match those generated when the report is run directly in the web UI. For example, text elements may be incorrectly sized or placed.

In such cases, Jaspersoft recommends that you use PhantomJS as the engine to execute JavaScript when generating graphical reports that are run in the background or are scheduled. PhantomJS is a headless WebKit with JavaScript API. To use PhantomJS, you must download and install the correct version for your environment. Download PhantomJS and install it on the computer hosting JasperReports Server. At a high level, installing PhantomJS includes expanding an archive. For installation instructions, refer to the documentation provided with PhantomJS.

Once PhantomJS is installed, you must point JasperReports Server to its location. You can configure several options independently: HighCharts generation, Pro Charts generation, Pro Widgets generation, and Pro Maps generation.

These are a server-wide settings. In a given server, all charts of the same type (HighCharts or Fusion (Charts Pro, Maps Pro, or Widgets Pro)) must use the same JavaScript engine.

You cannot use PhantomJS to render JFreeCharts. Such reports are always generated by Rhino when run in the background or scheduled.

To configure JasperReports Server to use PhantomJS for HighCharts, edit the following properties:

JavaScript Engine Configuration for HighCharts

Configuration File

.../WEB-INF/classes/jasperreports.properties

Property

Description

com.jaspersoft.jasperreports.
highcharts.phantomjs.
executable.path

This property points to the engine the server should use to generate HighCharts-based charts in reports that are run in the background or have been scheduled.

For example, if you are using Windows and you expanded the PhantomJS 1.8.1 ZIP file into the root of your C: drive:

com.jaspersoft.jasperreports.highcharts.
phantomjs.executable.path=C:\\phantomjs-1.8.1-windows\\phantomjs.exe

com.jaspersoft.jasperreports.
highcharts.phantomjs.
tempdir.path


The temporary directory where PhantomJS stores its output. By default, JasperReports Server expects this output in the location defined by Java’s java.io.tmpdir system property.

com.jaspersoft.jasperreports.
highcharts.phantomjs.
executable.timeout

The maximum number of milliseconds to wait for output from PhantomJS. After that amount of time, the chart times out. The default is 3000.

To configure JasperReports Server to use PhantomJS for Pro Charts (Fusion), edit the following properties:

JavaScript Engine Configuration for Pro Charts (Fusion)

Configuration File

.../WEB-INF/classes/jasperreports.properties

Property

Description

com.jaspersoft.jasperreports.
fusion.phantomjs.
executable.path

This property points to the engine the server should use to generate Pro Charts (based on Fusion) in reports that are run in the background or have been scheduled.

For example, if you are using Windows and you expanded the PhantomJS 1.8.1 ZIP file into the root of your C: drive:

com.jaspersoft.jasperreports.fusion.
phantomjs.executable.path=C:\\phantomjs-1.8.1-windows\\phantomjs.exe

com.jaspersoft.jasperreports.
fusion.phantomjs.
tempdir.path


The temporary directory where PhantomJS stores its output. By default, JasperReports Server expects this output in the location defined by Java’s java.io.tmpdir system property.

com.jaspersoft.jasperreports.
fusion.phantomjs.
executable.timeout


The maximum number of milliseconds to wait for output from PhantomJS. After that amount of time, the chart times out. The default is 3000.

By default, when Fusion-based reports are viewed in the web UI, they are generated as Flash elements. You can configure the web UI to generate your reports using HTML5 instead. For details, see Enabling Flash or HTML5 for Pro Charts.

Version: 
Feedback