Package com.ibm.etools.pd.widget.viewer

Provides classes for creating document generators which can produce graphics based on dynamic content data and render those graphics in various formats, for example, Scalable Vector Graphics (SVG), as appropriate for the device on which they are to be displayed, for example, a web browser.

See:
          Description

Interface Summary
IDataInputConstants The IDataInputConstants interface provides constants which map to the tag names defined in the data input schemas and other miscellaneous values used by the classes.
IDataInputProcessingExceptionCodes The IDataInputProcessingExceptionCodes interface holds the error codes used when raising exceptions of type DataInputProcessingException.
IGraphicDocumentGenerator The IGraphicDocumentGenerator interface provides users with access to objects which generate graphic visualizations of (potentially) dynamic input data.
IGraphicDocumentStyle The IGraphicDocumentStyle interface defines the default CSS style rules, colour palettes, and other basic or default style attributes of the graphic.
IGraphicTypeConstants The IGraphicTypeConstants interface contains constants denoting the known generated types.
 

Class Summary
CommonDataRetriever Common data retrieval methods which retrieve data of interest to SVGLineChart, SVGBarChart, SVGStackBarChart, SVGPieChart and SVGMeter from documents which conform to the documented data input schemas.
DOMDataRetriever Convenience class for accessing DOM elements and attributes.
ECMAScriptGenerator ECMAScriptGenerator generates the (ECMA 1.0-compliant) JavaScript functions needed to support browser-based user interaction with GraphicDocumentGenerators that generate Scalable Vector Graphics (SVG).
GraphicDocumentGenerator GraphicDocumentGenerator is an abstract base class for classes which take content data input as Document Object Model (DOM) objects and then generate DOM objects which represent graphic visualizations of that content data.
MeterDataRetriever Data retrieval methods which retrieve data of interest to SVGMeter from documents which conform to the documented data input schemas.
PieChartDataRetriever Data retrieval methods which retrieve data of interest to SVGPieChart from documents which conform to the documented data input schemas.
SVGBarChart SVGBarChart generates a bar chart graphic DOM using Scalable Vector Graphics (SVG).
SVGDocumentGenerator Abstract base class SVGDocumentGenerator implements document-building methods which are common to SVG document-based charts.
SVGDocumentGeneratorFactory Convenience class for creating SVG document generators.
SVGLineChart SVGLineChart generates a line chart graphic DOM using Scalable Vector Graphics (SVG).
SVGMeter SVGMeter generates a meter graphic DOM using Scalable Vector Graphics (SVG).
SVGPieChart SVGPieChart generates a pie chart graphic DOM using Scalable Vector Graphics (SVG).
SVGStackBarChart SVGStackBarChart generates a stacked bar chart graphic DOM using Scalable Vector Graphics (SVG).
SVGXYChart SVGXYChart is an abstract base class providing implementation of methods common to classes generating SVG graphics which have x,y axes.
XYChartDataRetriever Data retrieval methods which retrieve data of interest to SVGLineChart, SVGBarChart and SVGStackBarChart from documents which conform to the documented data input schemas.
 

Exception Summary
DataInputProcessingException Signals that the XML data cannot be processed by the consuming widget.
 

Package com.ibm.etools.pd.widget.viewer Description

Provides classes for creating document generators which can produce graphics based on dynamic content data and render those graphics in various formats, for example, Scalable Vector Graphics (SVG), as appropriate for the device on which they are to be displayed, for example, a web browser.

These generators require content data input in the form of a data source object which implements the org.w3c.dom.Document interface and which conforms to the generator schema. In this version, the generators can produce SVG 1.0 renderings of the graphic objects. These detail a visualization of the input data and support some browser-based user interactions, such as setting color and font preferences. The generated graphic can be saved to a file on the local machine where the generator is executing and then used as a resource wherever the format is supported.

It is expected (although not prescribed) that the host environment for the generators will be a web server and that Java Server Pages (JSP) or servlets will be the technology used. In this context, the generators are beans which can be instantiated with the "useBean" tag. Once the data source is specified, a graphic can be generated, serialized to the local machine and then immediately embedded in the response HTML using the "object" tag. If content data is dynamically updated, reloading the page will cause the bean to generate another graphic on the updated data.

There are a number of properties belonging to the generated graphic which can be configured. These include:

Specifying these properties programmatically overrides any provided defaults as well as any specifications of same which are present in the content data as may be allowed by the schema for the graphic type. To override, setters for these properties must be called subsequent to calling the setters for the configuration and/or data update documents.

Default Values
Both width and height have default values assigned which are dependent on the graphic type.
The default pixel height for graphic types currently available is 300.
The default pixel width for this group varies with the type as follows:

If a title, legend title, or timestamp prefix is not specified (in the content data or programmatically), none will be displayed.
The default font family is "Arial, sans-serif". If a font is specified, it will be prepended to the default to provide the browser with another option should the specified font not be available.

If a graphic supports a legend and it is not suppressed, it will be displayed if legend data is provided.

User Preferences
User preference pages are provided for the current graphic types. The preference page is launched by clicking on the icon in the upper right corner of the SVG graphic. When the page appears, the current style preferences showing in the SVG graphic are selected. Users may make changes to these preferences values and then use the "Preview" button to immediately see the effect in the SVG graphic. When satisfied with the selected changes, "OK" updates the SVG graphic with those changes while "Cancel" resets the style preferences to the current values of the SVG graphic. Note that there is support for showing custom color palettes which have been added to the SVG graphic in the preference page - the maximum number of colors allowed in a particular palette is currently 15. There is no checking done on custom palette colors.

Data Input and Validation
Graphic generators attempt to retrieve the required and optional data. The meaning of "required" varies with the type of graphic and is documented (see "Schema mappings"). Configuration data is optional and can be specified in the Document object passed either to the setConfigDocument(Document) method or to the setDataDocument(Document) method. Note, however, that the Document object containing the actual data must be passed in a call to setDataDocument(Document); otherwise, an exception is thrown. A DataInputProcessingException is thrown whenever required data cannot be retrieved and whenever retrieved (required and optional) data cannot be processed. These exceptions contain information which indicates where the failure occurred. It is assumed that all retrieved data is valid and complete. It is left to the data provider and the page designer to ensure that the graphic space occupied by the data is aesthetically pleasing.

Related Documentation

For schema information, see: