Exhibit/XML Importer

From SIMILE Widgets
Revision as of 15:10, 18 June 2010 by Karger (Talk | contribs)
Jump to: navigation, search

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.

Contents

Basics

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" /> 

Required Attributes

In addition to the attributes given above, the XML importer requires two additional tags:

attribute name type of value meaning example
ex:itemTags comma separated list of tags designates which XML tags are roots of exhibit items. if an xml file contains a <card> tag representing cards, the user would specify ex:itemTag='card' to make card items
ex:propertyLabels comma separated list of tags specifies which XML tag of the item will be the item's label a user might use the 'playerName' attribute of a card to label the card

Example:

<link href="myData.xml" type="application/xml" rel="exhibit/data" ex:itemTags="card" ex:propertyLabels="playerName" />

Optional Attributes

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[0]
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[0] = item.propertyTag[0]

The link attributes given above should allow the user just as much flexibility (or more) in decoding data into an Exhibit-readable format.

Multiple Items

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".

Rules

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.

Live Example

Exhibit on Test XML Exhibit || Raw XML

Exhibit on an xml from data.gov data.Gov Exhibit || Raw XML

Personal tools
Namespaces
Variants
Actions
Navigation
Toolbox