TextualDisplay Developer's Guide

Authors:

Sergei Chevtsov, SEAL Development, Inc.

$Id: textdisp_dev_guide.html,v 1.5 2007/07/26 19:02:52 chevtsov Exp $

Copyright © 2007 SLAC

Abstract

This document describes how to use TextualDisplay from an Eclipse plugin. In a nutshell, TextualDisplay displays textual data on screen using XML serialization, transformation to XHTML, and rendering via CSS.

Status of this Document

This section describes the status of this document at the time of its publication.
This seems to be the final version.

Overview

We recommend you take the following steps:

1. Install TextualDisplay
2. Run an example application
3. Manually serialize an instance of your data to an XML document.
4. Write an XSLT stylesheet that transforms your XML document to an XHTML document.
5. Display your XHTML document in a web browser by writing a CSS stylesheet.
6. Embed your CSS stylesheet into your XSLT document.
7. Upload your XSLT document to a web server.
8. Call the TextualDisplay API from your plugin.

Installation

You get TextualDisplay as part of SEAL. In your plugin project, you need to add "edu.slac.stanford.seal.textdisp" as a required plugin.

Running the Textual Display example

• Run SEAL.
• In Eclipse main menu, select Window - Show View - Other... - Seal Examples - Textual Display Example.
  "Textual Display Example" is an application that displays one of the two sets of available data, depending on the status of the radio buttons. Through its simplicity, it demonstrates how TextualDisplay can benefit even the dumbest applications.
• Press the "Export to TextualDisplay" button to see TextualDisplay in action. In this example, it displays all data at the same time in various colors.

Object-to-XML serialization

• Create an instance of your data and pass it to ObjectSerializer#toXML(Object). We recommend that you use a small amount of data, so that the resulting XML is readable.
• Save the output XML- for instance, by printing it to System.out and copying the text to a file. From now on, we refer to this file as "your XML document".

Example code:
MyData myData = new MyData();
String xml = new ObjectSerializer.toXML(myData);
System.out.print(xml);

Notes:
ObjectSerializer#toXML(Object) is a delegate to an XStream method. XStream is a very simple, but flexible and powerful library to serialize objects to XML. It is highly configurable, so if you are not satisfied with your generated XML, e.g. you find the names of the elements too long, use ObjectSerializer#getXStream() to get access to the XStream API.

XML-to-XHTML transformation

• Write an XSLT stylesheet that tranforms your XML document to an XHTML document.
• Run the tranformation by passing your XML document and the XSLT stylesheet as strings to XMLUtil#transform(String, String). You can use SealUtil#readUrlContent(URL) to read contents of a file URL into a string.
  Save the result to a file, to which we refer as "your XHTML document" from now on.

Example code:
MyData myData = new MyData();
String xml = new ObjectSerializer.toXML(myData);
String xslt = SealUtil.readUrlContent(new File("my_xslt.file").toURL());
String xhtml = new XMLUtil().transform(xml, xslt);
System.out.print(xhtml);

CSS stylesheet

• Open your XHTML document in a web browser. In 99% of all cases, this won't be what you want.
• Write a CSS stylesheet for your XHTML document. Go to previous step, or even modify your XSLT document, until you are satisfied with the result.

Embed CSS into XSLT document

• We recommend that you embed your CSS stylesheet directly into your XSLT document through the HTML element <style>.

Upload XSLT

• Copy your XSLT document to /afs/slac/g/lcls/docs/physics/seal/td_stylesheets/
• Make note of the corresponding URL, e.g.
  http://www.slac.stanford.edu/grp/lcls/controls/docs/physics/seal/td_stylesheets/myXslt.xsl

Call TextualDisplay

• Get an instance of edu.slac.stanford.seal.textdisp.TextDispPlugin via TextDispPlugin#getDefault() .
• In your Eclipse plugin, where you want to call TextualDisplay, pass your real data object and the URL of your XSLT document to TextDispPlugin#displayData(Object, URL)

Example code:
MyData myData = new MyData();
URL myXsltUrl = new URL("http://my_xslt.xsl");
TextDispPlugin.getDefault().displayData(myData, myXsltUrl);

Notes:
We urge you not to hardcode the URL of your XSLT document. Instead, you can, for instance, use Eclipse's String externalization mechanism.

References

XStream

http://xstream.codehaus.org

XSLT Tutorial

http://w3schools.com/xsl/xsl_transformation.asp

CSS Tutorial

http://w3schools.com/css/default.asp