Understanding the Report Object Model
- About the ROM specification
- About the ROM schema
- About the rom.def file
- About the primary ROM elements
- About the report item elements
- About the data elements
This chapter is from the book
This chapter is from the book
This chapter is from the book
About the ROM specification
The ROM specification defines a set of XML elements that describe the visual and non-visual components of a report. Visual components, known as report items, appear in a report, for example, data items, labels, and tables. ROM provides the framework for extended report items such as charts and cross tabs. Non-visual components support report items, but do not appear in a report, for example, data cubes, data sets, data sources, report parameters, and styles. The XML file that BIRT Report Designer generates to describe a report consists entirely of ROM elements. The ROM specification defines the elements, their properties, and an element’s relationship to other elements. ROM elements describe:
- The data source and query with which to populate a report
- The placement, size, style, and structure of report items
- The report page layout
The report design file contains XML elements that describe the ROM elements that make up the report design. The BIRT design engine interprets the ROM elements using the ROM specification and the design.xsd file. This file is located at http://www.eclipse.org/birt/2005/design and also in the plug-in, org.eclipse.birt.report.model. BIRT Report Designer displays the elements that the design engine interprets. Visual report items appear in the layout window. Data-related items such as cubes, data sets, and report parameters appear in the data explorer. All elements in the report design appear in the Outline view.
ROM properties
ROM elements can have properties and every property has a type. Property types are similar to variable types in programming or data types in database terminology. Like variables and data types, ROM property types can be simple or complex. Simple types include string, number, dimension, color, and so forth. Complex types include structure and list. A complex type contains more than one component. For example, a text type contains both the text and a resource key used for internationalizing the text.
The components of a ROM property are:
Property values
Most elements have simple properties that are defined by a name-value pair. There are several property types, described later in this section.
User-defined property definitions
The userProperties array provides a way for users to define custom properties. Each item in the array is a UserProperty object.
Executable expressions
The methods array is an associative array of method names. The method name is the key into the array. The return value is a string that contains the method text.
The property types defined in ROM include:
property
This property type is the simplest and most common property type. A property definition of this type has the following syntax:
<property name="propName">value</property>
property-list
This property type defines a set of properties, such as custom colors. A property definition of the property-list type has the following syntax:
<property-list name="propName"> [ <structure> ... </structure> ] * </property-list>
xml-property
This property type defines custom XML. A property definition of the xml-property type has the following syntax:
<xml-property name="propName">value</xml-property>
expression
The value for this property type is an expression. A property definition of the expression type has the following syntax:
<expression name="propName">value</expression>
structure
This property is a collection of two or more properties. A property definition of the structure type has the following syntax:
<structure name="propName"> <property name="member1">value1</property> <property name="member2">value2</property> </structure>
ROM slots
A ROM slot is a collection of identically typed elements. For example, a report element has a slot of style elements that comprise all the styles available to the report.
ROM methods
A ROM element can have one or more methods, called event handlers. BIRT fires many different events during the course of executing a report. When BIRT fires an event, the appropriate event handler is executed to handle the event. By default, event handlers are empty methods that do nothing. By supplying code for an event handler, a report developer can customize and extend the functionality of BIRT. Supplying code for an event handler is called scripting. An event handler can be scripted in either JavaScript or Java.
Report items can have four events: onPrepare, onCreate, onPageBreak, and onRender. Each of these events fires during different phases of report creation. The onPrepare event fires in the preparation phase. The onCreate event fires during the generation phase. The onRender and onPageBreak events fire during the presentation phase.
ROM styles
The ROM style system is based on cascading style sheets (CSS), where a style set in a container cascades to its contents. The Report element contains all other elements, so the style property of the Report element defines the default style for the entire report. An element within the report can override the default style. A report developer can either choose a style from a defined set of styles or create a new style. Typical style attributes include color, text size, alignment, background image, and so forth. For more information about the styles, see the ROM reference in the BIRT online help.