net.sf.jasperreports.engine

Interface JRTemplate

All Superinterfaces:

JRDefaultStyleProvider

All Known Implementing Classes:

JRSimpleTemplate

public interface JRTemplate
extends JRDefaultStyleProvider

A template that can be used by report.

Templates contain report styles that can be used by reports once the template is included in the report. This allows styles to be externalized and reused across several reports.

A template can in its turn include other templates, see getIncludedTemplates().

Style Templates

Report styles can also be defined in external style template files that are referenced by report templates. This allows report designers to define in a single place a common look for a set of reports.

A style template is an XML file that contains one or more style definitions. A template can include references to other style template files, hence one can organize a style library as a hierarchical set of style template files.

Style template files use by convention the *.jrtx extension, but this is not mandatory.

The <jasperTemplate> element is the root of a style template file. The <template> element is used to include references to other template files; the contents of this element is interpreted as the location of the referred template file.

The <style> element is identical to the element with the same name from report design templates (JRXML files), with the exception that a style in a style template cannot contain conditional styles. This limitation is caused by the fact that conditional styles involve report expressions, and expressions can only be interpreted in the context of a single report definition. Each style must specify a name, and the style names have to be unique inside a style template.

A report can use style templates by explicitly referring them in its definition. References to a style templates are included in JRXML reports as <template> elements. Such an element contains an expression that is resolved at fill time to a style template instance.

The template expression can only use constants/literals and report parameters. Variables and fields cannot be used because the template expressions are evaluated before the report calculation engine is initialized. If the template expression evaluates to null, the engine ignores the template reference.

Style template locations are interpreted in the same manner as image or subreport locations, that is, the engine attempts to load the location as an URL, a disk file or a classpath resource.

Styles from included template files can be used in the report just as local styles, that is, they can be referred by report elements or used as base styles for other (derived) styles. The style templates are loaded at report fill time, and style name references are resolved once all the templates have been loaded. If a style name reference cannot be resolved, that is, no style can be found in the loaded templates for a style name used in the report, the fill process will fail with an exception that specifies which style could not be resolved.

When loading style templates and resolving style names to styles, a tree/graph of style templates is created, the top of the tree being the set of styles defined in the report. On this tree, style name references are resolved to the last style that matches the name in a depth-first traversal. For instance, if a report contains a style named Normal and the report also includes a style template that contains a style named Normal, an element referring the Normal style would use the style defined in the report. The same principle applies to the way the default style is determined: the last style which is marked as default is used as report default style.

The following example illustrates how style templates can be referenced in a JRXML report definition:

 <jasperReport ...>
   <template>"report_styles.jrtx"</template>
   <!-- parameters can be used in style template expressions -->
   <template>$P{BaseTemplateLocation} + "report_styles.jrtx"</template>
   <template class="java.net.URL">$P{StyleTemplateURL}</template>
   <parameter name="BaseTemplateLocation"/>
   <parameter name="StyleTemplateURL" class="java.net.URL"/>
   ...
 

At the API level, style templates are represented by JRTemplate instances. A reference to a style template in a report is represented by a JRReportTemplate instance. Such references can be added to a JasperDesign object via the addTemplate(JRReportTemplate) method, and the list of template references can be obtained by calling the getTemplates() method.

In more complex cases, style templates can be injected into a report by using the built-in REPORT_TEMPLATES report parameter. This parameter expects as value a collection (as in java.util.Collection) of JRTemplate instances. The user report fill code can either load style templates on its own from template XML files using JRXmlTemplateLoader, or instantiate style template objects by any other means, and pass the dynamically loaded style template list to the report fill process using the REPORT_TEMPLATES parameter.

Style templates passed to a report via the REPORT_TEMPLATES parameter are placed after the templates referenced in the report definition, hence styles from the parameter templates override styles with identical names from the statically referenced templates.

Author:

Lucian Chirita (lucianc@users.sourceforge.net)

See Also:

JRReport.getTemplates(), JRParameter.REPORT_TEMPLATES, JRStyleContainer.getStyleNameReference()

Method Summary

Methods

Modifier and Type	Method and Description
JRTemplateReference[]	getIncludedTemplates() Returns the templates included/referenced by this template.
JRStyle[]	getStyles() Returns the styles defined in this template.

Methods inherited from interface net.sf.jasperreports.engine.JRDefaultStyleProvider

getDefaultStyle

Method Detail

getIncludedTemplates

JRTemplateReference[] getIncludedTemplates()

Returns the templates included/referenced by this template.

Returns:

the included templates

getStyles

JRStyle[] getStyles()

Returns the styles defined in this template.

Returns:

the template styles