## GdaReportEngine

GdaReportEngine — Low level report generator based on XML

## Stability Level

Stable, unless otherwise indicated

## Synopsis

    #include <libgda-report/gda-report-engine.h>

    struct              GdaReportEngine;
    GdaReportEngine *   gda_report_engine_new               (xmlNodePtr spec_node);
    GdaReportEngine *   gda_report_engine_new_from_string   (const gchar *spec_string);
    GdaReportEngine *   gda_report_engine_new_from_file     (const gchar *spec_file_name);
    void                gda_report_engine_declare_object    (GdaReportEngine *engine,
                                                             GObject *object,
                                                             const gchar *obj_name);
    GObject *           gda_report_engine_find_declared_object
                                                            (GdaReportEngine *engine,
                                                             GType obj_type,
                                                             const gchar *obj_name);
    xmlNodePtr          gda_report_engine_run_as_node       (GdaReportEngine *engine,
                                                             GError **error);
    xmlDocPtr           gda_report_engine_run_as_doc        (GdaReportEngine *engine,
                                                             GError **error);

## Object Hierarchy

      GObject
       +----GdaReportEngine

## Properties

      "output-directory"         gchar*                : Read / Write
      "spec"                     gpointer              : Read / Write
      "spec-filename"            gchar*                : Write
      "spec-string"              gchar*                : Write

## Description

The GdaReportEngine object generates a report based on a specifications file in any XML format. It browses through the XML file and replaces the parts of it which are <gda_report...> action nodes. The generated XML file may then need to be processed using other post-processor tools depending on the XML file format.

The following "action" tags known are:

Table 22.

Node name | Description | Attributes | <gda_report...> sub nodes
--- | --- | --- | ---

<gda_report_section>

Starts a section which runs a SELECT query to generate a data model (GdaDataModel).

A parameter named "<query_name>|?nrows" is created and is available in any sub node of the <gda_report_section> node, which contains the number of rows in the section's data model.

- "query_name": the name of a SELECT GdaStatement to be run; using this attribute implies that a GdaStatement has already been created and that the query has been declared to the GdaReportEngine object with the "query_name "name. To define a query within the report spec., add a <gda_report_query> sub node instead

- "cnc_name": name of the connection to use (the GdaConnection object has already been created and has been declared to the GdaReportEngine object with the "cnc_name" name)

- <gda_report_query> to define the SELECT query which will be run. It is also possible to use a named query using the "query_name" attribute of the <gda_report_section> node

- <gda_report_if_empty_section> to define the contents by which the <gda_report_section> node is replaced if the data model for the section contains no row.

<gda_report_iter>

Repeats is list of children nodes for each row in the section's data model. Note that is that data model has no row, then the contents of the <gda_report_iter> node will not appear at all in the final result.

For each column of the data model, several parameters are created, named <query_name>|@<column_name> (such as "customers|@`name`" for the "name" column) and <query_name>|#<column_number>, (such as "customers|##0" for the first column). Those parameters can be used in any child node (recursively), and have their value updated for each row of the data model. For more information about the parameter's syntax, see the GDA SQL query syntax.

<gda_report_query>

Specifies the SQL of the SELECT query in a <gda_report_section> section. The SQL should be in the contents of that node

- "query_name": name of the query

- "cnc_name": name of the connection to use (the GdaConnection object has already been created and has been declared to the GdaReportEngine object with the "cnc_name" name)

<gda_report_param_value>

Replace the node with the value of a parameter. The parameter can either by defined globally (and declared to the GdaReportEngine), or defined as part of a section

- "param_name" specifies the name of the parameter

- "converter" optionnally specifies a conversion to apply to the parameter's contents (for now only "richtext::docbook" to convert text in rich text format to the DocBook syntax)

<gda_report_expr>

Replace the node with the evaluation of an expression. The expression can be any SQLite valid expression, and can contain any reference to any parameter. For example the node:

    <gda_report_expr>
    ##customers|@col IS NULL
    </gda_report_expr>

