Eclipse BIRT Report Object Model (ROM)

ReportDesign Element

Element Overview

The report design element represents report as a whole.

Details

Display Name: Report Design
Since: 1.0
XML Element: report
Extends: Module
Extendable: No
Abstract: No
Name Space: None
Name Requirement: Not Supported
Allows User Properties: Yes
Has Style: No

Property Summary

ACLExpression
bidiLayoutOrientation
cascadeACL
cheatSheet
A string containing the file name of the cheat sheet.
cssStyleSheets
dataObjects
displayName
Display name of the report design
displayNameID
Resource key for the localizable display name property.
enableACL
eventHandlerClass
The full qulified name of the event handler class.
iconFile
The design icon/thumbnail file path
imageDPI
layoutPreference
locale
newHandlerOnEachEvent
pageVariables
refreshRate
The refresh rate when viewing the report.
thumbnail

Method Summary

afterFactory
Perform initialization before opening the report document for writing.
afterRender
Called after completing a presentation time action.
beforeFactory
Perform initialization before opening the report document for writing.
beforeRender
Called before starting a presentation time action.
initialize
Called when the report starts executing in either the Factory or Presentation engine.
onContentUpdate
onPageEnd
onPageStart

Slot Summary

styles
List of user-defined styles used to format elements in the report.
parameters
A list of Parameter elements that describe the data that the user can enter when running the report.
dataSources
The connections used by the report.
dataSets
Data sets (queries) defined in the design.
pageSetup
The layout of the master pages within the report.
components
Reusable report items defined in this design. Report items can extend these items. Defines a "private library" for this design.
body
The visual layout sections within the report.
scratchPad
TBD
templateParameterDefinitions
Stores the reusable template definitions.
cubes

Inherited Properties

author, base, colorPalette, comments, configVars, createdBy, description, descriptionID, helpGuide, images, includeResource, includeScripts, libraries, propertyBindings, scriptLibs, subject, theme, title, titleID, units

Description

The report design element contains the information about a report design. It represents the entire set of design information stored in a BIRT report design file.

The report design defines properties that describe the design as a whole. Report design properties do not inherit because a design cannot extend another design.

Scripting Summary

Runtime object: report (global variable)

Design object: report.design

See Also

Library element

Property Detail

ACLExpression Property

Details

Type: expression
Context:
Expression Type: None
Since: 2.3
Required: No
Display Name: ACL expression
JavaScript Type:
Default Value: None
Inherited: Yes
Runtime Settable: Yes
Property Sheet Visibility: Hidden
Property Sheet Group: Top

bidiLayoutOrientation Property

Details

Type: choice (bidiDirection)
Since: 2.3
Required: No
Display Name: Report orientation
JavaScript Type:
Default Value: ltr
Inherited: No
Runtime Settable: Yes
Property Sheet Visibility: Visible
Property Sheet Group: Top

Choices

NameDisplay Name ValueDescription
ltr Left To Right ltr
rtl Right To Left rtl


cascadeACL Property

Details

Type: boolean
Since: 2.3
Required: No
Display Name: Cascade ACL
JavaScript Type:
Default Value: true
Inherited: Yes
Runtime Settable: Yes
Property Sheet Visibility: Hidden
Property Sheet Group: Top

cheatSheet Property

A string containing the file name of the cheat sheet.

Details

Type: string
Since: 2.0
Required: No
Display Name: Cheat sheet
JavaScript Type:
Default Value: None
Inherited: Yes
Runtime Settable: No
Property Sheet Visibility: Visible
Property Sheet Group: Top

Description

A string containing the file name of the cheat sheet used with this design.


cssStyleSheets Property

Details

Type: List of IncludedCssStyleSheet Structures
Since: 2.2
Required: No
Display Name: Css style sheets
JavaScript Type:
Default Value: None
Inherited: No
Runtime Settable: No
Property Sheet Visibility: Hidden
Property Sheet Group: Top

dataObjects Property

Details

Type: List of contentElements
Since: 2.5
Required: No
Display Name: Data objects
JavaScript Type:
Default Value: None
Inherited: Yes
Runtime Settable: Yes
Property Sheet Visibility: Hidden
Property Sheet Group: Top

