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: | LayoutModule
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.
externalMetadata
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.
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

Name | Display Name | Value | Description
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 Data Security
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.

## externalMetadata Property

### Details

Type: | xml
Since: | 2.6
Required: | No
Display Name: | External Meta Data
JavaScript Type: |
Default Value: | None
Inherited: | Yes
Runtime Settable: | Yes
Property Sheet Visibility: | Visible
Property Sheet Group: | Top

## 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

Name | Display Name | Value | Description
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:

- For each library, in the order that the library is included:

- Locate, read and execute the imported scripts in the order they appear in the Code Modules element.
- Execute the `initialize` script.

- For the report design itself.

- Locate, read and execute the imported scripts in the order they appear in the Code Modules element.
- Execute the init script.

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

## 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:

- All report items in the component area must have a name. (This rule applies only to items directly in the component area, not to items nested inside of other items.)
- All report items share a single name space, including those in the Components and Body.
- Items in the Components area can extend from other items in the Components area of the same type. In the design file, the base components must physically appear before derived items.
- Any type of report item can appear in the Components area.
- Only report items can appear in the components area. Master pages, styles, data sets, data sources, parameters and other elements cannot appear.
- Report items in the components area can contain other items if their definition allows. For example, a grid can contain other items.

## 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