Papyrus XML Documentation


Table of Contents

Introduction
Defining Data, Retrieving Data
Database Configuration
Variables
Data Sources
Using Data Sources
Formatting and Displaying Output
The Report's Title
Defining and Displaying Content
Structured Output
Front Matter
Back Matter
A looping construct
Rows
Columns
A Full Papyrus Example

Introduction

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.

Defining Data, Retrieving Data

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.

Database Configuration

The database tag

Any database configurations are processed under database tags. Any number of database connections can be configured. Attributes of the database tag follow.

name

Specifies the name of this particular database connection. The datasource tag references database connections by using this attribute.

type

Specifies the type of database we're calling. Currently Papyrus supports three values here.

postgres

For the PostgreSQL database.

mysql

For the MySQL database.

libgda

For using the database abstraction layer of GNOME-DB. If libgda is the attribute value, the attribute provider is also required.

provider

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>

Variables

The requires tag

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.

type

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, ...

Note

Not yet implemented.

defaultvalue

Specifies a default value to be assigned in case no argument was specified on the command line.

Note

The requires tag must be near the top of the report, just below any database tags.

Data Sources

The datasource tag

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.

name

Specifies the name of this particular data source. The dataloop tag references data sources by using this attribute.

database

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>

Using Data Sources

The data tag

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.

For the retrieval of an argument specified within a requires tag.

To retrieve a variable's value, the content of the data tag must be the same and the content of the requires tag.

When the data tag is by itself, in which case a source must be specified.
source

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>

Formatting and Displaying Output

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 Report's Title

The title 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>

Note

Like some other elements, title is ultimately a wrapper around label, which is a more general tag for defining output.

Defining and Displaying Content

The label tag

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.

paragraph

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

Align the contents of the table cell. Default value is `left'. Attribute value can be: `left', `right', `centre', `center' or `justify'.

width

The width of the cell. This is a digit value followed by `cm' or `in'. For example width="4cm".

bold

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>

Structured Output

The table tag.

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.

Note

The report can have any number of tables.

The table tag has three formatting attributes associated with it.

border

Whether the table should have a border around it. Can be a number from 0-9. Default is `1'.

width

The width of the table. Can be a percentage, for example width="100%".

paragraph

Whether or not cells are set as paragraphs. Default is `false'. paragraph can be either `true' or `false'.

Front Matter

The header tag

The header tag defines titles for the columns of the table. Formatting attributes affect all columns of the header.

paragraph

Whether or not to format the column titles as paragraph's. Default is `false'.

align

Specify the alignment of the column titles. Attribute value can be: `left', `right', `centre', `center' or `justify'.

bold

Whether or not to format column titles in boldface. Default is `true'. Can be either `true' or `false'.

Back Matter

The footer tag

Equivalent to the header tag, but output is at the end of the table.

A looping construct

The dataloop tag

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.

source

A data source corresponding to the value of the attribute name in a datasource.

Rows

The row tag.

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.

font

The font to use.

height

The height of the row.

Columns

The cell tag

The cell tag corresponds to a cell in the table. cell has one attribute, span.

span

Cell span's a number of columns

When used in conjuntion with a dataloop tag, the cells of the column are filled up.

A Full Papyrus Example

<?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>