PythonReports Templates

Version: 0.6.1
Date: 16-nov-2012

Introduction

Report definitions for PythonReports (report templates) are used to control database report layouts. Report builder applies a template to a sequence of report data objects and produces a printout file that can be rendered by one of the front-end drivers to screen, printer, HTML, PDF etc.

Report templates are files in XML format. By convention, these files use extension .PRT.

This document describes the structure of the template files.

Let's start with some terminology:

The root of the template structure is report element. It must contain exactly one layout element and may contain and arbitrary number of font, parameter, variable and data elements.

The layout element contains one group or detail element and may contain a sequence of style elements and possible columns, header, footer, title and summary elements.

The columns element may contain a sequence of style elements and possible header and footer elements.

The group element contains one group or detail element and may contain a sequence of style elements and possible columns, title and summary elements.

Report template may contain only one detail section (innermost in the layout/group hierarchy).

All section elements may contain one box element, a sequence of eject variants and style definitions and any body elements. The order of body elements is important: elements appearing later in the template sequence are laid out on top of previous elements.

All section elements may contain arbitrary number of subreport elements.

All body elements must contain one box element and may contain a sequence of style elements.

In each sequence of the style and eject specifications only one will apply: when expressions are evaluated in order of the element appearance in the report template, and the first match will stop the search.

Styles are inherited; when body elements do not have an applicable style, style search continues up the template hierarchy: containing parent section first, then all containing group elements, and finally the layout element. Styles set in columns are checked immediately before the styles of parent group or layout element.

Types of element attributes

This section explains special attribute types used in element descriptions.

Booleans

Values true, yes and 1 stand for boolean true, values false, no and 0 stand for boolean false. Recommended form is true and false.

Colors

Color values may be specified in one of the following forms:

  • 6-digit hexadecimal number prefixed by a hash mark (HTML format),
  • color name from the following dictionary (case insensitive),
  • three integer values: red, green, blue (0..255),
  • three float values: red, green, blue (0..1),
  • single integer value, where
    • the red component is in bits 16-23,
    • the green component is in bits 8-15,
    • the blue component is in bits 0-7.

Recommended form is the first one.

Standard color names:

Name Value Name Value
BLACK #000000 YELLOW #FFFF00
SILVER #C0C0C0 NAVY #000080
GRAY #808080 BLUE #0000FF
WHITE #FFFFFF TEAL #008080
MAROON #800000 AQUA #00FFFF
RED #FF0000 CYAN #00FFFF
PURPLE #800080 DARKGRAY #404040
FUCHSIA #FF00FF LIGHTGRAY #C0C0C0
GREEN #008000 MAGENTA #FF00FF
LIME #00FF00 ORANGE #FFC800
OLIVE #808000 PINK #FFAFAF

Dimensions

All report dimensions (page and field sizes, margins etc.) are expressed as integer or floating point numbers with optional suffix:

  • mm - millimeters,
  • cm - centimeters,
  • in - inches,
  • pt - points (1/72 inch).

If suffix is omitted, dimension is in points.

It is recommended to always use integral points for all dimensions to avoid rounding errors.

The origin of the coordinate system (0,0) is always in the left upper corner of a container (page or section).

Expressions

All expressions are evaluated in the context of current result set row, i.e. result set fields may be referred directly as python variables. In addition, expressions can use names defined by import, parameter and variable elements and the following predefined variables:

Name Meaning
THIS Current row object from report data.
ITEM_NUMBER Zero-based index of current row object in report data sequence. May differ from REPORT_COUNT if some detail sections are suppressed by printwhen.
DATA_COUNT Total length of the report data sequence.
REPORT_COUNT Number of detail sections from start of the report.
PAGE_COUNT Number of detail sections from start of the page.
COLUMN_COUNT Number of detail sections from start of the column.
group _COUNT Number of detail sections from start of named group.
PAGE_NUMBER Current page number.
COLUMN_NUMBER Current column number.

