Carte Report Writing Manual

Reports and Templates

To write a report, you need to create a Template. A template is an XML document in the Carte format, embedding another XML document with another (arbitrary) format, through the use of XML namespaces. A Carte template looks like this:

<?xml version="1.0" encoding="ISO-8859-1"?>
<xte:report xte:version="0.1" xmlns:xte="http://informatica.info/projects/carte">
<xte:document-writer xte:type="pdf" />
<xte:media-type>
  application/pdf
</xte:media-type>
<xte:document-properties>
<xte:property xte:name="title">
  Report for ${myvar}
</xte:property>
</xte:document-properties>
[... the real XML template goes here ...]
</xte:report>

At first, this may seem too complicated or loosely defined, but gives a lot of flexibility. To simplify things, we are going to assume that the embedded XML document is an XHTML document, so our example becomes:

<?xml version="1.0" encoding="ISO-8859-1"?>
<xte:report xte:version="0.1" xmlns:xte="http://informatica.info/projects/carte">
<xte:document-writer xte:type="pdf" />
<xte:media-type>
  application/pdf
</xte:media-type>
<xte:document-properties>
<xte:property xte:name="title">
Report for ${myvar}
</xte:property>
</xte:document-properties>
<html xmlns="http://www.w3.org/1999/xhtml" lang="es">
<head>
  <style type="text/css">
    body {font-family: Arial, Helvetica}
    p {font-size: large;  font-weight: bold;  margin-left: 5%;  margin-right: 5%}
    table.global {border-width: thick}
    table {border-width: medium;}
    th {font-weight: bold; background-color: silver }
    td.numeric {text-align: right}
    .myclass {font-size: smaller;}
    p#foo {font-family: Courier;}
  </style>
</head>
<body>
  <h1 xte:type="format">Report for ${myvar}</h1>
  <p xte:type="format">
    Lorem ipsum ${var2}.
  </p>
  <!-- The dataspec -->
  <xte:dataspec xte:source="mydatasource">
    <xte:row-limit>
      150
    </xte:row-limit>
    <xte:sort-options>
      <xte:sort-field xte:name="date" xte:order="asc" />
    </xte:sort-options>
  </xte:dataspec>
  <!-- Dynamic table -->
  <table type="table" xte:dataspec="mydatasource">
    <tr>
      <th>Independent variable</th>
      <th>Data 1</th>
      <th>Data 2</th>
    </tr>
    <tr>
	  <td>${date,dd/MM/yyyyD}</td>
	  <td class="numeric">${yaxis,11d}</td>
	  <td class="numeric">${zaxis,14d}</td>
    </tr>
  </table>
  <!-- Chart -->
  <img xte:type="barchart" xte:dataspec="mydatasource">
    <xte:param xte:name="title">
      Bar Chart Title
    </xte:param>
    <xte:param xte:name="maxdata">
      120
    </xte:param>
    <xte:param xte:name="x_axis_title">
      Independent variable
    </xte:param>
    <xte:param xte:name="x_axis_label_format">
      ${date,ddD}
    </xte:param>
    <xte:param xte:name="y_axis_title">
      Y axis
    </xte:param>
    <xte:param xte:name="datasets">
      1
    </xte:param>
    <xte:param xte:name="dataset_param_0">
      yaxis
    </xte:param>
    <xte:param xte:name="width">
      400
    </xte:param>
    <xte:param xte:name="height">
      260
    </xte:param>
    <xte:param xte:name="file">
      ${filename}.png
    </xte:param>
  </img>
</body>
</html>
</xte:report>

You can see that transforming an XHTML document into a report consists in annotating it with Carte elements and attributes, through the use of XML namespaces. The document includes a CSS style declaration, which will be honored when printing the report, recognizing even the appropriate @media rules.

Once you have your template(s), your application must handle the production of the reports, by providing the data to them.

It is interesting to note that with a single instance of data, you can write multiple reports with multiple templates (and multiple output formats), so your application can take advantage of this capability to write multiple reports without the need to recompute the data.

This document describes the report format, which is relatively intuitive, however it is recommended that you look at some report samples first to get an idea of how the format works.

Blocks and Peer Elements

When a block-displayable element (i.e. its display style property has the value of block) has the Carte namespace prefix, or includes an attribute in the Carte namespace, it is known as a "report element", and can have a "report block" associated to it. A "report block" is the Object responsible for the rendering of the report element, which in turn is known as the "peer element" of the "report block".

