Styles, Templates & Markup

A style is a <style> element with a unique name and any of the formatting attributes. Elements refer to it with their style attribute and inherit every attribute that applies to their kind (a text field uses the font and the alignment, a rectangle only the colours and the pen). Attributes written on the element override the style. A style can name a parent with its own style attribute, and one style of the report can be marked default="true": it applies to every element that has no style of its own, and it is the root of the inheritance chain of the other styles (the property net.sf.jasperreports.styles.inherit.from.default is true in the default configuration of 7.0.8).

The attributes that a 7.0.8 <style> accepts are listed below. The list is what the Jackson loader reports for the style class, so it is the authority for 7.0 files, whatever the older documentation says.

The books of the corpus describe styling with the mechanisms of their day, and several of them do not load any more (finding O18). B2 (JasperReports 1.x/2.x) and B3 (the Ultimate Guide) use a report-wide reportFont element, boolean attributes with the is prefix, the pdfFontName, pdfEncoding and isPdfEmbedded triple as the way to reach a PDF font, the Acrobat Asian font packs, and border and leftBorder attributes on elements. Nothing from those books is reproduced here, and these are the results for 7.0.8, each checked by compiling a one-line report:

A v6 JRXML (and a v6 .jrtx, see below) is not a 7.0 file, so the whole file needs converting with Jaspersoft Studio 7, as explained on the JRXML design page.

The example is one report with a style template. The template holds the house look, and the report adds the pieces that depend on its own data. All three files are the ones that were run.

The style template, src/main/resources/reports/styles.jrtx, defines a default style, a table heading, a table cell whose text turns red and bold when the row is low on stock, and a money cell:

The report, src/main/resources/reports/styles-demo.jrxml, loads the template, adds the zebra stripes as a conditional style (they use a report variable, which a template cannot), picks the category style with an expression, and shows HTML, styled text and a paragraph definition in the title:

The row class is a plain JavaBean (a Java record is not accepted by the bean data source, see the JRXML page):

And the driver compiles the report, fills it with a fixed locale so that the number pattern prints the same everywhere, and writes the PDF:

The dependencies are the four JasperReports artifacts of this section at 7.0.8 (net.sf.jasperreports:jasperreports, jasperreports-pdf, jasperreports-fonts and jasperreports-jdt, all with the same version), declared as in the JRXML design page.

Running it prints styles-demo.pdf: 1 page(s). Reading the PDF back gave the title line, the two lines of markup text, the heading row and the five books with their prices as 9.90, 14.50, 7.25, 11.00 and 13.75; rendered to an image, the heading is white on blue, Cosmos and Ulysses are bold red, the even rows (Cosmos, The Selfish Gene) have the pale blue background and the two Science cells are highlighted in pale yellow. The sections that follow take the file apart. The example derives from the JasperReports templates sample and the markup sample.

In the template, Heading, Cell and Money declare style="Base" or style="Cell" and only add what differs, so the font is written once, in Base. Base is also default="true", which is why the title, written without any style, comes out in DejaVu Sans 9 pt dark grey, and why fontSize="16.0" and bold="true" on the title text are the only things it needs to say. A change of corporate colour or typeface is then one edit in styles.jrtx.

Three precedence rules explain the output. An attribute on the element beats the style: the Stock cells use Zebra and override hTextAlign to Right. A style beats its parent: Money sets an alignment that Cell does not have. And a conditional style beats the style it belongs to while its condition is true, which is the next section. The API of the resolved result is JRStyle; the loader class of a design style is JRDesignStyle.

A <conditionalStyle> inside a style holds a <conditionExpression> and the attributes that apply while it evaluates to true. In 7.0 the attributes are written on the <conditionalStyle> element itself, as the example shows (<conditionalStyle forecolor="#B00020" bold="true">), and the same child elements as a style (<box>, <pen>, <paragraph>) are allowed.

Alternate row colours need a conditional style and a counter that says which row this is. The built-in variables for that are $V{REPORT_COUNT} when the alternation runs through the whole report, $V{PAGE_COUNT} when every page should start with the same colour, $V{COLUMN_COUNT} for multi-column pages, and a group’s own counter such as $V{CategoryGroup_COUNT} when each group should start the same way. The Zebra style of the example is exactly the pattern of the official sample:

Derived from the alternate row colours section of the scriptlet sample.

The style that stripes a cell has to be applied to every cell of the row (the example uses Zebra or ZebraMoney on all four), otherwise the stripe has holes.

Since JasperReports 6.20.6 (the release notes of that version describe it as an optional style expression added to report elements in addition to the static style reference) an element can compute its style name at fill time, with a <styleExpression> child. The result is the name of a style of the report. The example uses it for the category cell:

It is the right tool when the choice is among several whole styles (a different style per status, per customer tier or per parameter), where a conditional style only switches properties of one style on and off. Three results from 7.0.8 are worth knowing, all observed:

For delayed evaluation of styles the configuration reference has the property net.sf.jasperreports.style.evaluation.time.enabled, which is false by default in 7.0.8; it was not tested for this page.

