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.
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.
This tag contains the descriptive text entered by the report creator.
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.
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.
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.
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.
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)*>
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.
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>