Documentation XML

From RLIB

Jump to: navigation, search

Contents

Overview

As RLIB uses XML based report layout description, all RLIB reports begin with: 

    <?xml version="1.0"?>
    <!DOCTYPE report >

Also, the XML standard allows specifying the encoding in which string literals are in the XML file and the Document Type Definition (DTD) schema which the XML file can be validated against: 

    <?xml version="1.0" encoding="UTF-8"?>
    <!DOCTYPE report SYSTEM "rlib.dtd" >

The report description consists of several main and sub-sections denoted by XML tags with mandatory or optional attributes.

Definitions

The following notations are used throughout this documentation page: 

    exp: An Expression of any type
    expN: An expression that computes to a NUMBER
    expS: An expression that computes to a STRING
    expD: An expression that computes to a DATE
    TRUE: NUMBER 1
    FALSE: NUMBER 0
    YES: NUMBER 1
    NO: NUMBER 0

Here is the reference of the expressions that can be used in exp, expN, expS and expD.

The <Report> tag

This tag (closed with the </Report> tag) denotes a main report part. Multiple such parts may exist in a report. The following attributes may be placed in the Report tag:

  • fontSize=expN, REQUIRED: Default report font size
  • query=expS, default main loop query to use. If unspecified the first query passed will be used.
  • orientation=expS. expS can be landscape or portrait
  • topMargin=expN, usually a floating point number representing inches from the top of the page
  • leftMargin=expN, usually a floating point number representing inches from the left of the page
  • bottomMargin=expN, usually a floating point number representing inches from the bottom of the page
  • detail_columns=expN, must be an integer. Represents how many columns across the report should have. Typically this is used for things like mailing labels.
  • column_pad=expN, usually a floating point number. Used in conjunction with detail columns. Represents how much space in inches to leave between columns
  • height=expN representing a percentage from 1 to 100. A hint to the engine in fixed layouts such as PDF as to how much height a report will take up.
  • iterations=expN, an INT. How many times the report should loop though. This is used in conjunction with callbacks to change the data set.
  • paperType=expS Valid values are: LETTER,LEGAL,A4,B5,C5,DL,EXECUTIVE,COMM10,MONARCH,or FILM35MM
  • pagesAcross=expN an INT. How many pages across is the report (Imagine scotch taping pages :) )
  • suppressPageHeaderFirstPage=expN Boolean. Suppress the page header on the first page.
  • suppress=expS Boolean ("yes"/"no"). If set to "yes", this report part will be suppressed.
  • uniquerow=expS string. A condition similar to DISTINCT in SQL can be listed here to list similar rows only once.

Subsections of a Report

The following subsections can occur in a report.

  • <ReportHeader>
  • <ReportFooter>
  • <PageHeader>
  • <PageFooter>
  • <Detail>
  • <Variables>
  • <Breaks>
  • <Alternate>
  • <Graph>
  • <Chart> defines a Gantt chart in the report
  • <MetaData> defines certain metadata in the report.

<ReportHeader>

It describes the report header appearing once at the beginning of the report. It contains an <Output> subsection.

<ReportFooter>

It describes the report footer appearing once at the end of the report. It contains <Output>.

<PageHeader>

It describes the page header appearing at the start of every page. It contains <Output>.

<PageFooter>

It describes the page footer appearing at the end of ever page. It contains <Output>.

<Detail>

The report <Detail> section describes the detail lines that come from the database or file input sources. This subsection contains two subsections:

  • <FieldHeaders>, used for information appearing before the first actual data line, and
  • <FieldDetails>, used for data lines.

Both contain <Output> subsections.

<Variables>

It defines report variables for summation, averages, etc. It contains multiple <Variable> subsections each defining one report variable.

<Variable>

It may contain the following tag attributes:

  • name=expS, REQUIRED
  • type=expS, REQUIRED, valid values are: expression (same as static), count, sum, average, lowest, highest
  • value=expS, the value string may contain an expression computable by RLIB. Refer to the Function Reference page.
  • resetonbreak=expS, it may contain a break name. When the break occurs, the value of this value resets.
  • precalculate=expN, Boolean. Value is precalculated.
  • ignore=expS. the value string may contain an expression computable by RLIB. The expression value is treated as boolean and if the value computes to TRUE, the current row is omitted. The effect is similar to uniquerow in the <Report> tag.

<Breaks>

This section is optional and is used to define hierarchical levels of breaks that may contain headers and footers. If the Breaks section is present, it will contain one or more <Break> subsections.

Breaks and Variables

<Break>

The <Break> tag is used to name and organize a break level. It is used to watch changes in input data and break up the report into one or more named logical parts or sections according to the watched data. Each <Break> section contains a <BreakFields> subsection and may optionally contain one or more <BreakHeader> and <BreakFooter> subsections.