When several reports must look alike, the styles live in one external file, by convention with the .jrtx extension. In 7.0 it is an XML file whose root is <jasperTemplate>, without a namespace or a DOCTYPE, as for JRXML. It contains <style> elements with the same attributes as in a report, and optionally <template> elements that include other template files, so a library of styles can be layered. The file of the example is the whole format; a layered one looks like:

The nested form was checked: a style in the second file inherited the colour of its parent from the first. Derived from the templates sample.

A report loads a template with a <template> element, whose content is an expression evaluated at fill time:

Only literals and parameters can appear in that expression (fields and variables do not exist yet when templates are loaded), and a null result makes the engine skip the template. The location is resolved like the location of an image or a subreport: a URL, a file or a classpath resource, and the class attribute can be java.lang.String, java.io.File, java.net.URL, java.io.InputStream or net.sf.jasperreports.engine.JRTemplate. The example loads it from the classpath. A location that cannot be found fails the fill with "Byte data not found at: nope.jrtx" (observed).

Three practical points. The styles of a template are available to the report by name, as parents and as style values, but see the previous section for style expressions. Keep style names unique across the template library and the report. And a v6 .jrtx is, like a v6 JRXML, not a v7 file: the v7 Jackson-based format applies to both, and no template conversion was run for this page, so open and save the old ones in Jaspersoft Studio 7 and diff the result. The loader class is JRXmlTemplateLoader.

Everything above formats a whole element. To format part of a text (one bold word, a red warning, a superscript) the element declares a markup language, on the element or on a style: none (the default, plain text), styled, html or rtf. It works on static texts and, more usefully, on text fields, whose expression result is then parsed as markup.

Styled text is the JasperReports own XML dialect: the content is a fragment in which <style> tags change the font, colours and decorations of a portion, with the simple tags <b>, <i>, <u>, <font>, <sup>, <sub>, <li> and <br> and the hyperlink <a>. The tags inside the text still use the old is attribute names, for example <style isBold="true" forecolor="#1F5FA6"> (this is the one place where isBold is correct in 7.0; the example shows it). Nested <style> tags inherit from the enclosing one. HTML markup accepts the usual inline tags and is interpreted by the Swing HTML editor kit. RTF is read with the Swing RTF editor kit. Both are converted to styled text internally: a short RTF string with a bold and an italic run came out as styled text with isBold="true" and isItalic="true" runs (checked). The element of the example for HTML is:

For a text field the same attribute is set and the expression returns the markup string, as in the markup sample (<element kind="textField" markup="html"> with $P{HtmlText}). Derived from the markup and styled text samples.

Two cautions, both observed in 7.0.8. First, the data that reaches a markup field is parsed, so a title or a comment typed by a user must be escaped before it is used there: with markup="styled" the text a < b & c made the parser log a SEVERE "Error parsing styled text" and the engine fell back to showing the raw text, and with markup="html" the same text lost the < and printed a b & c; with markup="none" the text is printed exactly as written, so leave the markup off for anything that is not meant to carry it. Second, an unknown value such as markup="bogus" fails the fill with "No markup processor factory specified". The older boolean isStyledText no longer loads.

The <paragraph> element, available on text elements and styles, controls how a block of text flows. Its attributes are the line spacing (lineSpacing: Single, 1_1_2, Double, AtLeast, Fixed or Proportional, with lineSpacingSize for the last three), the indents (firstLineIndent, leftIndent, rightIndent), the vertical space (spacingBefore, spacingAfter) and the tabs (tabStopWidth for the regular tab width, or <tabStop position="..." alignment="..."> children with Left, Center or Right alignment). Horizontal and vertical alignment are not part of the paragraph: they are the hTextAlign and vTextAlign attributes of the element or the style (the Justified value is accepted by hTextAlign). The styled-text element of the example uses most of them:

In the rendering, the first line is indented and the text after the tab character ends at the right tab stop. The tab in the example is a literal tab inside the CDATA. Defaults for all reports of a context are set with properties such as net.sf.jasperreports.default.first.line.indent and net.sf.jasperreports.default.tab.stop.width (default 40), listed in the paragraph sample; those properties are covered with the other configuration on Scriptlets, Properties & Extensions. Derived from the paragraphs sample. One discrepancy: the templates sample still lists lineSpacing among the attributes of a style, but the 7.0.8 loader has it only on the paragraph, so write it there.

The old border attributes became children. A <box> holds the padding (or topPadding, leftPadding, bottomPadding, rightPadding) and the borders; each side has its own pen (<topPen>, <leftPen>, <bottomPen>, <rightPen>) and a bare <pen> inside the box sets all four. A pen has lineWidth, lineStyle and lineColor. Graphic elements (lines, rectangles, ellipses) use a direct <pen> child. The Cell style of the example draws a hairline under every row with a bottom pen, and Heading has padding only:

A frame with a full border was shown in the JRXML design page. Because they are children of a style, boxes and pens are inherited like other attributes, and a <conditionalStyle> can switch them (for instance a red border for a failed check).