will return a TRUE value if the parameter named "customers|@`col`" is not NULL. For more information about the parameter's syntax, see the GDA SQL query syntax.

<gda_report_if>

Creates an "IF THEN ELSE" flow control, based on the evaluation of an expression (in the same way as for the <gda_report_expr> node). If the expression evaluates as TRUE, then the <gda_report_if> node will be replaced by the children nodes of the <gda_report_if_true> node if it exists, and otherwise by the children nodes of the <gda_report_if_false> node if it exists.

"expr" to define the expression to evaluate

<gda_report_if_true> and <gda_report_if_false>

<gda_report_if_true> | Defines the contents to use when the expression of a <gda_report_if> is evaluated as TRUE |  |
<gda_report_if_false> | Defines the contents to use when the expression of a <gda_report_if> is evaluated as FALSE |  |

## Details

### struct GdaReportEngine

    struct GdaReportEngine;

### gda_report_engine_new ()

    GdaReportEngine *   gda_report_engine_new               (xmlNodePtr spec_node);

Creates a new GdaReportEngine using `spec_node` as the specifications. Note that `spec_node` is not copied, but "stolen" by the new report engine object.

`spec_node` : | a xmlNodePtr node
Returns : | a new GdaReportEngine object

### gda_report_engine_new_from_string ()

    GdaReportEngine *   gda_report_engine_new_from_string   (const gchar *spec_string);

Creates a new GdaReportEngine using `spec_string` as the specifications.

`spec_string` : | an XML string
Returns : | a new GdaReportEngine object

### gda_report_engine_new_from_file ()

    GdaReportEngine *   gda_report_engine_new_from_file     (const gchar *spec_file_name);

Creates a new GdaReportEngine using the contents of `spec_file_name` as the specifications.

`spec_file_name` : | a file name
Returns : | a new GdaReportEngine object

### gda_report_engine_declare_object ()

    void                gda_report_engine_declare_object    (GdaReportEngine *engine,
                                                             GObject *object,
                                                             const gchar *obj_name);

Declares an object which will be used in `engine`, referenced by the `obj_name` name.

`object` must be of a supported types, that it must be a GdaConnection, GdaStatement or GdaHolder object.

`engine` : | a GdaReportEngine object
`object` : | a GObject to declare
`obj_name` : | the name to give to `object` within `engine`

### gda_report_engine_find_declared_object ()

    GObject *           gda_report_engine_find_declared_object
                                                            (GdaReportEngine *engine,
                                                             GType obj_type,
                                                             const gchar *obj_name);

Finds an object which has previously been declared using `gda_report_engine_declare_object()`.

`engine` : | a GdaReportEngine object
`obj_type` : | the type of requested object
`obj_name` : | the name (in `engine`) of the object to find
Returns : | a pointer to the requested object, or `NULL` if not found

### gda_report_engine_run_as_node ()

    xmlNodePtr          gda_report_engine_run_as_node       (GdaReportEngine *engine,
                                                             GError **error);

Execute the `engine` engine and creates a new xmlNodePtr XML node

`engine` : | a GdaReportEngine object
`error` : | a place to store errors, or `NULL`
Returns : | a new xmlNodePtr or `NULL` if an error occurred

### gda_report_engine_run_as_doc ()

    xmlDocPtr           gda_report_engine_run_as_doc        (GdaReportEngine *engine,
                                                             GError **error);

Execute the `engine` engine and creates a new XML document

`engine` : | a GdaReportEngine object
`error` : | a place to store errors, or `NULL`
Returns : | a new xmlDocPtr or `NULL` if an error occurred

## Property Details

### The `"output-directory"` property

      "output-directory"         gchar*                : Read / Write

Default value: NULL

### The `"spec"` property

      "spec"                     gpointer              : Read / Write

### The `"spec-filename"` property

      "spec-filename"            gchar*                : Write

Default value: NULL

### The `"spec-string"` property

      "spec-string"              gchar*                : Write

Default value: NULL