## Introduction

Libgda's report feature has been reworked and is only offers it report engine object, a low level general usage engine to generate reports in the XML format. More specifically it converts an XML tree containing special tags into another XML tree where all the specific tags have been expanded/replaced with database contents. For more information about the special tags taken into account, please refer to the GdaReportEngine's documentation.

Working on any XML file allows the report engine to work with all the existing post-processors which will actually generate the final file(s) in HTML, PDF or other; for example:

- SVG can be processed by a web browser or further edited using inkscape for example

- DocBook can then be converted to HTML of PDF (see this docbook Wiki page)

- RML files (Report Markup Language), see ReportLab or OpenReports can be converted to HTML or PDF.

- some other XML dialects can also be used such as RLib, Papyrus, and other.

To make it easier to use RML or Docbook XML dialects, Libgda has the GdaReportDocbookDocument and GdaReportRmlDocument which both offer high level of features when dealing with those XML dialects.

From a programmer's point of view, the following code example shows how to convert the "report-spec.xml" file to a "report.xml" report:

    GdaConnection *cnc;
    GdaReportEngine *eng
    xmlDocPtr doc;
    GError *error = NULL;

    cnc = gda_connection_open_from_dsn (...);
    eng = gda_report_engine_new_from_file ("report-spec.xml");
    gda_report_engine_declare_object (eng, G_OBJECT (cnc), "main_cnc");

    doc = gda_report_engine_run_as_doc (eng, &error);
    if (!doc) {
        /* ERROR */
    }
    else {
        xmlSaveFile ("report.xml", doc);
        xmlFreeDoc (doc);
    }
    g_object_unref (eng);

For example the XML "report-spec.xml" file could be:

    <?xml version="1.0" encoding="UTF-8"?>
    <!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN" "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd">
    <article>
      <articleinfo>
        <title>Customers report example</title>
        <abstract>
          <!-- Use the "abstract" parameter which is supposed to be defined using gda_report_engine_declare_object() -->
          <para><gda_report_param_value param_name="abstract"/></para>
        </abstract>
      </articleinfo>

      <!--
           Start a new section, with the "customers" SELECT query, which is supposed to be defined using
           gda_report_engine_declare_object()

           Any <gda_report_iter> node will repeat its contents as many times as there are rows in the
           data model returned by the "customers" SELECT query.
        -->
      <gda_report_section query_name="customers" cnc_name="main_cnc">
        <sect1>
          <!-- Will be replaced by: <title>List of customers (5)</title> if there are 5 rows for example -->
          <title>List of customers (<gda_report_param_value param_name="customers|?nrows"/>)</title>

          <!-- List all the customer's names -->
          <ul>
    	<gda_report_iter>
    	  <li><gda_report_param_value param_name="customers|@name"/></li>
    	</gda_report_iter>
          </ul>
        </sect1>
      </gda_report_section>
    </article>

For a more detailed example, have a look at the `samples/Report` of Libgda's sources.