displayName Property

Display name of the report design

Details

Type: string
Since: 2.0
Required: No
Display Name: Display name
JavaScript Type:
Default Value: None
Inherited: Yes
Runtime Settable: No
Property Sheet Visibility: Visible
Property Sheet Group: Top

Description

The localized display name for the report design.


displayNameID Property

Resource key for the localizable display name property.

Details

Type: resourceKey
Since: 2.0
Required: No
Display Name: Display name key
JavaScript Type:
Default Value: None
Inherited: Yes
Runtime Settable: Yes
Property Sheet Visibility: Visible
Property Sheet Group: Top

Description

Resource bundle key for the display name property, the localized display name value will be looked up from a resource file relating to the current locale.


enableACL Property

Details

Type: boolean
Since: 2.3
Required: No
Display Name: Enable ACL
JavaScript Type:
Default Value: false
Inherited: Yes
Runtime Settable: Yes
Property Sheet Visibility: Hidden
Property Sheet Group: Top

eventHandlerClass Property

The full qulified name of the event handler class.

Details

Type: string
Since: 2.0
Required: No
Display Name: Event handler class
JavaScript Type:
Default Value: None
Inherited: Yes
Runtime Settable: Yes
Property Sheet Visibility: Visible
Property Sheet Group: Top

Description

Full quilified name of the event handler class, used to specify an external Java class which define the scripting behavior that will be executed at runtime.


iconFile Property

The design icon/thumbnail file path

Details

Type: string
Since: 2.0
Required: No
Display Name: Icon file
JavaScript Type:
Default Value: None
Inherited: Yes
Runtime Settable: No
Property Sheet Visibility: Visible
Property Sheet Group: Top

Description

The design icon/thumbnail file path


imageDPI Property

Details

Type: integer
Since: 2.5
Required: No
Display Name: Image DPI
JavaScript Type:
Default Value: None
Inherited: Yes
Runtime Settable: Yes
Property Sheet Visibility: Visible
Property Sheet Group: Top

layoutPreference Property

Details

Type: choice (reportLayoutPreference)
Since: 2.2
Required: No
Display Name: Layout preference
JavaScript Type:
Default Value: fixed layout
Inherited: Yes
Runtime Settable: No
Property Sheet Visibility: Visible
Property Sheet Group: Top

Choices

NameDisplay Name ValueDescription
fixed layout Fixed Layout fixed layout
auto layout Auto Layout auto layout


locale Property

Details

Type: locale
Since: 2.5
Required: No
Display Name: Locale
JavaScript Type:
Default Value: None
Inherited: Yes
Runtime Settable: Yes
Property Sheet Visibility: Visible
Property Sheet Group: Top

newHandlerOnEachEvent Property

Details

Type: boolean
Since: 2.5
Required: No
Display Name: New handler on each event
JavaScript Type:
Default Value: false
Inherited: Yes
Runtime Settable: Yes
Property Sheet Visibility: Visible
Property Sheet Group: Top

pageVariables Property

Details

Type: List of contentElements
Since: 2.5
Required: No
Display Name: Page variables
JavaScript Type:
Default Value: None
Inherited: Yes
Runtime Settable: Yes
Property Sheet Visibility: Hidden
Property Sheet Group: Top

refreshRate Property

The refresh rate when viewing the report.

Details

Type: integer
Since: reserved
Required: No
Display Name: Refresh rate
JavaScript Type:
Default Value: 0 (the report does not refresh)
Inherited: No
Runtime Settable: No
Property Sheet Visibility: Hidden
Property Sheet Group: Top

Description

The refresh rate when viewing the report. The viewer will automatically rerun and redisplay the report. The rate is given in seconds. A rate of 0 means no refresh.


thumbnail Property

Details

Type: literalString
Since: 2.1
Required: No
Display Name: Thumbnail
JavaScript Type:
Default Value: None
Inherited: Yes
Runtime Settable: No
Property Sheet Visibility: Hidden
Property Sheet Group: Top

