<= Previous | Next => | Table of Contents | DataVision User's Manual |
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. The DTD snippets below may not be completely up-to-date. When in doubt, see the DTD file.
All sizes used in a report file are in points (72 points = 1 inch). All coordinates and lengths are floating point, but may be truncated by layout engines. Colors are stored as strings of the form "red;green;blue;alpha". Each component is an integer from 0 to 255.
For an example report XML file, see postgresql.xml in the examples directory.
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".
The report element'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" element.
This element's "name" attribute describes the paper size used by this report. The name attribute's value must be one of the strings found in the paper.properties file contained in the DataVision.jar JAR file.
jimm/paper.properties is copied into DataVision.jar; that is the version used by DataVision when it is running. If you need to change the paper size values, edit the file paper.properties and then replace it in the JAR file by using the commands
> cd jimm > jar uf ../DataVision.jar paper.properties
This element contains the descriptive text entered in the Report Summary dialog.
The "database" element describes the database that is used in the report. See Connecting to the Database, for how to set these values.
driverClassName is the JDBC driver class name.
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").
name is the name of the database.
username is your database user name.
The "query" element 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" 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 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 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 > <!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, subtotals, 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").
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.)
subtotal Subtotal fields display the running subtotal for the numeric database column, numeric parameter field, or formula field whose id is contained in this field's value attribute.
special Special fields display one of the following values, named in the value attribute:
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 visiblity 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) >
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 (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).
Color is stored as a string of the form "red;green;blue;alpha". Each value is an integer in the range 0 - 255.
The format string (an attribute of the format element; confusing, eh?) determines the print format of numeric and date fields. For a complete description of the format string, see The Format Dialog.
Here is an example field that displays some text, right justified.
<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>
<= Previous | Next => | Table of Contents |
|