Evaluation context performs name lookup in the following order:

  1. Predefined variables.
  2. Names created by import elements.
  3. parameter names.
  4. variable names.
  5. Items of the row object (dictionary-like).
  6. Attributes of the row object (structure-like).

Template elements

This chapter contains informal descriptions of the template elements.

In element attribute tables, the second column (Req) shows whether the attribute is required: M for mandatory attributes, O for optional ones.

All elements and attributes not mentioned here are ignored by PythonReports. Element contents (text) are ignored except for the data elements.

report

The root element of template. Contains a sequence of parameter, variable, import and font elements and exactly one layout element.

Attributes:

Name Req Type Description
name O string Report name.
description O string Description of the report.
version O string Report version.
author O string Author name.
basedir O string Base directory for image file paths. Default: directory containing template file.

parameter

This element sets parameter values for report generation.

Attributes:

Name Req Type Description
name M string Variable name.
default M expr Default value.
prompt O boolean If set to yes, report builder will prompt for parameter value. If value is no, report builder will use default value.

variable

Report variable. Used to run counters, sums and such.

Attributes:

Name Req Type Description
name M string Variable name.
expr M expr Expression used to compute value.
init O expr Initial value for calculations.
calc O string Calculation function. See calculation types below. Default: first.
iter O string How often the expression is evaluated: report, page, column, group or detail. [1] Default: detail.
itergrp [2] string Group name for iter="group".
reset O string How often the expression is reset to initial value: report, page, column, group or detail. [1] Default: report.
resetgrp [3] string Group name for reset="group".
[1](1, 2) The expression is always evaluated at the end of report group referred by this attribute.
[2]Required when iter is group, otherwise ignored.
[3]Required when reset is group, otherwise ignored.

Calculation types:

Name Meaning
count Count distinct values. Hint: for iteration counter, use sum with expression="1" or one of the predefined variables.
list A list containing all values.
set A set containing distinct values.
chain Similar to itertools.chain, a list composed of elements of sequences produced by expr. [5] The expr must evaluate to an iterable or None.
sum Sum of all values.
avg Average value. [4]
min Lowest value.
max Highest value.
std Standard deviation. [4]
var Variance from the average. [4]
first Keeps the first value calculated after reset.
[4](1, 2, 3) The expression must be compatible with float type.
[5]Note: this is a shortcut. Same result would be produced by init="[]" calc="sum" and expr evaluating to list.

import

Import a symbol from Python module.

Attributes:

Name Req Type Description
path M string A dot-delimited path in python package namespace. The last component of the path will be available for use in expressions. E.g. <import path="a.b.c.d" /> has the same effect as Python statement from a.b.c import d.
alias O string Alternate local name for imported symbol. E.g. <import path="a" alias="b" /> has the same effect as Python statement import a as b.

font

Font definition for use in text fields and as a default font in sections and whole report.

Attributes:

Name Req Type Description
name M string Local name of font definition. Used as font reference in field elements.
typeface M string Typeface name.
size M integer Font size in points.
bold O boolean True for bold fonts.
italic O boolean True for italic fonts.
underline O boolean True for underlined text.

data

Contains arbitrary data for use in field, image and barcode elements.

This is the only element in PythonReports templates that has significant body text; for all other elements body text is ignored.

Attributes:

Name Req Type Description
name [6] string Data reference needed to use the data in elements other than immediate parent element.
pickle O boolean if set to True, data is pickled Python object.
compress O string zlib or bz2.
encoding O string base64, uu or qp.
[6]Optional when immediate parent element is field, image or barcode; required otherwise.

style

The style elements may be contained in all section elements and body elements. Style attributes printwhen, font, color and bgcolor propagate to inner elements, i.e. if an element does not have these attributes in the applicable style, they are searched up the layout hierarchy.

Attributes:

Name Req Type Description
when O expr When this style is applicable. The styles are checked in order of their appearance in the template. Style search stops when this expression evaluates to boolean True. Default: True.
printwhen O expr If False, this element is suppressed.
font O string Name of font definition.
color O color Foreground or pen color.
bgcolor O color Background or fill color.