Method Detail

afterFactory Method

Perform initialization before opening the report document for writing.

Synopsis

None obj.afterFactory( )

Details

Since: 1.0
Context: factory
Arguments: None
Return Type: None

Description

Called at the end of the Factory after closing the report document (if any). This is the last method called in the Factory.

See Also

beforeFactory method


afterRender Method

Called after completing a presentation time action.

Synopsis

None obj.afterRender( )

Details

Since: 1.0
Context: presentation
Arguments: None
Return Type: None

Description

BIRT calls this method at the completion of each presentation-time activity such as convert a page, print a report, extract data, etc. Code is likely to be specific to the deployment platform.

If the report is being run and rendered in a single pass, then the call to afterFactory will precede the call to afterRender.

See Also

beforeRender method


beforeFactory Method

Perform initialization before opening the report document for writing.

Synopsis

None obj.beforeFactory( )

Details

Since: 1.0
Context: startup
Arguments: None
Return Type: None

Description

Called at the start of the Factory after the initialize( ) method and before opening the report document (if any).

See Also

Module element initialize method

afterFactory method


beforeRender Method

Called before starting a presentation time action.

Synopsis

None obj.beforeRender( )

Details

Since: 1.0
Context: presentation
Arguments: None
Return Type: None

Description

BIRT calls this method at the start of each presentation-time activity such as convert a page, print a report, extract data, etc. Presentation activities are usually done in repose to a client request coming into the Presentation Engine. Code is likely to be specific to the deployment platform.

BIRT may cache the same report session across multiple render actions. For example, if a user wants to view pages 1 and 2, see the table of contents, then do a search, the Presentation Engine may elect to keep the report loaded and the JavaScript session in effect. This allows an application to perform costly presentation-time initialization once, simply keep a flag that indicates whether initialization has already been done by another render action.

If the report is being run and rendered in a single pass, then this method is called after the call to beforeFactory. If the rendering operation is being done on a report previously created, then this method is called just after the initialize method.

The Presentation Engine may choose to cache a report design and script session across multiple render requests. In this case, each render operation will trigger a call to beforeRender and afterRender. The initialize method will be called only when the report is first loaded.

See Also

initialize method

afterRender method


initialize Method

Called when the report starts executing in either the Factory or Presentation engine.

Synopsis

None obj.initialize( )

Details

Since: 1.0
Context: startup
Arguments: None
Return Type: None

Description

BIRT calls this method before calling any other method in the design.

BIRT calls this method at the start of the Factory and Presentation engines, just after loading the imports, before opening the report document. Implement this method to define global functions, objects, Java imports and other resources used throughout the report.

Libraries can also contain an init script and imports. BIRT executes these scripts in the following order:

In general, the initialize method of a report design or library can reference resources defined in the initialize script of any included libraries, but not visa-versa. This is the generally accepted meaning of an include.

See Also

Report Design beforeFactory method

Report Design beforeRender method


onContentUpdate Method

Synopsis

None obj.onContentUpdate( )

Details

Since: 2.5
Context: client
Arguments: None
Return Type: None

onPageEnd Method

Synopsis

None obj.onPageEnd( )

Details

Since: 2.5
Context: factory
Arguments: None
Return Type: None

onPageStart Method

Synopsis

None obj.onPageStart( )

Details

Since: 2.5
Context: factory
Arguments: None
Return Type: None

Slot Detail

styles Slot

List of user-defined styles used to format elements in the report.

Details

Display Name: Styles
Since: 1.0
XML Element: styles
Contents: List of Style

Description

User-defined styles used to format elements in the report. Each style must have a unique name within the set of styles for this report.


parameters Slot

A list of Parameter elements that describe the data that the user can enter when running the report.

Details

Display Name: Parameters
Since: 1.0
XML Element: parameters
Contents: List of Parameter, ParameterGroup

Description

A list of parameter elements that describe the data that the user can enter when running the report. BIRT supports four kinds of parameters identified above. The design can also include parameter groups that organize parameters visually.

The order of parameters within this slot in the design file determines the order that they will appear in the requester UI.

