Exploring TRIRIGA With Exhibit
Interactive Web Presentations
In this article, we're going to look at using the Exhibit framework to visualize data residing in the TRIRIGA system. Originally developed as part of the SIMILE project at MIT, Exhibit is a browser-based system for combining, visualizing, and presenting sets of information in an interactive environment.
One key feature of Exhibit is that it allows you to produce very slick presentations of your data with little or no "programming"; simple HTML-based templates define the look and feel of the page, and the Exhibit framework does the majority of the work. As an example, here is the HTML code for a simple Exhibit that displays a timeline of upcoming Work Tasks:
Sample Exhibit HTML Code<html>
<head>
<script src="http://static.simile.mit.edu/exhibit/api-2.1.0/exhibit-api.js" type="text/javascript"></script>
<script src="http://static.simile.mit.edu/exhibit/extensions-2.1.0/time/time-extension.js" type="text/javascript"></script>
<link rel="exhibit/data" type="application/json" href="example.js"/>
<style type="text/css">
div.exhibit-toolboxWidget-popup { display: none; }
div.exhibit-views-header { display: none; }
</style>
</head>
<body>
<div ex:role="view" ex:viewClass="Timeline"
ex:start=".planned-start-date"
ex:end=".planned-end-date"
ex:showSummary="false">
<table ex:role="exhibit-lens">
<tr>
<td>
<div ex:content=".label"></div>
<div>
<b>Planned Start:</b> <span ex:content=".planned-start-date"></span>
</div>
<div>
<b>Planned End:</b> <span ex:content=".planned-end-date"></span>
</div>
</td>
</tr>
</table>
</div>
</body>
</html>
When linked to a data source and rendered, we get a nice timeline that looks like this:
Exhibit - Work Task Example
This in itself (as minimal as it is) is pretty cool; but it really just barely scrapes the surface of what Exhibit provides. With not much more effort, it is possible to integrate mapping functionality, charts, and many other visualizations. Here is the same example with a timeline, mapping, priority color-coding of tasks, facet-based filtering, and searching ( source is here, it's not much bigger than the previous example): Exhibit - Work Task Example with Timeline, Mapping, and Priority Color-Coding
The Exhibit site has several additional examples which show some of the framework's potential in more depth.
Exhibit consumes one or more data sources in JSON (Javascript Object Notation) format; in this article, we'll be building a system for generating compatible sources from data in TRIRIGA, and linking them to an HTML document in Document Manager.
Exhibit Data Source Format
Here's what a sample data source looks like:
Sample Exhibit Data{
types: {
"Work Task": {
pluralLabel: "Work Tasks"
}
},
properties: {
"planned-end-date": {
label: "Planned End Date",
valueType: "date"
},
"planned-start-date": {
label: "Planned Start Date",
valueType: "date"
}
},
items: [
{
label: "1001201-Replace air filters",
type: "Work Task",
"planned-start-date": "2009-10-22T08:00:00-05:00",
"planned-end-date": "2009-10-24T17:00:00-05:00"
},
{
label: "1001022-Fire extinguisher check",
type: "Work Task",
"planned-start-date": "2009-10-20T09:00:00-05:00",
"planned-end-date": "2009-10-21T13:30:00-05:00"
},
{
label: "1001233-Move furniture",
type: "Work Task",
"planned-start-date": "2009-10-19T08:00:00-05:00",
"planned-end-date": "2009-10-22T14:00:00-05:00"
},
{
label: "1001227-Change lightbulbs",
type: "Work Task",
"planned-start-date": "2009-10-23T13:00:00-05:00",
"planned-end-date": "2009-10-23T16:30:00-05:00"
},
{
label: "1001332-Fix clogged pipe",
type: "Work Task",
"planned-start-date": "2009-10-19T10:00:00-05:00",
"planned-end-date": "2009-10-19T12:00:00-05:00"
}
]
}
JSON consists of two primary structures; collections of key-value pairs (basically sets of properties, enclosed in curly braces, " {}"), and ordered value lists (arrays, enclosed in square braces, " []"). Exhibit objects have three core properties:
- types - An object with properties describing the types of items in the Exhibit, and how their plural form should be labeled. In the example above, the Exhibit has items of type "Work Task", which should be labeled "Work Tasks" when used in a plural context. If not specified, the default is to append "s" to the item's type (which would have been sufficient for our example); however, this can be useful for item types like "Person", where "People" is a more natural plural form.
- properties - An object describing the fields and relationships of items in the exhibit. In the example, "planned-start-date" and "planned-end-date" are defined as fields of type "date". Several data types are recognized and supported by the Exhibit framework (specified by the "valueType" attribute):
- text - Simple text strings
- number - Integer or floating point numbers
- date - Dates and data/time values in ISO 8601 format
- boolean - Values "true" or "false"
- url - A URL that should be hyperlinked when displayed by Exhibit
- item - A pointer to another item's identifier
In addition to the value type, the property definition can also provide a label (specified by the "label" attribute) for Exhibit to use when presenting the property. Properties of type "item" are special; they define a relationship between data items. The name of the relation is given in the "label" attribute, and the reverse relationship is specified using the "reverseLabel" attribute. This is very similar in nature to TRIRIGA's associations.
- items - An array containing the actual data within the Exhibit. Each member of the array is an object with an arbitrary set of properties. Each item must have a property named "label", and can have any other properties as well. There are a few "special" properties that can be specified:
- label - As mentioned, this is required; it indicates the name that should be presented to the user. If the "id" property is not specified, the label will also be used as the unique identifier.
- id - This property provides a value to use as the item's unique identifier (similar to the published name in TRIRIGA). This can be used to differentiate between two items that have the same label (for example, two people named "John Smith" might have the same "label" property, but two different "id" values).
- type - This indicates the item's type, and is used in conjunction with the "types" object.
Of these core objects, only the "items" property is strictly required (containing the Exhibit data); the others are optional and serve to further define the nature and relationships of items in the Exhibit.
Building a Solution
We're going to model this data source structure within TRIRIGA as follows:
- devExhibit - This Business Object represents the Exhibit itself.
- devExhibitNameTX - The unique name for the Exhibit.
- devExhibitDescriptionTX - A brief description.
- devDocumentTX - A locator pointing to an HTML document in Document Manager. Our system will also allow the data to be retrieved directly (for use with externally hosted HTML documents).
- devUsernameTX/devPasswordTX - Credentials to use when retrieving the data from TRIRIGA.
- devCacheTimeNU - Time (in minutes) to cache the Exhibit contents for performance.
- devDataSource - This object encapsulates a TRIRIGA query that is used to provide data to the Exhibit; a single Exhibit can combine one or more Data Sources to produce its content.
- devQueryTX - Name of the TRIRIGA query that will provide the data. Column labels in the query will provide the property names for our Exhibit items.
- devModuleTX, devBusinessObjectTX - These specify the Module and Business Object to which the query applies.
- devDataSourceIdTX, devDataSourceNameTX, devDataSourceDescriptionTX - ID, name, and description for the Data Source.
- devTypeTX - The item type that will be used in Exhibit for records returned by this Data Source. In our example, this would be "Work Task".
- devPluralTX - The plural label that should be used for this item type (e.g., "Work Tasks").
- devProperty - Represents a property descriptor for a Data Source property.
- devPropertyIdTX - Identifier for the property.
- devPropertyNameTX - Name of the property; this should match the column names from the Data Source query.
- devValueTypeLI - The value type for the property (text, number, date, boolean, url, or item).
- devPropertyLabelTX - The label that Exhibit should apply to the property. If the property type is "item", this represents the item relationship.
- devReverseLabelTX - The reverse relationship for item properties.
Now that we've defined what Exhibits look like from the TRIRIGA side, we'll need to build a solution to present our content externally. What we'll create is a servlet-based system that will work as follows:
- Our servlet will receive a web request for an Exhibit by name (e.g., "/WorkTasks"). If the client sends the request with either a "data=true" parameter ("/WorkTasks?data=true") or a "data" path component ("/WorkTasks/data") then we will treat it as a request for the JSON-formatted data; otherwise, we will feed them the applicable HTML document from Document Manager.
- In addition to caching the Exhibit content, we will also cache the Exhibit definitions themselves to improve performance. If we have an Exhibit object matching the requested name, we can use that. Otherwise, we will retrieve the matching devExhibit object from TRIRIGA (along with its related devDataSource and devProperty objects).
- If the request is for the HTML document, we will retrieve the content from the Document record associated to the devExhibit object, and send that to the client.
- If the request is for the JSON data, we will either use the cached content from the Exhibit or run the related queries defined by the Data Source objects.
- The result will be formatted as JSON and sent to the client.
We can break this down further to identify the TRIRIGA-related operations that need to take place to achieve this:
- Retrieve the matching devExhibit Object - The runDynamicQuery BusinessConnect call is used to retrieve the devExhibit record, filtered on devExhibitNameTX. A second runDynamicQuery call is used to retrieve all devDataSource records associated to that devExhibit (using an association filter); we will also use associated display columns to retrieve the necessary fields from the devProperty records associated to the Data Sources (that way we don't have to make several follow-up calls to retrieve them later).
- Retrieve the HTML document - There isn't an API to retrieve Document Manager content currently; what we do here is use the HTTP session cookie that we are maintaining for our BusinessConnect calls to retrieve the document using HTTP. Once we have the record ID for the Document, we can extract it using the URI:
/WebProcess.srv?objectId=410000&actionId=410014&disp=false&documentID=RecordID
where "RecordID" is the record ID of the document. A standard HTTP GET request is made to TRIRIGA, passing the authenticated session cookie, and the response is funnelled back to the client.
- Retrieve the JSON data - We use the runNamedQuery BusinessConnect call (in conjunction with runNamedQueryContinue as needed) to run the queries specified by the devDataSource records. The result sets are merged using the "id" item property (or "label" if an ID is not provided), and marshalled into JSON for caching and subsequent return to the client.
Attached at the bottom of this article is "exhibit.zip", which contains the following:
- exhibit-om.zip - Object Migration package containing the objects described above, as well as some example records.
- EXHIBIT.properties - Configuration file for the middleware servlet; this should be edited for your environment, and copied into the "config" subdirectory of your TRIRIGA installation (alongside "TRIRIGAWEB.properties" and the rest of the TRIRIGA configuration files).
- exhibit.war - Middleware servlet. This should be deployed on your application server; for JBoss, you just need to copy this file into the "server/all/deploy" subdirectory under your JBoss installation. For other server types, consult your application server documentation.
Once you've got the solution installed, open your Data Browser and find the "Exhibit" manager. The Object Migration package contains a sample devExhibit record, which should look something like this (you'll need to link the Data Source; this can be done by revising the Exhibit, clicking "Find" on the query section and adding the Data Source, then publishing the Exhibit):
You can leave the "Username" and "Password" fields blank if desired (it will use the default credentials specified in the configuration file). Similarly, open the devDataSource record and link in the devProperty objects:
Once that's done, you should be able to point your browser at:
http://yourserver/exhibit/WorkTasks
(where "yourserver" is the server on which the Exhibit middleware servlet is deployed). This should display the example Work Task timeline as seen at the beginning of this article.
Additional Resources
The source code for the solution presented in this article is available at the triDeveloper code repository:
I highly recommend browsing through the examples on the Exhibit website:
More documentation on Exhibit is available at the SIMILE Project wiki:
There is also an active user community and Google Group, where you can ask questions and get answers:
|
|