Each <Break> contains one or more <BreakFields> subsections that may contain multiple <BreakField> tags defining the watched data. It may also contain <BreakHeader> and <BreakFooter> subsections, which in turn contain an <Output> subsection. A break may contain the following tag attributes:

  • name=expS, REQUIRED
  • newpage=expS, valid values: "yes", "no". Controls whether a new page is started when the watched dataset changes. The default value is "no".
  • headernewpage=expS, values values: "yes", "no". If "yes", then the break header appears on every new page.
  • suppressblank=expS, values values: "yes", "no". If "yes" and any of the watched data is empty or NULL then this row-set will not be output.

<BreakFields>

This is the subdivision of breaks and contains one <BreakField> tag sections. Each <BreakFields> subsection that may contain multiple <BreakField> tags defining the watched data.

<BreakField>

This tag defines the data to be watched for a change in value to define the break. The use of more than one BreakField tag within a BreakFields section is deprecated. The value="expS" tag attribute is required.

  • value=expS It contains the reference of the watched data, which may be a field from a report query, or a variable.

<BreakField> is a simple XML tag which has no more subsections. Example: 

    <BreakField value="query1.field3"/>

<BreakHeader>

<BreakFooter>

<Alternate>

It defines alternative output that appears in case no queries were defined or the input datasource produced no data. It contains a <NoData> subsection which in turn contains an <Output> sub-subsection.

<Graph>

It defines a graph in the report. It may contain the following tag attributes:

  • name=expS specifies the name of the graph.
  • type=expS, specified the main graph type. Valid values are: line, area, column, row, pie, xy
  • subtype=expS, specifies the subtype for the main type. Valid values are:
    • stacked, percent for main types line, area, column and row
    • ring, offset for main type pie
    • lines with symbols, lines only, cubic spline, cubic spline with symbols, bspline, bspline with symbols for main type xy
  • width=expN, width of graph
  • height=expN, height of graph
  • bold_titles=expN, boolean
  • title=expS, title of graph
  • legend_bg_color=expS, XML color specification
  • legend_orientation=expS, valid value is bottom, everything else means right.
  • draw_x_line=expN, boolean
  • draw_y_line=expN, boolean
  • grid_color=expS, color specification code
  • x_axis_title=expS, title of X axis
  • y_axis_title=expS, title of Y axis.
  • y_axis_mod=expN
  • y_axis_title_right=expS, title of Y axis on the right side
  • y_axis_decimals=expN
  • y_axis_decimals_right=expN

Contains a <Plot> subsection

<Plot>

It may contain the following tag attributes:

  • axis=expS, values values are: x, y.
  • field=expS, input datasource field name
  • label=expS, label of this data in the legend
  • side=expS, valid values: left, right
  • disabled=expN, boolean, whether this particular plot in the graph is disabled.
  • color=expS, color specification

<Chart>, Gantt chart

It defines a Gantt chart in the report. It may contain the following tag attributes:

  • name=expS, name of the chart
  • title=expS, title of the chart
  • cols=expN, width of the chart. The unit is in current font size.
  • rows=expN, height of the chart.
  • cell_width=expN, cell width in pixels
  • cell_height=expN, cell height in pixels
  • cell_width_padding=expN
  • cell_height_padding=expN
  • label_width=expN, label width
  • header_row=expN, boolean, whether to display the header row.

It contains two more subsections, called <HeaderRow> and <Row>.

<HeaderRow>

This determines the data displayed in the header row of the Gantt chart. It may contain the following tag attributes:

  • query=expS, specifies the query used for charting
  • field=expS, the field used for header row labels
  • colspan=expN, how many cols a label spans

<Row>

This determines the data displayed in the data rows of the Gantt chart. The query the Gantt chart uses is specified in the parent <Report> section. It may contain the following tag attributes:

  • row=expN, which row the data goes into
  • bar_start=expN, the starting point of the bar for this data
  • bar_end=expN, the end point of the bar for this data
  • label=expS, the label of this row
  • bar_label=expS, the label placed in the bar for this data
  • bar_color=expS, color of the bar
  • bar_label_color=expS, color of the label in the bar

<MetaData>

<MetaData> allows you to define result set data types in advance and refer to them with a shorter name later in the report. Example and more detailed explanation can be found in the MetaData documentation. The same MetaData keyword is used for both the subsection name and the detail tag lines: 

    <MetaData>
        <MetaData name="expS" value="exp">
        ...
    </MetaData>

The following attributes may be used in the MetaData detail tag:

  • name="expS", the name of the metadata
  • value="exp", any expression. It will be substituted in expressions with the name whenever the defined name is encountered in expressions.

<Output>

The <Output> section is uniformly used inside of several sections that may display something on the report. Output may contain the following attributes:

  • page=expN, ?
  • suppress=expN, whether to suppress the output of the entire line if false.

<HorizontalLine>

Outputs a horizontal line. It may contain the following tag attributes:

  • bgcolor=expS, a color, "black" is the default. For color specification, see Colors
  • size=expN, the width of the line
  • indent=expN, indentation on the left side. The unit is the current (fixed-size) font size.
  • length=expN, the length of the line. The unit is the current (fixed-size) font size.
  • fontSize=expN, optional font size used in "length" and "indent" tags. Default is the report font size.
  • suppress=expN, whether to suppress the line. The expression is computed to a boolean value.