The parameters property provides a "flattened" list of parameters. Each parameter identifies the group (if any) to which it belongs.

Parameter values are also available using the params global variable.


dataSources Slot

The connections used by the report.

Details

Display Name: Data Sources
Since: 1.0
XML Element: data-sources
Contents: List of DataSource

Description

This slot holds the list of data sources defined within the report itself. Each data source must have a unique name. The order of items within this slot is unimportant.


dataSets Slot

Data sets (queries) defined in the design.

Details

Display Name: Data Sets
Since: 1.0
XML Element: data-sets
Contents: List of DataSet, TemplateDataSet

Description

This slot holds the list of data sets defined within the report itself. Each data set must have a unique name. The order of items within this slot is unimportant.


pageSetup Slot

The layout of the master pages within the report.

Details

Display Name: Page Setup
Since: 1.0
XML Element: page-setup
Contents: List of GraphicMasterPage, SimpleMasterPage

Description

The page setup defines the way that the report will appear when printed. It consists of a master page that defines the page size, page "decoration", margins and so on. Some reports need to use different master pages, perhaps to have the first page of the report appear in letterhead, with the remaining pages on plain paper. Other reports may be printed and bound, requiring differing page layout for the left and right pages.

A report can omit the page setup information. If so, page setup is taken from a library, if provided. If the library is not provided, or does not have a page setup, or the master page does not have page dimensions, then the setup comes from BIRT preferences, or from locale-specific defaults.

If the user lists multiple master pages, but no page sequences, then BIRT uses the first master page by default. If the user defines one or more page sequences, then BIRT uses the first page sequence by default. Other than these two cases, the order of elements within the page setup slot is unimportant.

This slot defines a name space; the name of each master page and page sequence must be unique across the set of other page setup elements.

Only the simple master page is available in the first release, and the design can contain at most one simple master page in the first release.

The page setup can contain zero or more master pages (of either type) and zero or more page sequences (of either type). The simplest report provides no master page. It will appear with the default pages size and margins, and with no page header or footer.

See Also

Library element


components Slot

Reusable report items defined in this design. Report items can extend these items. Defines a "private library" for this design.

Details

Display Name: Components
Since: reserved
XML Element: components
Contents: List of Data, ExtendedItem, FreeForm, Grid, Image, Label, Line, List, Rectangle, Table, Text, TextData

Description

This slot defines reusable report items defined in this design. Report items can extend these items.

A report developer may want to use the same image, text, label or other item in several places within in the report. Instead of copying & pasting, the developer can instead define the element once in the components slot. Then, he can use the component to create the various instances.

Using a reusable component helps reduce maintenance costs because changes are made in only one place, rather than across several copies.

This slot defines a "private library" for this design. Components that are used by several reports appear in a "shared" library file.

The following rules apply to the components slot:


body Slot

The visual layout sections within the report.

Details

Display Name: Body
Since: 1.0
XML Element: body
Contents: List of AutoText, Data, ExtendedItem, FreeForm, Grid, Image, Label, List, Table, TemplateReportItem, Text, TextData

Description

The body portion of a design contains a list of the visual report content. Content is made up of one or more sections. A section is a report item that fills the width of the page. Sections represent relatively independent divisions within the report. In CSS terminology, a section is a block-level element.

The simplest design contains a single section. However, sophisticated designs can contain any number of sections.

The body contains any number of sections, in any order.


scratchPad Slot

TBD

Details

Display Name: Scratch Pad
Since: reserved
XML Element: scratch-pad
Contents: List of Data, ExtendedItem, FreeForm, Grid, Image, Label, Line, List, Rectangle, Table, Text, TextData

Description

TBD


templateParameterDefinitions Slot

Stores the reusable template definitions.

Details

Display Name: Template Parameter Definitions
Since: 2.0
XML Element: template-parameter-definitions
Contents: List of TemplateParameterDefinition

Description

Slot that stores the reusable template definitions, report items/data set/data source can be created from a template definition


cubes Slot

Details

Display Name: Cube Elements
Since: 2.2
XML Element: cubes
Contents: List of Cube