The block can be a generic block that works with any document-writer, or a writer-specific block. The former case is the most frequent. Internally, those writer-generic blocks are generally wrapped with a native adaptor when a particular type of rendering must be done, but this is transparent to the user.

There are two kinds of blocks: template blocks (also called "map" blocks) and dynamic blocks. Template blocks use a name-value map to render themselves, and not a multiple-row data source, which is what dynamic blocks can render. A report element without a dataspec attribute is assumed to be a template block, otherwise it is a dynamic block.

Frequently used blocks are: template (simple), template table, dynamic table, chart.

Carte namespace Elements and Attributes

The following are the Carte namespace elements and attributes. Remember to use them with the appropriate namespace prefix. The source document format (generally XHTML) must use the default namespace.

report

The root element of the report, requires the version attribute and the namespace definition.

document-writer

The report system can render different document types. The "document-writer" is responsible to render a Carte template into a final document. In the example above, it is set explicitly, but can be set programmatically.

media-type

The MIME media type for the target document, in case it is not specified by the document-writer.

document-properties

The report can have several properties that can be used in ${property-name} constructs over the document, or used by the underlying objects. Those properties are defined inside this element, with property sub elements.

The syntax is:

<property name="property-name">
  Property value (nested ${properties} are allowed)
</property>

Property	Value	Description
`locale`	text	Locale (la[_co[_va]] style). It can be hardcoded into the template or set programmatically based on file extension (example: a filename document_es.tem would lead to "locale=es")
`write.dir`	text	Default directory for writing the reports

The `type` attribute

This attribute, when annotating any block-displayed XHTML element, causes such element (and descendants) to be interpreted as a report element of the given type. The value of this attribute is used to determine which peer report block should be used.

If omitted, it is assumed to be a standard DataFormatter template block.

dataspec

Must have a name attribute specifying the name of the datasource as given to the underlying ReportDataSource object. The id attribute is optional, but if two dataspecs refer to the same datasource, they must have two different id's.

Optional child elements of dataspec:

row-limit

row-limit contains the maximum number of rows that the datasource will use.

sort-options

Its child elements are the names of the data fields used to order the datasource:

sort-field

Its name attribute is the name of a data field used to order the datasource, and the order attribute can be "asc" or "desc" depending on the sort order for this field.

Commonly-used Blocks

Format Block

A format block simply formats the data according to a DataFormatter formatting specification. See the DataFormatter class description for more information.

Table Block

Renders a table.

Bar Chart Block (type="barchart")

Renders a bar chart graph representing one or more datasets. In its basic form, when printed it gives the filename of the created image. Wrapped versions may return different values.

Property	Value	Description
title	text	Chart title
font	(fontfamilyname[-style[-pointsize]])	Title font spec
width	integer	Image width
height	integer	Image height
file	text	Filename of the image
write.dir	text	Current report directory
max	integer	Maximum amount of data items to plot
x_axis_label_format	format specification	A DataFormatter-style format specification for X axis data (eg. "${year,-5T}")
datasets	integer	Number of data sets to plot in parallel
dataset_param_N	text	Name of the dataset-N parameter to be plot (eg. "age")
dataset_caption_N	text	Caption to be used for the specified N-th dataset parameter (eg. "Subject age")
dataset_color_N	Color name (eg. "red") or RGB integer values ("R,G,B" or "R-G-B" where R, G and B are between 0 and 255)	The color to be used when plotting the N-th dataset
x_axis_title	text	Label for the X axis
y_axis_title	text	Label for the Y axis

Carte Report Writing Manual

Introduction

Reports and Templates

Blocks and Peer Elements

Carte namespace Elements and Attributes

report

document-writer

media-type

document-properties

Recommended Document Properties

The `type` attribute

dataspec

row-limit

sort-options

sort-field

Commonly-used Blocks

Format Block

Table Block

Bar Chart Block (type="barchart")

Pie Chart Block (type="piechart")

Carte Report Writing Manual

Introduction

Reports and Templates

Blocks and Peer Elements

Carte namespace Elements and Attributes

report

document-writer

media-type

document-properties

Recommended Document Properties

The type attribute

dataspec

row-limit

sort-options

sort-field

Commonly-used Blocks

Format Block

Table Block

Bar Chart Block (type="barchart")

Pie Chart Block (type="piechart")

The `type` attribute