box

Defines rectangular space occupied by report elements.

Attributes:

Name Req Type Description
x O dimension Horizontal position. Negative values are offset from the right margin. [7]
y O dimension Vertical position. Negative values are relative to the bottom of section. [7]
float O boolean If True, y position (must be positive) is adjusted according to heights of elements laid out higher in the same section. Ignored for negative y values.
width O dimension Element width. Negative values are offset from the right margin. [8] Default: -1.
height O dimension Element height. [9] Negative values are offset from the bottom of section. [8] Default: -1.
halign O string Horizontal alignment for field, image and barcode elements: left, right or center. Default: left.
valign O string Vertical alignment for field, image and barcode elements: top, bottom or center. Default: bottom.
[7](1, 2) Element position is calculated as margin + 1 + offset, i.e. an element with y="-1" will be placed right at the bottom margin (and hence will have zero height).
[8](1, 2) Element size is calculated as margin + 1 + offset - position, i.e. an element with width="-1" will use all space remaining till right margin of the section.
[9]For text fields, minimal box height is determined by font metrics. If box height in a template is non-negative but less than the height of the text line, height of the printout box is made big enough for at least one line of text.

eject

Tells when section elements must be started on a new page or column.

For the title section, eject is evaluated at the end of the section, for all other sections - at the beginning of the section.

Attributes:

Name Req Type Description
type O string page or column. Default: page.
require O dimension Required vertical space on current page or column. If there is enough available space, the section continues current page or column. If omitted, eject is unconditional.
when O expr If the expression evaluates to False, eject is ignored.

arg

Actual argument value passed to subreport to fill a parameter slot.

Attributes:

Name Req Type Description
name M string Parameter name.
value M expr Parameter value.

subreport

Sets an embedded report to run on an inner data sequence.

For example, imagine you have a team of successful encyclopaedia salesmans each selling a really fine set of modern encyclopaedias. Common way to make a report on encyclopedia sales in RDBMS world would be to run the report on the list of all sold encyclopedias and use report groups to print name and total earnings for each salesman. Subreports allow you to do it the other way round - pass a sequence of salesmans to main report template and then run an encyclopedia subreport for each detail section of the main report. It could be especially useful if some of the team members work in a different ways - say, sell something to break the ice at parties - and thus require a totally different layout for their parts.

subreport element may contain a set of arg elements.

Subreports must not be placed inside columns.

Name Req Type Description
template M string Name of the template file.
seq M integer

Subreport sequence indicator. Subreports for a section will be run in the order of seq numbers. Subreports with negative seq values are printed before the section contents, ones with positive seq values - after section contents. Zero value is reserved and should not be used.

seq values for subreports of the same section are not required to be successive.

data M expr Data sequence for the subreport.
when O expr If this expression evaluates to False, the subreport is not run.
inline O boolean

If set to True, the subreport is formatted as an integral part of the main report, without page eject before or after it. [10]

If False (default), the subreport is printed on separate pages.

ownpageno O boolean If set to True, pages in the subreport are numbered as in standalone report. If False (default), page numbers in the subreport continue the sequence of the main report page numbers. Cannot be set to True for inline subreports.
[10]

Inline reports start at current page position. When inline report ends, containing report continues from current page position.

Inline reports may define page header and footer. The first header for inline report is printed where the report starts; following pages will have it printed below page header inherited from containing report. The last footer for inline report is printed where the report ends; other footers will appear above page footer inherited from containing report.

Subreports with different paper size or page orientation cannot be inlined.

Page margins of an inline report must match margins of the containing report; if they don't, a warning is issued and inline report margins are overwritten.

title

A child element of layout or group element containing a summary printed before report data.

While report title is processed, all *_COUNT values are set to zero (see predefined variables.)

Attributes:

Name Req Type Description
swapheader O boolean When used in report title section, value of True lets the title section be printed before the first page header. Ignored for group titles.

summary

A child element of layout or group element containing a summary printed after report data.

