Report templates

<report>
<meta>
<loop>
<sql>
<t>
<img/>
chart
<title>
<data>
<d>
<x>
<y>
<table>
<tr>
<td>

Colour Definition

pdfreport

pdfreport - Generate PDF reports from PostgreSQL

SYNOPSIS

pdfreport [-x] [-h host] [-p port] [-U user] [-P password] [-D variable=value] [-Z debuglevel] report.xml

DESCRIPTION

pdfreport parses an XML template and replaces elements in it from the results of PostgreSQL select statements. It then converts the XML to PDF output.

It has optional support for embedded graphs and charts using the chartdir library.

OPTIONS

-x --xml: Output XML rather than PDF.
-d --database database: Connect to this database.
-h --host hostname: Connect to this host (defaults to 127.0.0.1).
-p --port port: Connect to this port (defaults to 5432).
-U --user username: Connect as this user.
-P --pass password: Connect using this password.
-D --define variable=value: Set the variable to this value.
-Z --debug debugflags: Debugging flags.

Report templates

Each template must be a well-formed XML file. If the file is not well-formed pdfreport will be unable to parse it, and will exit with the error ``Failed to parse <filename>''. An XML parser, such as xmlwf from the expat distribution may be useful in finding the exact location of the error.

<report>

The outermost tag in the template must be <report>. Within this may be <sql>, <loop>, <table>, <meta> or <t> elements. It takes no attributes.

<meta>

If this tag has an attribute name with value title then the content of this tag will be used as the title of the report on the web page indexing all the reports. This is not the same as the title at the top of the report, and does not affect the generated PDF file at all, but can be used by wrapper scripts to e.g. generate HTML index pages for reports.

  <meta name="title">Daily User Report</meta>

<loop>

A loop has a name and a loop count variable, set by several tag attributes:

start: The starting value of the loop count variable. Defaults to 1.
count: The number of times the loop will be executed.
end: The end value of the loop.
step: The amount the loop count variable is incremented each time around. Defaults to 1.
name: The name of the loop.

Either count or end must be provided. All other attributes are optional.

The contents of the <loop> tag will be duplicated once for each pass through the loop. Any occurence of the string $<name>.row$ (where <name> is the name of the loop) will be replaced by the value of the loop count variable.

<sql>

This executes a single SQL query to the PostgreSQL database. If the query is a select then it will duplicate the contents of the tag once for each row returned, replacing any occurence of $<name>.<column>$ with the value returned from the database - where <name> is the value of the name attribute of the sql tag.

There are two standard tags:

query: The SQL query to be passed to the database.
name: The name of this query.

Any attributes other than query and name will be bound as named parameters (oracle-style - :name) into the query. There are some odd issues with doing this with PostgreSQL with the current Qt libraries, so using this feature isn't recommended yet.

<t>

A container for text, and other things. Similar to in HTML. May contain , , , , , <t>, <img/> and <chart>.

Optional attributes include:

font: The font to use. Standard PDF fonts are supported: Times, Courier, Helvetica, Symbol and ZapfDingbats.
size: The height of the text, in points.
align: left, right, centre (or center) or justify.

Makes the text contained by the tag bold.

Makes the text contained by the tag italic.

Underlines the text contained by the tag. (Not supported).

Inserts a line break. Takes one optional attribute:

size: The amount of additional vertical spacing to add between the lines of text, in points.

Changes the font of the text contained within the tag.

Optional attributes:

font: The font to use. Standard PDF fonts are supported: Times, Courier, Helvetica, Symbol and ZapfDingbats.
size: The height of the text, in points.

<img/>

Includes an image, in jpeg, png or gif format.

src: The filename of the image to include. As pdfreport is likely to be called from cron it's a good idea to use an absolute path.
width: The width of the image, in points. Optional.; If no width is specified, but a height is, the width will be chosen to preserve the aspect ratio of the image. If neither height nor width is specified then the image will be scaled to the full width of the page.
height: The height of the image, in points. Optional.; If no height is specified, but a width is, the height will be chosen to preserve the aspect ratio of the image.

chart

Plots a chart.

width: Chart width, in points. Optional.
height: Chart height, in points. Optional.
pixel: Number of pixels per point. Default 1.
bg: Background colour or pattern. See colour definition. Default white.
bgangle: If the background colour specifies a gradient it will be drawn at the angle specified by bgangle, in degrees. Default 90.
bgscale: If the background colour specifies a gradient it will repeat this many times. Default 1.
borderwidth: The width of the border of the graph, in pixels. Default 1.
barborderwidth: The width of the border of each bar. Default 0.
pad: The padding around the chart, in points. Default 30.
type: The type of chart. Defaults to bar.
legendwidth: The width of the legend. If zero, no legend is displayed. Default 0.

If neither width nor height are specified the width will default to the maximum usable width of the page.

Unless both width and height are specified the chart will default to being 80% as high as wide.

A chart may contain one or more <data> tags. Each of those can contain zero or more <d> tags. Each of those must contain an <x> and a <y> tag. It may contain a <title> tag.

<title>

The title of the chart.

font: The font to use (in chartdirector format). Defaults to bold.
size: Font size, in points. Defaults to 12.
color: Font color. Defaults to black.
bordercolor: Border colour. Defaults to Transparent.
bg: Background colour. Defaults to Transparent.

<data>

Contains (typically) one dataset within a chart. Contains one or more <d> elements.

group: Sets the default group for the enclosed <d> elements
color: Sets the default colour for the enclosed <d> elements

<d>

Defines a single datapoint on the chart. Contains an <x> and a <y> element.

color: The colour of this datapoint.
group: The group this datapoint belongs to.

<x>

The x value for this datapoint. Need not be numeric.

<y>

The y value for this datapoint. Must be numeric.

<table>

Outermost tag for a table. Contains zero or more <tr> tags.

align

<tr>

Defines one row of a table. Contains one or more <td> elements.

<td>

Defines a single cell of a table. It can contain anything a <t> tag can. Tables embedded within tables are not recommended yet.

bg: Background colour. Default white.
colspan: The number of columns this cell spans. Default 1.
rowspan: The number of rows this cell spans. Default 1.
font: The font to use. Standard PDF fonts are supported: Times, Courier, Helvetica, Symbol and ZapfDingbats.
size: The height of the text, in points.
align: left, right, centre (or center) or justify.

Colour Definition

Colours are used in a number of places - background colours, font colours. Within CDML text, follow the CDML colour syntax. Elsewhere colours are specified as

#RGB
#RRGGBB
#RRRGGGBBB
#RRRRGGGGBBBB: Standard HTML-style hexadecimal red, green and blue elements.
name: X-style colour names ('steelblue', 'goldenrod', 'gainsboro', 'blue'....)
pre-defined patterns: Transparent, goldGradient, silverGradient, redGradient, blueMetalGradient, greenGradient

Any single colour can be preceded by a number and '%' to specify an alpha channel.

Multiple colours, separated by colons can be used in a single colour value. When used ss the bg attribute of a <td> field the colours will be used in sequence on successive table rows. When used as the bg attribute of <chart> or <title> they define a multiple colour gradient, and each colour element can be followed by '.' and a number to set a width for that colour gradient.