Skip to main content
Pentaho Documentation

Create Report Design Wizard templates

Parent aricle

Once you have created a report that meets your requirements, you can save the report format as a template for future use.

Report Design Wizard template design guidelines

To create a new Report Design Wizard (RDW) template, you must use Report Designer to create a report with certain template-specific properties enabled. The resultant Pentaho Report Template file .prpt file is then deployed to the Report Designer or Pentaho Data Integration template directory.

Requirements

The generated-content-marker attribute in the wizard group is the flag that turns a normal report into a template. This attribute can only be applied to a band (group header, group footer, details header, details footer, details, or sub-band).

RDW will insert its auto-generated content into the first band with the generated-content-marker set to true. This applies to the group header, group footer, details header, details footer, and the details bands. In the event there are more groups defined in the Report Design Wizard than defined in the template, it repeats the last defined group header and footer in the template.

Formatting inheritance

Formatting styles are inherited, so any formatting applied to a band will also be applied to the elements used within it.

Formatting is applied in three ways and in the following order:

  1. Through the template via band inheritance
  2. Through query data where it is defined in Pentaho Metadata Editor
  3. 1.2.3.As defined by RDW users through the RDW interface

Inheriting styles from the data query

The query-metadata section of the Attributes tab contains options that determine whether formatting styles can come from the data query and be applied to the detail header, details, or detail footer band. This must be set directly on the detail header, detail footer, or details band; and the style-format option must be set to true for it to work. You must also disable any individual formatting styles (enable-style-*=true) that you don’t want to come from the query.

Padding and grid lines

Since the Details band is dynamically generated, you have to specify grid line and padding settings in the template definition. This is done through the wizard attribute group for the band that has the generated-content-marker enabled.

Updating

An RDW template is only a set of initial defaults for a report, so if a template is updated, completed reports that were based on that template will not be affected; there is no connection between the template and the report once the report is saved. If you want to update an RDW-based report to reflect template changes, you can edit the report with Report Design Wizard, make any necessary selections, and re-save it.

NotePentaho Interactive Reports templates have the opposite behavior because the report links itself to the template; when an Interactive Reports template is changed, all reports based on that template will automatically inherit the updated template.

Interactive Reports template design guidelines

Interactive Reports are saved as .prpti files. Report Designer report files have a .prpt extension. In the User Console, Interactive Reports are displayed with a special icon that differentiates them from reports that are created in Report Designer.

If you want to create a new Interactive Reports template, you must create it in Report Designer and place the template in the Interactive Reports templates directory.

For more information about enhancing Interactive Reports and building Interactive Reports templates in Report Designer, refer to the section Design Print-Quality Reports.

To create a new Interactive Reports template, you must use Report Designer to create a report with certain template-specific properties enabled. The resultant PRPT file is then deployed to the Interactive Reports plugin's template directory.

Requirements

The generated-content-marker attribute in the wizard group is the flag that turns a normal report into a template. This attribute can only be applied to a band (group header, group footer, details header, details footer, details, or sub-band).

RDW will insert its auto-generated content into the first band with the generated-content-marker set to true. This applies to the group header, group footer, details header, details footer, and the details bands. In the event there are more groups defined in the Report Design Wizard than defined in the template, it repeats the last defined group header and footer in the template.

Formatting inheritance

Formatting styles are inherited, so any formatting applied to a band will also be applied to the elements used within it. Formatting is applied in three ways and in the following order:

Procedure

  1. Through the template via band inheritance

  2. Through query data where it is defined in Pentaho Metadata Editor

  3. As defined by Interactive Reports users through the Interactive Reports interface

Inheriting styles from the data query

The query-metadata section of the Attributes tab contains options that determine whether formatting styles can come from the data query and be applied to the detail header, details, or detail footer band. This must be set directly on the detail header, detail footer, or details band; and the style-format option must be set to true for it to work. You must also disable any individual formatting styles (enable-style-*=true) that you don’t want to come from the query.

Padding and grid lines

Since the Details band is dynamically generated, you have to specify grid line and padding settings in the template definition. This is done through the wizard attribute group for the band that has the generated-content-marker enabled.

Updating

A template is not just a set of initial defaults for a report - it is the basis for that report. So if a template is updated, completed reports that were based on that template will also change.

NoteNote: Report Design Wizard templates have the opposite behavior; when an RDW template is changed, none of the reports based on that template will be automatically be updated with those changes. Instead, you will have to edit each report, apply the new template, and save it.

Dynamic element positioning in templates

Use the following methods to accommodate for multiple page sizes in reports:

Percentages

Express the height, width, x position, and y position in percentages.

Block, inline, or row