Attributes:

Name Req Type Description
swapfooter O boolean When used in report summary section, True means that the last page footer is printed before the report summary. Ignored for group summaries.

layout

Topmost element of report layout definition.

Attributes:

Name Req Type Description
pagesize O string Standard page size, like A4, Letter, Envelope#10 or EnvelopeDL.
width [11] dimension Page width.
height [11] dimension Page height.
landscape O boolean If True, page dimensions are swapped (landscape orientation).
leftmargin O dimension Left page margin.
rightmargin O dimension Right page margin.
topmargin O dimension Top page margin.
bottommargin O dimension Bottom page margin.
[11](1, 2) Required when pagesize is not specified; ignored when pagesize is set.

columns

Arranges report data for multi-column output. May be used in layout and group elements.

Please note: although it is possible to make nested column templates (you may have columns in layout and then in data group and again in a nested group), that does not work well. It is highly recommended to have only one (or none) columns element per report template.

Attributes:

Name Req Type Description
count M integer Number of output columns. All columns have equal widths and equal space between them.
gap O dimension Space between columns.

group

Defines a data-based group of report records.

Attributes:

Name Req Type Description
name M string Group name.
expr M expr Grouping expression. When value of this expression changes, current group is closed and new group starts.

detail

The detail section. Built once for each item in the report data set.

field

Output a text field.

Contents of the field may be set by expr or data attributes or by child data element. Data may be set (either by attribute or by child element) along with expr to estimate field size when expr evaluation is delayed by non-empty evaltime. When evaluation time arrives, the field is filled with expr result.

Attributes:

Name Req Type Description
expr O string Field expression.
evaltime O string When the expression is evaluated: report, page, column or group name. Evaluation is delayed until the end of this section.
data O string Name of a data section defined as a child of the report element.
align O string Text alignment: left, center, right or justified.
format O string Formatting expression. Default: %s (unicode conversion).
stretch O boolean Stretch with overflow.

line

Draw a line.

Attributes:

Name Req Type Description
pen M dimension or string Line style: width of the line or one of dot, dash, dashdot.
backslant O boolean When both box dimensions are non-zero, draw the line from upper left corner to lower right one - \ instead of /.

rectangle

Draw a rectangle.

Attributes:

Name Req Type Description
pen M dimension or string Outline style: width of the line or one of dot, dash, dashdot. Use 0 to disable outline.
radius O dimension Corner radius for rounded rectangles. Default: 0
opaque O boolean If set to False, the rectangle will be drawn transparent. Default: True.

image

Place bitmap image. The bitmap may be loaded from a file or from a data element (either put in the image element or referred by the data attribute.)

Attributes:

Name Req Type Description
type M string Image type, e.g. jpeg or png.
file O string Image file path. If specified, the data is ignored unless the file cannot be loaded.
data O string Name of a data section defined as a child of the report element.
scale O string Scaling mode: cut, fill (adjust image to the box) or grow (adjust the box to the image.)
proportional O boolean If True (default), image or box proportions are kept with fill and grow scaling modes.
embed O boolean If True (default), the image is embedded in the PRP file.

barcode

Print a bar code image. The box of the barcode elements always grows in the direction of coding (vertically if vertical="true", horizontally otherwise) and is filled in the opposite direction. Bar code images are always embedded in the PRP file.

Code contents may be set by expr or data attributes or by child data element. Data may be set (either by attribute or by child element) along with expr to estimate image size when expr evaluation is delayed by non-empty evaltime. When evaluation time arrives, expr result produces the bar code image.

Characters that cannot be encoded with selected code type are ignored.

Attributes:

Name Req Type Description
type M string Code128, Code39 or 2of5i.
module O number X dimension, in mils (1/1000inch). Default: 10.0.
vertical O boolean If True, the image is rotated 90 degrees clockwise.
expr O string Value expression.
evaltime O string When the expression is evaluated: report, page, column or group name. Evaluation is delayed until the end of this section.
data O string Name of a data section defined as a child of the report element.