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).
<?xml version="1.0" encoding="ISO-8859-1" standalone="yes" ?>
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:
<taxonomy id="My First Taxonomy"> ... </taxonomy>
The taxonomy node contains the definition of the taxonomy, the queries used to load data and some presentation annotations. It can have the following types of child nodes:
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
- 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.
- nodeid, (optional) if specified only the nodes with matching Id and Node Type will receive the icon annotation
- attrname and attrvalue, (optional) if specified only the nodes that contain an attribute that matches the given name and has the same value as the given value will have the specified icon.
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. |
nvp | Yes | If nvp="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.
|
prefix | Yes | Set the prefix attribute to any string, in order to prefix the column names of the results with it. The prefix attribute only works for metadata queries and has no effect in taxonomy-structure queries (the attribute is ignored). |
singlerow | Yes | If singlerow="true" the resulting column names do not have an index specifier ("[]").
|
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.
<query name="getUserSynonyms" nodetype="synonym" nodeidcol="synonym_name" nodenamecol="synonym_name"> <sql> <![CDATA[ select * from dba_synonyms where owner = ? order by lower(synonym_name) ]]> </sql> </query> <query name="getUserObjects" nodetypecol="nodetype" nodeidcol="object_id" nodenamecol="object_name"> <sql> <![CDATA[ select dba_objects.*, lower(object_type) as nodetype from dba_objects where owner = ? order by lower(object_name) ]]> </sql> </query>
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.
Metadata Name-Value-Pair (NVP) queries
A metadata query can be a "name-value-pair" (NVP) query. The difference from a normal query 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 (<query ... nvp="true">
) 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 normal query (nvp="false"
) 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:
blue = #00f green = #0f0 red = #f00
Adding a prefix attribute with the value "meta"
to the query, will result in the following attributes:
meta.blue = #00f meta.green = #0f0 meta.red = #f00
Metadata queries returning a single row result
In many cases, metadata queries are invoked in order to return one row worth of additional data and add it to the
current node. VirtualTreeNavigator by default adds an index value ("[]
") at the end of the column
name, which results in attribute keys like column[0]
, column[1]
, etc. If this is undesirable you can set the
singlerow attribute to "true"
. This will prevent the addition of the index number ("[]
").
Examples of Metadata queries
Examples of metadata nodes with references or inline queries are shown below:
<metadata nodetype="..."> <query refid="MyMetaDataQuery" prefix="addon"> <argument ... /> </query> </metadata> <metadata ....> <query name="inlineQuery" nvp="true"> <sql> ... </sql> <argument ... /> </query> </metadata> <metadata ....> <query name="inlineQuery" singlerow="true"> <sql> ... </sql> <argument ... /> </query> </metadata>
Argument nodes for metadata queries work in exactly the same way as for taxdef elements.