# 1

# The data manager's XML syntax

The XML tree's root node must be a `<data>`, which is allowed to contain one or more data source definitions. Each data source is defined by `<query>` or `<table>` nodes, both accepting the following optional attributes:

"id" to specify a data source string ID, used when linking data sources one to another;

"title" to specify a title.

It is of course possible to use both the `<query>` or `<table>` tags in the same data sources specifications.

# Exported variables

Each data source exports some variables which can be reused by other data sources to introduce a dependency. When the data sources are executed, the contents of these exported variables are reset depending on the row actually selected in the resulting tabular view. If no row is selected then the variable is unset.

Any data source depending on a variable is executed again when the variable changes, and in case the variable is unset, the data source's execution result is an empty data set.

# The `<query>` tag

Use the `<query>` tag to specify an SQL SELECT statement, as the contents of the tag. Linkage to other data sources can be achieved using variables in the SELECT's SQL.

<data> <query title="Customers" id="customers"> SELECT id, name FROM customers where name like ##name::string </query> <query title="Customer's details" id="cust_details"> SELECT * FROM customers WHERE id=##customers@id::int </query> </data>

For example the previous XML specification defines two data sources:

the `customers` data source which selects some fields from the customers table, and which depends on a string variable named `name`. This variable has to be set when the data sources are executed because it won't be exported by any data source in this specification.

the `cust_details` data source which selects all the details of a customer specified using its ID. This second data source depends on the previous one because the `customers@id` variable is exported from the `customers` data source.

Executing this data sources specification will create two tabular views: one where you can select a customer, and one which displays all the attributes for the selected customer.

## Exported variables

Each data source defined by a `<query>` tag exports the following variable for each column of the resulting data set (the variable's type is the same as the column's type):

`<data source ID>@<column position>` where the column's position starts at 1

`<data source ID>@<column name> if the data set's column is a table column`

# The `<table>` tag

Use the `<table>` tag to define a data source which will display the contents of a table. This tag:

requires the "name" attribute which represents the table name.

can have a "id" attribute corresponding to the data source's ID. If not present, and ID will be assigned automatically.

can contain a `<depend>` tag which defines a dependency on another data source with the "foreign_key_table" attribute defining the name of the table to which there are foreign keys used to determine the dependency, and the "id" attribute can specify a data source ID if different than the aforementioned table

The `<depend>` tag, which, for a data source from a table, defines a dependency to another data source from a table:

requires the "foreign_key_table" attribute defining the name of the table to which there are foreign keys used to determine the dependency

can have a "id" attribute corresponding to the ID of the referenced data source. If not provided, then the dependency may fail if there is no data source which ID is the"foreign_key_table" attribute.

can contain one or more `<column>` tag which contents define the columns to identify the foreign key to use; this is necessary if there are multiple foreign keys, and can be omitted if there is only one possible foreign key. The listed columns are the one from the table where the foreign key exists.

<data> <table id="the_cust" name="customers"/> <table name="orders"> <depend id="the_cust" foreign_key_table="customers"> <column>customer_id</column> </depend> </table> </data>

For example the previous XML specification defines two data sources:

the `customers` data source which selects all the contents of the customers table.

the `orders` data source which selects among contents of the `orders` table, the rows which correspond to a row in the `customers` table using the foreign key on table orders which involves the "orders.customer_id" column and the primary key of the customers table. The "id" attribute of the `<depend>` tag is necessary here to identify referenced the data source.

Note in this example that:

you don't have to specify the fields involved in the foreign key linking the `orders` and `customers` tables

the data sources IDs have been assigned the names of the selected tables as no "id" attribute has been specified for the `<table>` tags.

## Exported variables

Each data source defined by a `<query>` tag exports the following variable for each table's column (the variable's type is the same as the column's type):

`<data source ID>@<column name>`

`<data source ID>@<column position>` where the column's position starts at 1