Report format index

Introduction

The report format index is a file describing the various output formats available for a specific report. Based on this file, the menu with the various choices will be generated. In case no specific configuration is present, a default menu is shown.

The format index file also allows to configure the default format, thus the first format which should be displayed to the user when viewing the report.

Location of the format index files

The built-in default index

This one is part of the xReporter-Cocoon application and should never be modified. If you want to modify it, you can define a new default in the conf.home, which is described in the next section.

Just for reference, the built-in index can be found at:

<webapp-root>/xreporter/resources/defaultformats/default-index.xml

The custom default index

If you don't like the built-in index, you can define a new default by putting a customized version in this location:

<conf.home>/reports/customformats/default-index.xml

The report-specific index

A report-specific index can be defined by creating a file at this location:

<conf.home>/reports/customformats/<report-definition-id>/index.xml

To avoid too much duplication, it is possible to import the default index into the report-specific index. This is useful if you just want to add a few new formats next to the default ones.

Syntax of the format index files

The empty format index

An empty index file looks as follows:

<?xml version="1.0"?>
<idx:formats xmlns:idx="http://outerx.org/xreporter/index/1.0">

</idx:formats>

Including the defaults

Including the defaults can be done as follows:

<?xml version="1.0"?>
<idx:formats xmlns:idx="http://outerx.org/xreporter/index/1.0">

   <idx:includeDefaults/>

</idx:formats>

Obviously, it is not possible to use idx:includeDefaults in the default index file itself.

Defining entries

An entry defines a link to a specific format.

The following sample defines two such entries:

<?xml version="1.0"?>
<idx:formats xmlns:idx="http://outerx.org/xreporter/index/1.0">

  <idx:includeDefaults/>

  <idx:entry dir="xrp" file="xml" extension="xml" icon="html.gif"/>
  <idx:entry dir="xrp" file="pdf" extension="pdf" icon="pdf.gif"/>

</idx:formats>

The attributes of idx:entry are as follows:

• dir: name of the directory where the format file is defined. This should be a subdirectory of the directory containing the index.xml. It should be a simple name, not a path including slashes. The value xrp is special and is used to refer to built-in formats.
• file: the name of the file defining the format. This should be without the ".xml" extension. This file should be located in the subdirectory named by the "dir" attribute, except of course for the special "xrp" directory.
• extension: optional but recommended attribute, specifying an extension to put in the URL that links to this format.
• icon: optional, an icon found in the images/icons/ directory of the active skin

The name for the entry (displayed to the user) is defined in the format file, not in this index file.

See report formats for more information on creating format files.

Making groups

Entries can be hierarchically grouped by means of idx:group elements.

Sample:

<?xml version="1.0"?>
<idx:formats xmlns:idx="http://outerx.org/xreporter/index/1.0">

  <idx:includeDefaults/>

  <idx:group>
    <idx:title>Some other formats</idx:title>

    <idx:entry dir="xrp" file="xml" extension="xml" icon="html.gif"/>
    <idx:entry dir="xrp" file="pdf" extension="pdf" icon="pdf.gif"/>

    <idx:group icon="chart.gif">
      <idx:title>Charts</idx:title>

      <idx:entry dir="chart" file="chart1" extension="png"/>
    </idx:group>

</idx:formats>

The title for the group is specified with the idx:title element. To have an internationalized title, just put an i18n:text tag in there.

Groups can have an optional icon.

There is no special limit to the nesting of the groups, though the styling might only work up to a certain level.

Default format

The default format is the format shown to the user after the interaction steps are completed. It can be defined as in the following sample:

<?xml version="1.0"?>
<idx:formats xmlns:idx="http://outerx.org/xreporter/index/1.0">

  <idx:default dir="xrp" file="xml" extension="xml"/>

</idx:formats>

Note that if, as in this sample, you choose an output format that doesn't display the usual menus, the user will not be able to select any other format or perform actions such as changing sort order etc.

Putting changes live

As usual, after making changes to these index files, you need to run the following command in the conf.home directory to put the changes live:

cd <conf.home>
xreporter-cocoon deploy