The XML Importer allows Exhibit to work off of raw xml data. Customizable options allow the user specify items, properties, types, and more by using attributes in HTML link tags.
The XML Importer reads an XML file and converts it into an Exhibit data set. The importer uses a number of parameters to handle the conversion of the "tree structured" XML to the "collection of objects" Exhibit framework. The assumption is that some of the nodes in the XML tree correspond to the objects you want to consider in the Exhibit, while other tags represent the properties of these objects. Attributes of the XML Importer tag are used to specify which tags in the XML represent objects and which represent properties.
<propertyKey> property value</propertyKey>
Note: XML data files that store information within attributes of XML tags will not work with this importer.
The Link Attribute
In order to use the XML Importer, you must include the below link tag into the head of your exhibit HTML file. Note that 'myData.xml' should point to the specific xml file that you wish to use.
<link href="myData.xml" type="application/xml" rel="exhibit/data" />
In addition to the attributes given above, the XML importer requires two additional tags:
ex:itemTags: designates which XML tags will be considered to be "items" by exhibit. For example, if you had an Exhibit of baseball cards, the user would specify ex:itemTag='card' to make card items.
ex:propertyLabels: specifies which attribute tag of the item will be the item's label. For example, a user might use the 'playerName' attribute of a card to label the card.
<link href="myData.xml" type="application/xml" rel="exhibit/data" ex:itemTags="tagNames" ex:propertyLabels="propertyLabels" />
|attribute name||type of value||meaning||example|
|ex:parentRelations||list of values||comma separated list relations between item types||item.parentRelations --> parentItemLabel|
|ex:itemTypes||list of item types||comma separated list that specifies types of items||item1.type = ex:itemTypes|
|ex:propertyTags||list of property tag names||comma separated list of property tags for users to rename||SEE ex:propertyNames|
|ex:propertyNames||list of user-specified property names||comma separated list of strings to rename properties||item.propertyNames = item.propertyTag|
The link attributes given above should allow the user just as much flexibility (or more) in decoding data into an Exhibit-readable format.
As shown above, each link attribute is a comma separated list of values. To implement this, your code should resemble the following:
<link ... ex:itemTags = "person,dog" ex:propertyLabels = "firstName,breed" ex:parentRelations="hasMaster" ex:itemTypes="human,pet" ex:propertyTags = "name,breed" ex:propertyNames = "callingName,typeOfDog" />
In this example, we have 2 items with tags "person" and "dog" which we would like to get from the XML. For the "person", we tell exhibit:
- item.label = text inside "firstName" tag
- item.type = "human"
For the "dog", we tell exhibit:
- item.label = text inside "breed" tag
- item.type = "dog"
- item['hasMaster'] = label of parent item (most likely person)
- item.callingName = property value of firstName tag
- item.typeOfDog = property value of breed tag
Also Note that the ex:propertyTags and ex:propertyNames affect both item types, however, it is given the a person does not have a "callingName" and "typeofDog".
The following set of rules pertains to when an item is found. The program test the child nodes of that item in the following ways:
- If child node has no children (only text), then that child node is a property of the enclosing item.
- If child node is an item as designated by ex:itemTag, then create parent relation between items
- If child node has children, but is not an item designated by ex:itemTag, then ignore. Instead check the children of the child node with the same rules as specified above.