Report-specific Styling

This document applies to xReporter 1.1 and above.

By default, xReporter will show the output of a report in a standard table. This can be further customised either by parameterizing the default output.xsl stylesheets (which does not require knowledge of XSL), or by providing report-specific XSL's. This last option allows for unlimited customisation: instead of displaying the data in a table, you can render it in any way you like. In this document we'll show how to use both approaches.

Stylesheet parameterisation files

The concept

Stylesheet parameterisation files are simply XML files that will be merged into the data retrieved from the xReporter server. They can be used for any purpose, but mostly they are used to provide extra information to the stylesheets. The content of these parameterisation files can be anything you like, though the default stylesheets shipped with xReporter only understand certain things, which are documented below.

For each report existing on xReporter, you can (but are not required to) have a stylesheet parameterisation file, one for each output format (html, pdf, ...). The name of the parameterisation file is alwasy <reportid>.xml, but the location depends on the output format (see below).

If you ever felt the need to add things to report definition files to control presentation-related features or other extensions that are purely handled in the Cocoon layer, consider using this parameterisation file mechanism.

Customising the HTML output

The HTML output parameterisation allows to define columns widths (in pixels) and column-based CSS styling. The parameterisation file should be named as follows:

conf.home/reports/customlayout/html/<reportid>.xml

wherein <reportid> is the id of the report which you'd like to customise (thus the value of the id attribute on the <report> root element of a report definition file).

With this filename-based mechanism, it is possible to have one customisation per report per format type. If you would like to have multiple customizations of the same format type for the same report, you can do so by defining formats and specifying the file to be used in there.

The content of this file should follow the following structure:

<style:style-info xmlns:style="http://outerx.org/xreporter/style/1.0">
  <style:column id="col1" column-width="200" css="background-color: #fffc82" header-css="background-color: grey"/>
  <style:column id="col2" column-width="250"/>
</style:style-info>

The value of the id attribute on the <style:column> element should correspond to the id of one of the columns defined in the report definition. The column-width is specified in pixels. You don't have to provide <style:column > elements for all columns.

After adding this file, you need to redeploy to Cocoon (usually this is done by entering "ant deploy-cocoon" in the conf.home directory). You do not need to redeploy to Phoenix, neither is it needed to restart Phoenix and Cocoon.

Customising the PDF output

To be written (there's an example included with xReporter, see the testconf/reports/customlayout/fo directory).

Customising the CSV (text) output

Using a parameterisation file, you can specify the column width and alignment (left or right) for the CSV output. So this makes it possible to use fixed-width text output. The parameterisation file should be named as follows:

conf.home/reports/customlayout/txt/<reportid>.xml

An example file:

<style:style-info xmlns:style="http://outerx.org/xreporter/style/1.0">
  <style:column id="col1" column-width="30" align="right/>
  <style:column id="col2" column-width="20"/>
</style:style-info>

The width is of course in characters, not in pixels or something.

Report specific XSLT's

To create a report specific XSLT, simply create an XSLT that is named as follows:

conf.home/reports/customlayout/html/<reportid>.xsl

wherein <reportid> is the id of the report for which you'd like to create an XSL (thus the value of the id attribute on the <report> root element of a report definition file).

With this filename-based mechanism, it is possible to have one stylesheet per report per format type. If you would like to have multiple custom stylings of the same format type for the same report, you can do so by defining formats and specifying the file to be used in there.

Below the XSL is shown used in the slashdot sample report (this is a report which retrieves the slashdot newsfeed using HTTP). Since the output of that report contains a specific XML format, it can't be rendered by the default output XSL.

<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" version="1.0"
  xmlns:xr="http://outerx.org/xreporter/result/1.0">

  <xsl:import href="cocoon:/skinsource/stylesheets/html/outputwrapper.xsl"/>

  <xsl:param name="context-path"/>
  <xsl:param name="lang"/>

  <xsl:template match="xr:report">
    <ul>
      <xsl:for-each select="backslash/story">
        <li><a href="{url}"><xsl:value-of select="title"/></a>
           (Department: <xsl:value-of select="department"/>)</li>
      </xsl:for-each>
    </ul>
  </xsl:template>

</xsl:stylesheet>

Usually you'll want the output of the report-specific XSL to be wrapped inside the skin-specific decorations. As shown in the example above, this can be achieved by importing the outputwrapper.xsl. This is a skin stylesheet that will match on "/" and build the basic page layout. It will then < xsl:apply-templates/>, which will then trigger the execution of the template matching on xr:report.

Once you created your report specific XSLT, you need to redeploy to Cocoon (usually this is done by entering "ant deploy-cocoon" in the conf.home directory). You do not need to redeploy to Phoenix, neither is it needed to restart Phoenix and Cocoon.