GNOME.org

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