Switch the band’s layout mode from canvas to either block, inline or row:

layout-modevalue
CanvasUses the x and y position to place the element in the band.
BlockStacks elements vertically according to the layer order in a band; width is set to 100%.
InlineStacks elements horizontally according to the layer order in a band; width is determined by the length of the text in the field, and wraps within the band.
RowStacks elements horizontally in one row according to the layer order in the band.

Dynamic height message elements

Set dynamic-height=true on message elements. This will allow the element size to grow according to line height. Also, setting the following Reporting engine configuration option will allow the element size to grow according to the font size used:

org.pentaho.reporting.engine.classic.core.layout.​fontrenderer.UseMaxCharBounds = true

Proportional column widths

To support varying window sizes in a Web browser, enable the use of proportional column widths so that the resulting table will have a width of 100% and the columns will have the proportional equivalent of their static widths as width. The relevant Reporting engine option to set this globally is:

org.pentaho.reporting.engine.classic.core.modules.​output.table.html.ProportionalColumnWidths = true

Template properties

The following band properties affect RDW and Interactive Reports report templates. Notice that many properties have a different effect in RDW than in Interactive Reports.

BandReport Design WizardInteractive Reporting
page headerNoneEdit message elements
report headerNoneEdit message elements
group headersInserts a message element with the value of: fieldname: $(fieldname)Edits any message elements within the band. Inserts a message element with the value of: fieldname: $(fieldname)
detail header
  1. Inserts a column header label for every field used. Default value for the label is the fieldname.
  2. Edits any label within the band.
  1. Inserts a column header label for every field used. Default value for the label is the fieldname.
  2. Edits any label within the band.
detailsInserts the appropriate fields definedInserts the appropriate fields defined
detail footerInsert a numeric field in the same x-position and width of the details field that the summary calculation is applied.None
group footerNone
  1. Inserts a numeric field in the same x-position and width of the details field that the summary calculation is applied.
  2. Inserts a message element in the x-position of the details field with no summary calculations applied.
report footerNone
  1. Inserts a numeric field in the same x-position and width of the details field that the summary calculation is applied.
  2. Inserts a message element in the x-position of the details field with no summary calculations applied.
  3. Edit any message elements within the band
page headerNoneAllows the modification of message elements

Deploy a template to Report Design Wizard

Once you have created a template for the Report Design Wizard, you must follow the below process to deploy it to the Report Design Wizard in Pentaho Report Designer (PRD) and Pentaho Data Integration (PDI).

Procedure

  1. Shut down Pentaho Report Designer and Pentaho Data Integration if either one of them is currently running.

  2. Create an icon for your template, in PNG format, with the same name as the template file.

    The size of the icon does not matter since the PRD Wizard will scale it to fit the correct dimensions. However, you can avoid unusual scaling issues by creating a square-shaped (equal width and height) graphic. If you would like further guidance, take a look at the default template icons that Pentaho provides in the templates directory.
  3. Copy the icon and the .prpt template files to the following directories:

    • design-tools/report-designer/templates
    • design-tools/data-integration/plugins/spoon/agile-bi/templates

Results

Your template is now deployed to the Report Design Wizard and will be available when you next start Pentaho Report Designer or Pentaho Data Integration.

Deploy a template to Interactive Reports

Once you've created a template for Interactive Reports, you must follow the below process to deploy it to the Interactive Reports plugin.

Procedure

  1. Shut down the Pentaho Server if it is currently running.

  2. Create an icon for your template, in PNG format, with the same name as the template file.

    The size of the icon doesn't matter; Interactive Reports will scale it to fit the correct dimensions. However, you can avoid unusual scaling issues by creating a square-shaped (equal width and height) graphic. If you'd like further guidance, take a look at the default template icons that Pentaho provides in the templates directory.
  3. Copy the icon and the PRPT template files to the /pentaho-solutions/system/pentaho-interactive-reporting/resources/templates/ directory.

  4. Edit the /pentaho-solutions/system/pentaho-interactive-reporting/resources/messages/messages.properties file and add a new line for your template with the template_ prefix, the name of your template file, and a friendly name for the template as you'd like it to appear in the Interactive Reports interface.

    As in the following example (given a template filename of template_demo.prpt):
    template_template_demo=Template Demo

Results

Your template is now deployed to Pentaho Interactive Reports.

Set the default Interactive Reports template

To change the default template for Interactive Reports, edit the /pentaho-solutions/system/pentaho-interactive-reporting/settings.xml file and change the value of the <default-template> node. You do not have to provide a path to the template PRPT file - just the filename.

<!-- default template -->
<default-template>1_jade_1_left_aligned.prpt</default-template>