Using the report components

Currently there are only two kind of components available for report rendering:

  • An inline frame component that can be embbeded in any page.
  • A link that when clicked navigates to a full page with the report rendered.

    Note: An additional report component exists just for allowing nested reports.

Report Frames (inline reports)

An inline report is rendered using the jr:reportFrame tag. When this component is used, an iframe HTML element will be rendered, so many of the attributes available for the iframe tag are also available with this component.

Report Links

An inline report is rendered using the jr:reportLink tag. When this component is used, an a HTML element will be rendered, every attribute available for the a tag is also available with this component.

Common Usage

There are some attributes you must specify when using any of the report components. This attributes are shown in the following table:

formattrueOutput format for this report instance.
nametrueName of the generated report, very useful when working with report links or subreports.
sourcetrueReport Source reference id (See Report Source documentation) or any supported source object.
valuetrueA pointer to the report instance, it can be a path name to a .jasper file, a JasperReport object, etc.


As it is said in the previous table, the common usage uses resources stored inside the application context but the plugin has its own resource loading mechanism. Advanced users can use the service provider interfaces to extend functionality to the plugin.

Report resources can be loaded from the classpath, from the web application context, from an external URL or relative to the current request. Following there are some examples:

Classpath Resources

When loading classpath resources we need to use the prefix classpath: in the value attribute:

<jr:reportFrame value="classpath:reports/orders.jasper">

Note: Since 1.0-RC version classpath resources can be specified also without the classpath: prefix. This is done in order to address some issues found when those resources are looked up from inside the JasperReports engine. However, the prefered way to specify this kind of resources is still prepending the classpath: prefix.

External URL Resources

When loading resources from an URL simply use any normal URL as the value of the value attribute:

<jr:reportFrame value="">
Context-relative Resources

Context-relative resources are the default way of loading reports. When loading this kind of resources just use an absolute path to the given resource. This path will be resolved inside the application context.

<jr:reportFrame value="/reports/orders.jasper">
Request-relative Resources

Request-relative resources are a special kind of resources that are resolved locally against current request. When using this kind of resources.

Request-relative resource locally to view id

<jr:source value="orders.xls" />


<jr:reportLink value="orders.jasper" />

Report Parameters

Report parameters are specified using the JSF f:param tag nested inside the report component tag that you are using.

<jr:reportFrame value="/reports/orders.jasper">
    <f:param name="CITY" value="Melbourne" />

Output Formats

JasperReports JSF-Plugin allows rendering reports using different output formats by means of the format attribute. The plugin has its own built-in mechanism to be aware of different exporters bundled inside the official distribution. Advanced users can also provide its own supported output formats, take a look to this link to get more information about that.

Apart from that, each of the output formats can be customized providing some component attributes using the f:attribute tag nested inside the report component that you are using.

<jr:reportFrame value="..." format="csv">
    <f:attribute name="FIELD_DELIMITER" value=":" />

Following there is a list of the current supported output formats

format valueMime TypeDescription
docxapplication/vnd.openxmlformats-officedocument.wordprocessingml.documentExports to a Office 2007 Word document
pdfapplication/pdfExports to a PDF document
csvtext/plainExports to a CSV text file
htmltext/htmlExports to a HTML document
jexcelapplication/ to a MSExcel file using JExcel API
rtfapplication/rtfExports to a RTF document
texttext/plainExports to a plain text file
xlsapplication/ to a MSExcel file using POI API
xmltext/xmlExports to a XML document

Take a look to the Javadocs to get specific information about each exporter and its specific attributes.

Implicit objects

When report instances are filled with data some implicit objects are provided to the JasperReports engine and thus, they can be used by report code to access contextualised information from the web application that is rendering the report.

The set of implicit objects and its names are showed in following table:

Parameter nameTypeDescription
REPORT_CLASS_LOADERjava.lang.ClassLoaderCurrent context class loader.
REPORT_LOCALEjava.util.LocaleCurrent view locale.
APPLICATION_SCOPEjava.util.MapServlet/Portlet application scope map.
SESSION_SCOPEjava.util.MapSession scope map.
REQUEST_SCOPEjava.util.MapRequest scope map.


It's very common working with reports which contain other mini-reports inside as a master-detail view. JasperReports JSF Plugin provides with a subreport component that can be used to insert data into the detail report inside a master one.

This component should be used this way:

<jr:reportFrame value="...">
    <f:param name="ORDER_ID" value="..." />
    <jr:subreport name="orderLines" value="...">
        <f:param name="FROM_DATE" value="..." />
        <f:param name="TO_DATE" value="..." />

Subreport attributes

namefalseA subreport should always have a name attribute, it will be used to nest parameter names passed into it.
sourcetrueReport Source reference id (See Report Source documentation), or a any supported source object.
valuetrueA pointer to the report instance, it can be a path name to a .jasper file, a JasperReport object, etc.

Note: A subreport can not specify an export format since it will use the same export format than the parent report it belongs to. However, it may use a different report source than the parent and it can also have its own parameters.