Table of Contents
Papyrus is an XML reporting engine for Linux. Papyrus enables you to generate reports from a variety of different relational databases and a variety of output formats.
Native database support exists for PostgreSQL and MySQL; and using libgda there are a number of other databases supported, such as Oracle, Sybase, Informix, MS Access. Reports can be generated as PDF, PS, XML, HTML, DVI, TEX or straight ASCII text.
The Papyrus XML language is aimed from a formatting perspective. To give you the ability to generate the best looking reports at ease.
The Papyrus XML format is simple and easy to use. The root tag is report, under which there contains a description of the report, the database configuration, any required arguments, a title, datasources and the table. Generally title and everything after the table is outputted. Everything before specifies the datasources and SQL statements to run.
An element by element run-down follows.
In this section, defining and retrieving data, configuring a database connection and creating data sources are covered. Most of the time these things are written near the start of the Papyrus XML document.
Any database configurations are processed under database tags. Any number of database connections can be configured. Attributes of the database tag follow.
Specifies the name of this particular database connection. The datasource tag references database connections by using this attribute.
Specifies the type of database we're calling. Currently Papyrus supports three values here.
For the PostgreSQL database.
For the MySQL database.
For using the database abstraction layer of GNOME-DB. If libgda is the attribute value, the attribute provider is also required.
This will be one of the values libgda supports such as PostgreSQL, MySQL, Sybase or ODBC.
The database tag also contains a string that initialises the connection to the specific database, defined by the type attribute. For example we use dbname=victory host=nikita user=tim for accessing a PostgreSQL database victory on nikita using tim as the user to access it.
The element in whole would look something like this.
<database name="victory" type="postgres"> dbname=victory host=nikita user=tim </database>
The requires tag allows the report writer to include some variables in the report, thus allowing users to input arguments on the command line that give values to these variables.
Using variables is one instance in which the data tag is used. If the content of the data tag is the name of a variable (ie the content of the requires tag) then the `data' will be retrieved from the argument entered on the command line.
Restricts the value of the input to be of a certain type. For example if the required argument was a date, then by specifying the type as `date', the content of the tag will be checked to make sure it really is a date. The type attribute value can be one of int, date, email, ...
Not yet implemented.
Specifies a default value to be assigned in case no argument was specified on the command line.
The requires tag must be near the top of the report, just below any database tags.
Data sources specify data to retrieve. A datasource tag connects to a database (defined in a database tag) and retrieves data using the content of the tag, generally in the form of an SQL statement.
Specifies the name of this particular data source. The dataloop tag references data sources by using this attribute.
This attribute specifies which database configuration to use. Must be the same as a database tag's name attribute value.
The datasource's content provides the bulk of the data retrieval in the form of, most commonly, an SQL SELECT expression.
A simple example of a datasource element with a simple SQL query.
<datasource name="victory-datasource" database="victory"> SELECT * FROM victory; </datasource>
Any fields specified can then be used as output, when called upon using the data tag.
For example the field member.name in SELECT member.name FROM victory could be used in a data tag like <data>member.name</data>
The data tag is used to retrieve values from a data source or a variable. There are three instances in which this tag is used.
To retrieve a variable's value, the content of the data tag must be the same and the content of the requires tag.
This attribute explicitly defines a data source to retreive the data from (as opposed to the data source defined in a dataloop). This allows you to retrieve one value from the data source where the value of the name attribute is the same as this value.
Within a dataloop, where the data source is defined for the whole loop.
An example of a data tag, within a data source to retrieve the value of a variable.
<datasource name="get-pgname" database="victory"> SELECT pg.text AS pgname FROM programmegroup pg WHERE pg.id=<data>arg_pgroup</data>; </datasource>
This section covers the elements dealing with what gets displayed and how it's formatted. In general the output will consist of a table (with a header and optionally a footer) and a title. Data constructs embedded in structural elements are also covered (such as the dataloop tag).
The title tag is printed at the top of the report.
This example contains a data element which was described earlier.
<title><label>Members of ``<data source="get-pgname">pgname</data>'' Group</label></title>
Like some other elements, title is ultimately a wrapper around label, which is a more general tag for defining output.
The label tag is used when output is desired, in title and also in table. Can contain the data tag to retrieve (amazingly) data . Moreover it can contain text to be outputted directly. Most of the attributes to this tag are used to format the output.
Whether to format the output as a paragraph and wrap the label content. If you set this as `true', the width should also be set. If unspecified then the default is `false' and the width of the containing cell (and consequently the table column) will be the length of the content. Use this attribute, along with the width attribute to force a certain width on the column. Attribute value can be either `true' or `false'.
Align the contents of the table cell. Default value is `left'. Attribute value can be: `left', `right', `centre', `center' or `justify'.
The width of the cell. This is a digit value followed by `cm' or `in'. For example width="4cm".
Output as bold. Default is `false'. Can be either `true' or `false'.
Here's an example of label within a cell.
<cell><label width="4cm"><data source="programme">pname</data></label></cell>
The bulk of data is displayed in a table. This section of the report defines where the data that has been retrieved will be outputted.
The structure of table.
<table> <header><row>...</row></header> <dataloop source="..."><row>...</row></dataloop> </table>
The header tag contains titles for each of the columns. The dataloop tag retrieves data, row by row, filling up the columns defined within the row tag. Naturally the number of columns in the header should be the same as that in the rest of the table.
The report can have any number of tables.
The table tag has three formatting attributes associated with it.
Whether the table should have a border around it. Can be a number from 0-9. Default is `1'.
The width of the table. Can be a percentage, for example width="100%".
Whether or not cells are set as paragraphs. Default is `false'. paragraph can be either `true' or `false'.
The header tag defines titles for the columns of the table. Formatting attributes affect all columns of the header.
Whether or not to format the column titles as paragraph's. Default is `false'.
Specify the alignment of the column titles. Attribute value can be: `left', `right', `centre', `center' or `justify'.
Whether or not to format column titles in boldface. Default is `true'. Can be either `true' or `false'.
This tag provides the report writer with an easy method of retrieving rows of data from the data source and outputting each row in an equivalent manner. Associating with a data source, the dataloop will get fields from each row of data in the data source.
A data source corresponding to the value of the attribute name in a datasource.
The structure of row.
<row> <cell><label><data>firstname</data></label></cell> <cell><label><data>lastname</data></label></cell> <cell><label><data>address</data></label></cell> . . . </row>
Where each cell tag corresponds to a cell in the table. If this row is within a dataloop, the cell would correspond to a column of the table.
Some aspects of the formatting of rows can be specified here through the row tags attributes.
The font to use.
The height of the row.
<?xml version="1.0"?> <!DOCTYPE report SYSTEM "papyrus-1.0.dtd"> <report xmlns="http://papyrus.treshna.com/ns/papyrus/report"> <description> This report lists the members of a programme group </description> <database name="victory" type="postgres"> dbname=victory host=ns3.treshna.com user=postgres </database> <requires type="int">arg_pgroup</requires> <datasource name="get-pgname" database="victory"> SELECT pg.text AS pgname FROM programmegroup pg WHERE pg.id=<data>arg_pgroup</data>; </datasource> <title><label>Members of ``<data source="get-pgname">pgname</data>'' Group</label></title> <datasource name="members" database="victory"> SELECT DISTINCT -- don't duplicate results m.name AS mname, p.name AS pname, pg.text AS pgname, ms.cardno AS cardno, ms.enddate AS enddate, ms.concession AS concession FROM membership ms, member m, programme p, programmegroup pg WHERE ms.programmegroupid=<data>arg_pgroup</data> AND pg.id=<data>arg_pgroup</data> AND ms.memberid = m.id AND ms.history='f' AND p.id = ms.programmeid AND (p.enddate > current_date OR p.enddate IS NULL) ORDER BY mname, pname; </datasource> <table> <header> <row> <cell><label>Name</label></cell> <cell><label>Programme</label></cell> <cell><label>Card No.</label></cell> <cell><label>Expiry Date</label></cell> <cell><label>Concession</label></cell> </row> </header> <dataloop source="members"> <row> <cell><label><data>mname</data></label></cell> <cell><label><data>pname</data></label></cell> <cell><label><data>cardno</data></label></cell> <cell><label><data>enddate</data></label></cell> <cell><label><data>concession</data></label></cell> </row> </dataloop> </table> </report>