<Line>

A Line containing static or dynamic text. It may contain the following tag attributes: May contain <literal>, <field>, or <image> sub tags It may contain the following tag attributes:

  • suppress=expN, will suppress the output of the entire line if the expression evaluates to true.
  • bgcolor (Color Number) [example: bgcolor="iif(r.detailcnt%2,'0xe5e5e5','white')" - will alternate colors for multi-line entries ]
  • fontsize=expN, specifies the font size. Can be omitted and the report default font size will be used.
  • bold=expN, boolean, whether the text is bold.

<Literal>

It's used for displaying a literal. The actual literal content is between the opening and closing tags. It may contain the following tag attributes:

  • align=expS, the alignment. It can be "left", "right" or "center"
  • bgcolor=expS, the background color of the text
  • color=expS, the text color
  • width=expN, the padding size
  • bold=expN, whether the text is bold. The expression is treated as a boolean value.
  • italics=expN, whether the text is italic. The expression is treated as a boolean value.
  • link=expN, an URL, specifies that the literal is a link. Applicable to PDF and HTML outputs.
  • col=expN, used to place data in this column if output is CSV.

Example: 

    <literal width=60 align="center">Hello World!</literal>

<Field>

Displays the user data referenced in the value attribute. It may contain the following tag attributes:

  • value=expS is the value to be displayed.
  • align=expS, the alignment ("left", "right" or "center")
  • bgcolor=expS, background color specification
  • color=expS, text color specification
  • width=expN, padding to this width
  • bold=expN, whether the text is bold. The expression is treated as a boolean value.
  • italics=expN, whether the text is italic. The expression is treated as a boolean value.
  • format=expS
  • link=expS, an URL, specifies that the field value is a link. Applicable to PDF and HTML outputs.
  • col=expN, used to place data in this column if output is CSV.
  • memo=expN, boolean, used to display a 'text' multi-line SQL field).
  • delayed=expN, boolean, used to indicate fields to be filled after the report was layed out.
    It can be used in conjunction with RLIB internal counters, like "r.totpages".

<Image>

Embeds an image.

  • value=expS, path of the image file
  • type=expS, type of the image. Possible values: "jpeg", "png". Everything else is treated as "jpeg".
  • width=expN, the width of the image
  • height=expN, the height of the image

Example of an RLIB XML file 

    <?xml version="1.0"?>
    <!DOCTYPE Report SYSTEM "rlib.dtd" >
    <Report fontSize="12" orientation="landscape" xmlns:xi="http://www.w3.org/2003/XInclude">
	 <Alternate>
             <NoData>
                 <Output>
                     <xi:include href="common.xml" xpointer="xpointer(/common/nodataoutput/*)" />
                 </Output>
             </NoData>
         </Alternate>
         <ReportHeader>
             <Output>
                 <xi:include href="common.xml" xpointer="xpointer(/common/header/*)" />
             </Output>
         </ReportHeader>
         <PageHeader>
             <Output>
                 <Line fontSize="11" bold="yes">
                     <Field value="m.report_name" width="40" align="left" col="1" />
                 </Line>
                 <xi:include href="common.xml" xpointer="xpointer(/common/date/*)" />
                 <HorizontalLine size="4" bgcolor="'white'" />
             </Output>
        </PageHeader>
        <Detail>
            <FieldHeaders>
                <Output>
                    <HorizontalLine size="1" bgcolor="'black'" />
                    <Line bgcolor="'0xe5e5e5'">
                        <Literal width="30" col="1">OwnerCode</Literal>
                    </Line>
                </Output>
            </FieldHeaders>
            <FieldDetails>
                <Output>
                    <Line bgcolor="iif(r.detailcnt%2,'0xe5e5e5','white')">
                        <Field width="30" col="1"  align="left" value="rep_owner" />
                        <Literal width="1"/>
                        <Field   width="7"  col="8"  align="left" value="format_time(v.min_wrk)" />
                    </Line>
                </Output>
            </FieldDetails>
        </Detail>
        <PageFooter>
            <Output>
                <xi:include href="common.xml" xpointer="xpointer(/common/pagefooteroutput/*)" />
            </Output>
        </PageFooter>
        <Variables>
            <!-- Things that are done for every sql query returned line. -->
            <Variable name="min_wrk" value="get_mins_time(rep_work_time)" type="expression" resetonbreak="" />
        </Variables>
        <ReportFooter>
            <Output>
                <Line>
                    <Literal>||</Literal>
                    <Literal width="1" />
                    <Literal width="11">Hour</Literal>
                </Line>
            </Output>
        </ReportFooter>
    </Report>
Retrieved from "http://newrlib.sicom.com/~rlib/index.php/Documentation_XML"
Personal tools