11 Understanding Report XML Files

11.1 Elements

11.1.1 report

The "report" element is the root element of the XML. The attribute "dtd-version" defines the version of the report XML format used to create this report XML file. If this attribute is missing, its value is assumed to be "0.1".

11.1.5.1 database

11.1.5.2 charsep

11.1.5.2.1 column

The "column" element's attributes include "name", "type", and optionally "date-format". The type must be one of "string", "number", or "date".

11.1.5.2.2 metadata-url

If the "charsep" element contains a "metadata-url" element, that means the metadata is stored in an external XML file. The "metadata-url" element looks like this:

<!-- A charsep data source whose metadata is described -->
<!-- by an external XML file. -->
<charsep sep-char=",">
  <metadata-url>http://localhost/foo/metadata.xml</metadata-url>
</charsep>

Note that the URL can be a file URL or any other legal URL.

The metadata XML file (in this example, metadata.xml) must conform to the DTD found in metadata.dtd, which is quite simple. In that file, the root "metadata" element contains a list of "column" elements. Here is a complete example of a metadata XML file:

<!-- See metadata.dtd -->
<?xml version="1.0" encoding="UTF-8"?>
<metadata>
  <!-- We need to define column names and types. For date -->
  <!-- columns, we need to define a string that will be -->
  <!-- used to parse the string so we can turn it into a -->
  <!-- java.lang.Date object. In this example, you could -->
  <!-- skip the date-format string; the default parse -->
  <!-- string (yyyy-MM-dd) is the same string. -->
  <column name="office.name" type="string" />
  <column name="jobs.ID" type="number" />
  <column name="jobs.title" type="string" />
  <column name="jobs.hourly rate" type="number" />
  <column name="jobs.post_date" type="date"
          date-format="yyyy-MM-dd" />
</metadata>

11.1.5.3 query

The "query" element must come after the "database" or "charsep" element. It contains up to three elements: the joins, the sorts, and the where clause. The report uses these and the list of fields it contains to create a SQL query.

Each "join" element represents one of the links between tables that the user specifies.

There is a "sort" element for each group's field and for any other sorts the user specifies.

Finally, the "where" where clause element specifies an additional user-specified clause to use. The text of the where clause is contained in a CDATA element. When generating SQL, the text becomes part of the SQL WHERE clause. When used with a charsep data source, the text is evaluated as a BSF script and the result is used to determine if a record is used or ignored.

11.1.6 parameters

Parameters are defined and appear in the XML before they are used. Each parameter has an id, a type (string, numeric, or date), a name, a question to display when asking the user for a value, an arity, and an optional default value or values.

Types include "string", "numeric", "boolean", and "date".

The arity attribute describes how many values are allowed in the answer. The arity may be "single", "range", "list-single", or "list-multiple".

Default values for each parameter are contained as text within "default" elements.

11.1.7 formulas

11.2 Report Sections

A report may have zero or more parameters, formulas, report headers, report footers, page headers, page footers, and groups. It will have one or more detail sections. Each section may have zero or more fields and lines.

This DTD snippet says it best:

<!ELEMENT report      (description, formula?, paper, field, usercols?,
		       source, subreports?, parameters?, formulas?,
		       headers?, footers?, page?, groups?,
		       details)

>
<!ELEMENT headers     section*>
<!ELEMENT footers     section*>
<!ELEMENT page        headers? footers?>
<!ELEMENT group       headers? footers?>
<!-- column is deprecated, replaced by groupable-id and -->
<!--  groupable-type. For now, both will work. -->
<!ATTLIST group       column CDATA #REQUIRED>
<!ATTLIST group       groupable-id CDATA #REQUIRED>
<!ATTLIST group       groupable-type CDATA #REQUIRED>
<!ELEMENT details     section*>
<!ELEMENT section     (field|line)*>

11.2.1 Fields

Fields display text, including database values. Fields must have a bounds rectangle, and can have borders and formatting descriptions.

<!ELEMENT field        (bounds|format|border)*>
<!ATTLIST field type   (column
                           |formula
                           |parameter
                           |text
                           |special
                           |image
                           |sum
                           |average
                           |count
                           |min
                           |max
                           |stdev)
                                        #REQUIRED
                   value  CDATA         #REQUIRED
>
<!ATTLIST field        visible       (true|false)
>

The order of the bounds, format, and border elements is not important. I don't know how to describe that with DTD, though.

There are six types of fields that a report can display: text, database columns, parameters, formulas, aggregates, and special fields. The "value" attribute determines what is displayed.

text Text fields display the value attribute verbatim.

column Column fields display the value of the database column named by the value attribute (for example, "member.member id"). Yes, table and column names may contain spaces.

parameter Parameter fields display the value obtained by substituting the parameter value whose id is contained in this field's value attribute. (Remember, parameters are defined separately, and each one has an id.) The underlying parameter values are retrieved from the user each time the report is run.

formula Formula fields display the value obtained by executing the formula whose id is contained in this field's value attribute. (Remember, formulas are defined separately, and each one has an id.)

11.2.2 Lines

Lines, though not yet supported in the Design Window GUI, have been part of the report XML since the beginning of DataVision. They are simple, with a thickness, color, and visibility flag. Lines contain two end points.

<!ELEMENT line     point point>
<!-- Color is stored as "red;green;blue;alpha" -->
<!ATTLIST line  thickness  CDATA
                   color      CDATA
                   visible    (true|false)
>

11.2.3 Suppression Procs

11.3 Field Formats

A field's format describes how it will be displayed. Optional format attributes elements specify a field's font family name, alignment, font size, color, attributes (bold, italic, or underline), wrapping, and formatting (for numeric and date fields). The attributes bold, italic, underline, and wrap are boolean and may optionally take the values "true" or "false". The default for all but wrap is false; wrap defaults to true (as of version 0.8.0).

Color is stored as a string of the form "red;green;blue;alpha". Each value is an integer in the range 0 - 255.