next up previous contents
Next: 12 Parameter Value XML Up: DataVision version 0.2.0 Previous: 10 Layout Engines   Contents

Subsections

11 Understanding Report XML Files

This section describes some of the details of the DataVision XML file format.

There are a few general parts to each XML file: the report, the database and table descriptions, the query, parameter definitions, formula definitions, and the report sections that contain the fields and strings to output.

The DTD file report.dtd is a mostly accurate representation of a legal report file. DataVision uses the MinML parser to parse its XML files.

All sizes used in a report file are in points (72 points = 1 inch). All coordinates and lengths may be in floating point, but may be truncated.

For an example report XML file, see postgresql.xml in the examples directory.

11.1 report

The ``report'' tag 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''.

The report tag's remaining attributes (``name'', ``title'', and ``author'') are values that may be edited and displayed in the report by using special fields. See also the ``description'' tag.

11.2 description

This tag contains the descriptive text entered by the report creator.

11.3 database

The ``database'' tag describes the database that is used in the report. See Section 5.1, Connecting to the Database, for how to set these values.

11.3.0.1 driverClassName

is the JDBC driver class name.

11.3.0.2 connInfo

is the magic connection info string used by the database driver to connect to your database. It probably includes the database name (for example, ``jobs'' or ``salesdata'').

11.3.0.3 name

is the name of the database.

11.3.0.4 username

is your database user name.

11.4 query

The ``query'' tag has three parts: 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'' tag represents one of the links between tables that the user specifies.

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

Finally, the ``where'' where clause tag specifies an additional user-specified clause to use when generating SQL. The text of the where clause is contained in a CDATA element.

11.5 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 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.6 formulas

Formulas are defined and appear in the XML before they are used. Each formula has an id, a name, and formula text. The formula text is in a limited RPN mini-language. See Section 6.3.1, The RPN Mini-Language for a description of the language.

11.7 Report Sections

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

This DTD snippet says it best:

<!ELEMENT report        (database query parameters? formulas? headers?
                         footers? page? groups? details)
>
<!ELEMENT headers     section*>
<!ELEMENT footers     section*>
<!ELEMENT page        headers? footers?>
<!ELEMENT group       headers? footers?>
<!ATTLIST group       column CDATA #REQUIRED>
<!ELEMENT details     section*>
<!ELEMENT section     (field|line)*>


11.7.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)
                                                    #REQUIRED
                  value                CDATA        #REQUIRED
>

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, subtotals, and special fields. The ``value'' attribute determines what is displayed.

11.7.1.1 text

Text fields display the value attribute verbatim.

11.7.1.2 column

Column fields display the value of the database column named by the value attribute (for example, ``member.member id'').

11.7.1.3 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.

11.7.1.4 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.7.1.5 subtotal

Subtotal fields display the running subtotal for the column, numeric parameter field, or formula field whose id is contained in this field's value attribute.

11.7.1.6 special

Special fields display one of the following values, named in the value attribute:

11.8 Field Formats

A field's format describes how it will be displayed. Size, bold, underline, italic, borders, and format.

Optional field formats specify a field's alignment, font size, attributes (bold, italic, or underline), wrapping (I'm not sure this works yet), and formatting (for numeric and date fields). The attributes bold, italic, and underline are boolean and may optionally take the values ``true'' or ``false'' (the default is ``true'' if the attribute is specified). Here is an example of a field that displays some text, right justified.

The format string (an attribute of the format tag; confusing, eh?) determines the print format of numeric and date fields. For a complete description of the format string, see Section 9.4.2, The Format Dialog.

  <field id="42" type="text" value="My Very Own String">
    <bounds x="0" y="0" width="100" height="20" />
    <format bold italic underline size="24" align="right" />
  </field>


next up previous contents
Next: 12 Parameter Value XML Up: DataVision version 0.2.0 Previous: 10 Layout Engines   Contents
Jim Menard 2002-04-18