Skinning

This document applies to xReporter 1.1 and above.

In many cases you might want to adjust the look of the xReporter site to integrate with the rest of a website. In xReporter, the look of the site (the HTML code) is generated by transforming the XML outputted by the reporting server to HTML using XSLT. Basically, adjusting the look of the site is thus a matter of editing the XSLT stylesheets. However, to avoid creating a complete " fork" of the stylesheets, there's a skinning system available.

Creating a new skin

To create a new skin, you start by copying one of the default xReporter skins, and then you can customise them. First of all, choose the xReporter skin from which you'd like to start. xReporter comes with the following skins:

The "default" skin	The "outerthought" skin

The "default" skin is a very simple one without images, the "outerthought" skin is a more advanced one use images.

Now create some directory wherein you'll put your own skin(s), we'll use the following as example:

/home/jef/skins

Then copy either the default or outerthought skin directory to this new directory. The skin directories can be found at the following locations:

/home/jef/xreporter-cocoon/src/resources/skins/default
/home/jef/xreporter-cocoon/src/resources/skins/outerthought

Supposing you've selected the default skin, you'll now have the directory:

/home/jef/skins/default

Now rename this directory to something else:

/home/jef/skins/myskin

To verify that everything until now is done correctly, we'll deploy and use the skin. If you are usually deploying from your conf.home directory (using the "ant deploy-cocoon" command), then edit the file conf.home/build.properties, and add a property called extra.skins.dir pointing to your skins directory, for example:

extra.skins.dir=/home/jef/skins

Then use the "ant deploy-cocoon" command as usual to redeploy to Cocoon.

If on the other hand you are using the build script from the xreporter-cocoon directory, invoke it as usual but pass the value of the extra.skins.dir property in the command line:

./build.sh -Dcocoon.home=... -Dconf.home=... -Dextra.skins.dir=/home/jef/skins deploy

After deploying, your new skin should now be copied to cocoon/mount/xreporter/resources/skins. The skin that is actually used by xReporter can be configured in the cocoon.xconf file (found in cocoon/WEB-INF), to change it edit that file and look for the following part:

<component-instance name="xreporterdefaults"  
   class="org.apache.cocoon.components.modules.input.DefaultsMetaModule">
  <values>
    <skin>default</skin>
  </values>
</component-instance>

And change the text inside the <skin> element to match the name of your skin directory (in our example, this would be myskin).

Now restart Cocoon and access the xReporter site: it should now look like the skin you copied. Now you can move on to further customise the new skin, which is described in more detail in the next section. Each time you'd like to try out your changes, you need to run the deploy script, but usually you will not need to restart Cocoon.

Adjusting the stylesheets

About skin and common stylesheets

For each page on the xreporter site there is a corresponding XSLT stylesheet. The stylesheets are:

Stylesheet name	Purpose
datasources.xsl	renders the list of data sources
reportcatalog.xsl	renders the report catalog
interaction.xsl	renders an interaction step
output.xsl	renders the output of a report (the HTML table containing the resultset data, with or without grouping)
qbe.xsl	renders the "Query By Example" page
orderby.xsl	renders the page with the sort order options
columns.xsl	renders the page where the column order and visibility can be configured
error.xsl	renders the error page (in case of xReporter-specific errors, not in case an error occurs inside Cocoon)
outputwrapper.xsl	can be imported by report-specific stylesheets to render a skin-specific base layout

Most of the time, different skins will only add things like a header, a navigation bar, a footer, ... without touching the styling of the actual main content. Therefore, xReporter has a set of common XSL's that can render the main content. These common XSL's can be reused by importing them in the skin stylesheets (using xsl:import). Both the default and outerthought skins do this, though the outerthought skin will now and then override some templates from the common stylesheets to provide a more customised look. An example of the use of common stylesheets is shown in the image below.

How the stylesheets work

Lets take a look at how the XSL's are built up. We'll use the interaction.xsl and the default skin as an example. The Cocoon sitemap (which is an XML file wherein the publishing pipelines are defined) always references the skin XSL's, it doesn't know about the common XSL's. The skin interaction.xsl looks as follows:

<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="layout.xsl"/>
  <xsl:import href="../../../../common/stylesheets/html/interaction.xsl"/>

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

  <xsl:template match="/">
    <xsl:call-template name="make-xreporter-layout">
      <xsl:with-param name="pagetitle" select="'complete-parameters-title'"/>
    </xsl:call-template>
  </xsl:template>

</xsl:stylesheet>

The stylesheet has a template matching on "/", that's where the processing will start. Since the page layout is basically the same for all pages, we've delegated that to a third stylesheet called layout.xsl that contains the template called "make-xreporter-layout" (the outerthought skin uses the same approach). The make-xreporter-layout template will call < xsl:apply-templates/> on the location where the main content should come, this will then trigger the execution of the templates contained in the imported common interaction.xsl.

So basically, to adjust the basic page layout, all one has to do is edit the layout.xsl.

Using I18n in stylesheets

If your skin adds labels etc. that you'd like to see translated depending on the user's locale, then this can be easily achieved using Cocoon's I18nTransformer (which is enabled by default in xReporter).

You need to create (or edit) the resource bundles located in

/home/jef/skins/myskin/messages_<language>_<COUNTRY>.xml

wherein the <COUNTRY> part is optional. The outerthought skin includes an example of such a resource bundle.

To have some text translated, first make sure the i18n namespace is declared using:

xmlns:i18n="http://apache.org/cocoon/i18n/2.1"

and then put the text to translate inside an i18n:text element:

<i18n:text catalogue="skin">translate me</i18n:text>

The attribute catalogue defines that the text should be retrieved from the skin-specific resource bundle.

For more details on the usage of the I18nTransformer and its resource bundles, we refer to the Cocoon documentation.