Taxonomy Definition - XML Descriptor
VirtualTreeNavigator's taxonomy definition are written as plain XML files. There's no DTD, since the XML is fairly simple. This section describes the XML Descriptor elements.
1. XML Header
Start your XML file with an XML header like the one below. You may want to use different encodings in case you are using different language characters (e.g. in hard-coded strings).
2. Root Document Element - The "taxonomy" node
Every taxonomy definition contains one and only one taxonomy element. The taxonomy node can have an id attribute, which will be displayed in the UI as the name of the top-level tree node:
The taxonomy node can have three types of child nodes as described below:
| Child Node | Cardinality | Description |
|---|---|---|
| nodeicon | 0..* | Optional cosmetic feature. Using these kind of nodes you can customize the icon image that will be displayed in the UI instead of the default |
| query | 1..* | Specification of an SQL queries (nodetype olf resultset, identifier column, name column, etc.) |
| taxdef | 1..* | Definition rules for the Taxonomy based on level, nodetype, etc. |
| metadata | 0..* | Meta-data query references for gathering additional data for each node. |
2.1. "nodeicon" element
Node Icon definitions are optional. VirtualTreeNavigator will by default use (two-state) folder icons to display the nodes of the hierarchy. Every level of the hierarchy has a different color and there are 16 colors in VirtualTreeNavigator's icon sets, so level 17 has the same colored icon as level 0. "nodeicon" elements can take the following attributes:
- nodetype, the Node Type that will receive the icon annotation
- nodeid, (optional) if specified only the nodes with matching Id and Node Type will receive the icon annotation
- iconindex, the Icon Index that will be used. The Node will be displayed in the grayscale version of the icon until its contents are read from the database. For a list of icons press the [F4] key.
2.2. "query" element
Query definitions are the low-level interface of the Taxonomy Definition. They specify the result set that will be retrieved when the query is called. Query definitions can be used for:
- structuring your taxonomy definitions (normal queries), or
- simply adding meta-data attributes to your nodes (meta-data queries).
Query definitions can have the following attributes:
| "query" attributes | Optional | Description |
|---|---|---|
| name | No | The unique identifier of the query. |
| nodetype | Yes | The Node Type of each of the query's result nodes. This attribute is useful when the query returns a constant type of nodes (e.g. you are reading from the "COUNTRY" table, therefore all nodes are of type="country"). It can be ommitted when the "nodetypecol" is present. If the "nodetypecol" attribute exists and the query returns a non-null value for the specified column then that value will determine the Node Type of the node. |
| nodetypecol | Yes | The name of the column which signifies the Node Type of the node. This attribute is helpful when a query can return nodes of different types, in which case one of the columns in the query should contain the type. |
| nodeidcol | No | The name of the column which denotes the unique identifier of the node. The identifier will be used to match "taxdef" elements during run-time. |
| nodenamecol | No | The name of the column denoting the Name of the node. The name of the node is only required for the UI and will be displayed next to the icon in the Tree representation at run-time. The column can be the same as the id if required. |
| iconindexcol | Yes | The name of the column which can be used to drive the Icon that will be displayed in the UI for each node in the result set. Use this if you want to override the default icons and only if you wish to display a different icon for each child node. You can also use the global "nodeicon" definitions if that's more appropriate. |
| vtn | Yes | If vtn="true" and the query is used in a metadata element, then the first two columns of the
result set are considered to contain a "name-value" pair (NVP). The names and the values of all rows in the result set
are then added to the given node as metadata. The metadata key is formed as {query_name}.{column_value},
where query_name is the unique identifier of the query, and column_value is the value of the
first column of the result set. The value of the second column is used as the metadata value.
|
If a query definition has only the "name" attribute, it is considered to be a Meta-data Query and can only be used to collect additional data for nodes (see the "metadata" node).
Queries can be written in SQL, plain text or a scripting language. A "query" node should therefore contain
one and only one of the following node elements:
| "query" elements | Description |
|---|---|
| sql | This is a simple SQL query that can contain parameter placeholders (?). For each parameter placeholder an argument need to be specified when this query is used. |
| text | A "text" query is simply a comma-separated list of data that gets added to the node. Text can be manipulated at
run-time using the ${arg} placeholder for arguments (the placeholder can be overwritten). |
| xml | An "xml" query — like the "text" query — provides for another way of creating a (nearly) static result
set. As with the "text" query the contents can be altered at run-time using the ${arg} placeholder.
is another type of a nearly static query, i.e. a query that doesn't
run-time using the ${arg} placeholder for arguments (the placeholder can be overwritten). |
| script | Not Implemented Yet. This feature will allow the inclusion of scripting languages which will be able to produce CSV or XML output to be used for building taxonomies. |
2.2.1 "sql" element
SQL elements contain a simple CDATA XML element that in turn contains the SQL query description in a free-text
format. Placeholders are indicated with ? and when the query is executed the number of placeholders should match the number
of arguments given to the query reference. The text of the SQL query can be arbitrarily large, although we recommend to keep
structural SQL queries relatively short and use meta-data queries for additional node data (see the metadata
element).
The only attribute you can use when defining an "xml" query is:
| "text" attributes | Optional | Description |
|---|---|---|
| argplaceholder | Yes | The default argument placeholder for sql queries is a question mark (?). However, it can be overriden using this attribute
to any script may be convenient (e.g. ${arg}) |
Examples of "sql" query elements
Below you can see two examples of "query" elements. The first example returns nodes of "synonym" type for a given database
owner (Oracle).
The second example returns any full list of objects that belong to a database schema (Oracle), using the lower(object_type) as
the Node Type.
2.2.2 "text" element
A query that contains a "text" element, describes the full result set within its body. Most importantly, does not require a connection to a database or any other kind of setup. Theoretically you can build a taxonomy using just text data. However, since text queries do not contain any information on the columns and structure of the data (unlike SQL queries which can retrieve this information from the database driver), they require some additional attributes. The attributes you can use when defining a "text" query are:
| "text" attributes | Optional | Description |
|---|---|---|
| columns | No, if "headerrow" not specified. | A comma-separated list (e.g., columns="id, name") that specifies the names of the columns that appear
in the textual data of the query. The number of columns in this list must match the number of columns in every row of the
result set. |
| headerrow | No, if "columns" not specified. | If headerrow="true" the first row of the result set (the CDATA section) is used for acquiring
the names of the columns of the result set (see examples below).
|
| argplaceholder | Yes | The default argument placeholder for textual data is ${arg}. If however this string has any particular
significance in your text, then you can use this attribute to override it. For example, you may want to use the string
#arg# as a placeholder. |
Examples of "text" query elements
The first example is a text query, that defines two columns with names "id" and "name" and contains three rows of results.
Each time this query is used will generate the same three nodes in the hierarchy.
The second example is a text query which contains the header row within the CDATA section.
2.2.3 "xml" element
"xml" query elements, provide an alternative way of describing a result set.
Like the "text" queries, it does not require a connection to a database or
any other kind of setup. XML elements describe their data using the well-known XHTML elements <th>,
<tr> and <td>.
The column names are described in a nested <th> – <td> group, and the
row data are described in multiple nested <tr> – <td> groups.
The <td> element can contain plain text or a CDATA sub-element if the text is required to
retain its structure (e.g. line breaks).
The only attribute you can use when defining an "xml" query is:
| "text" attributes | Optional | Description |
|---|---|---|
| argplaceholder | Yes | The default argument placeholder for textual data is ${arg}. If however this string has any particular
significance in your text, then you can use this attribute to override it. For example, you may want to use the string
#arg# as a placeholder. |
Examples of "xml" query elements
The first example is a text query, that defines two columns with names "id" and "name" and contains three rows of results.
Each time this query is used will generate the same three nodes in the hierarchy.
The second example is a text query which contains the header row within the CDATA section.
2.2.4 "script" element
Not Implemented Yet. This feature will allow the inclusion of scripting languages which will be able to produce CSV output to be used for building taxonomies.
2.3. "taxdef" element
TaxDef rules are the backbone of the XML descriptor. These rules determine how a hierarchy is built and which queries will be used to build each node of the hierarchy. The taxdef element can take three attributes, all of which are optional:
- level, the Level of the hierarchy this rule applies to
- nodetype, the Node Type of the node this rule applies to
- nodeid, the Node Identifier of the node this rule applies to (requires nodetype attribute)
For example:
Depending on how specific to a node they are, the taxdef elements are sorted by the Taxonomy Engine in order of precedence:
| "taxdef" attributes | Rule Applies To... | ||
|---|---|---|---|
| level | nodetype | nodeid | A specific node in the hierarchy which appears at the specified level. All node attributes must match |
| nodetype | nodeid | A specific node in the hierarchy appearing at any level | |
| level | nodetype | All nodes of the specified Node Type appearing at the specified level of the hierarchy | |
| nodetype | All nodes of the specified Node Type appearing at any level | ||
| level | All nodes of the specified Level | ||
| <none> | Matches any node. This can be used for hierarchies where a recursive relationship exist in the database. | ||
A taxdef element can have one or more query child nodes. These child nodes can either:
- refer to the query definitions of the previous section 2.1, or
- contain an "inline" query.
These query nodes should also define any arguments that should be passed to the queries. The values for the arguments can come from the attributes of the current node or its ancestors.
A query reference has a single attribute called refid which denotes the name of the query definitions to be used and looks like this:
An inline query is identical to the query nodes as defined in section 2.1 with the exception that it obviously doesn't require a "name"::
All kinds of queries (SQL, Text, etc.) can be used as "inline queries".
Argument nodes can take one of the following attribute sets:
| "argument" attributes | Argument Value is taken from... | ||
|---|---|---|---|
| columnname | The value for the argument will be taken from the specified column of the parent node (the node we are expanding) | ||
| level | columnname | The value for the argument will be taken from the specified column of the node with the specified level in the hierarchy. The level can be either absolute (e.g. 0, 1, 2, ...) with zero being the root node of the hierarhcy, or relative (e.g. -1, -2, -3, ...) denoting the number of levels up the hierachy we will retrieve attributes from. A value of "-1" for the level means the parent node, i.e. it can be ommitted as the rule is the same as the previous one. | |
| nodetype | columnname | [order] | The value will be taken from the specified Column of an ancestor node of the specified Node Type.
If more than one node of the same Node Type exist in the hierarchy the order attribute comes into play: - when order="asc" the Taxonomy Engine will look for the node of the specified Node Type from Top to Bottom (i.e. from level 0, 1, ...) - when order="desc" the Taxonomy Engine will look from the current level of the hierarchy, going upwards. Order is assumed to be ascending by default. |
| value | The argument value will be the one specified (hard-coded). This attribute is particularly useful when one query can be reused for more than one Taxonomy Definitions. | ||
Examples of "taxdef" elements
Below you can see two examples of "taxdef" elements. The first example simply calls the "getUserFolders" query when a node of
"dba_user" Node Type is found in the hierarchy.
The second example will call query "getUserObjects" when the "user_folder" with id="44" is encountered. The query takes two arguments,
the first will be the "username" of a "dba_user" ancestor of the current node, the second will be the word "TRIGGER".
2.4. "metadata" element
Meta-data elements are used to populate the attribute-list of a node with additional data that can be generated by means
of executing another query. Similar to the "taxdef" element they can take three attributes, all
of which are optional:
- level, the Level of the hierarchy this rule applies to
- nodetype, the Node Type of the node this rule applies to
- nodeid, the Node Identifier of the node this rule applies to (requires nodetype attribute)
For example:
In an exactly similar fashion to taxdef elements, the metadata elements are sorted by the Taxonomy Engine in order of precedence (depending on how specific to a node they are):
| "metadata" attributes | Rule Applies To... | ||
|---|---|---|---|
| level | nodetype | nodeid | A specific node in the hierarchy which appears at the specified level. All node attributes must match |
| nodetype | nodeid | A specific node in the hierarchy appearing at any level | |
| level | nodetype | All nodes of the specified Node Type appearing at the specified level of the hierarchy | |
| nodetype | All nodes of the specified Node Type appearing at any level | ||
| level | All nodes of the specified Level | ||
| <none> | Matches any node. This can be used for hierarchies where a recursive relationship exist in the database. | ||
Hint! Even though the above options are all available, metadata elements are practically more used in combination with the "nodetype" attribute, i.e. it is much more likely to collect additional data depending on the type of a given node rather than the level of the hierarchy a node appears in.
A metadata element can have one or more query child nodes. Exactly like in the "taxdef" nodes, these child nodes can either:
- refer to the query definitions of the previous section 2.1, or
- contain an "inline" query.
A metadata Query can be either a normal query or a "name-value-pair" (NVP) query. The difference is in the
way the results of the query are added as metadata to a node.
A normal query will add keys of the form column_name[n] where "n" is the number of the row (0 is the first row), and
the values will be taken from the contents of the column in the result set. A metadata value will be added for every
column of the result-set.
A metadata NVP query will add keys from the value of the 1st column of the result-set and values from the 2nd column
of the result-set:
Consider a query with the following results:
If the query is used as a metadata query the following keys and value will be added to the node:
If the query is used as a metadata NVP query the following keys and value will be added to the node:
Examples of metadata nodes with references or inline queries are shown below:
Argument nodes for metadata queries work in exactly the same way as for taxdef elements.