Eclipse BIRT Report Object Model (ROM)

ReportItem Element

# Element Overview

Abstract base element for all visual report items.

### Details

Display Name: | Report Item
Since: | 1.0
XML Element: | `None`
Extends: | ReportElement
Extendable: | No
Abstract: | Yes
Name Space: | Report Items
Name Requirement: | Optional
Allows User Properties: | Yes
Has Style: | Yes
Default Style: | None

### Property Summary

bookmark
  Defines this item as a hyperlink target.
boundDataColumns
  Bindings the data set column and expressions with the property values..
cube
dataBindingRef
dataSet
  The name of the data set that provides data for this item.
height
  Height of the item.
paramBindings
  Bindings between input parameters in the included design and values in the main design.
refTemplateParameter
  Name of the template parameter definition.
style
  Name of the style applied to this item.
toc
  A table of contents entry for this item.
visibility
  A list of visibility rules that determines when the item appears.
width
  Width of the item.
x
  The x (horizontal) position of the item.
y
  The y (vertical) position of the item.
zIndex

### Inherited Properties

comments, customXml, displayName, displayNameID, eventHandlerClass, extends, name, propertyMasks, userProperties, viewAction

### Description

ReportItem is the common base element for all visual report elements. Report items include a style. The style provides visual characteristics for anything that prints in a report: a section or report item.

Report items are positioned within the report based on a series of rules described in the ROM Layout Specification. The free-form item provides absolute (x, y) positioning, but most other containers provide some kinds of automated positioning. The report item provides properties for each kind of layout, but the properties are used only when appropriate. For example, every item can have an (x, y) position, but the position is ignored unless the item appears within a free-form container.

Each report item also has a private style. The private style is a separate element in the XML definition. However, within the UI and scripting, the style properties appear as though they were properties of this item itself.

#### Report Item Inheritance

Report items can extend other report items. However, to keep the system manageable, ROM allows a report item to extend only those items defined in a library. (Libraries are not yet available in Release 1.0.)

A report item cannot extend another report item that appears in the Body area of the report design.

These rules avoid complex designs such as having a container extend the container that contains itself. (A determined user can still create this scenario within a library, however.)

# Property Detail

## bookmark Property

Defines this item as a hyperlink target.

### Details

Type: | expression
Context: |
Expression Type: | string
Since: | 2.0
Required: | No
Display Name: | Bookmark
JavaScript Type: |
Default Value: | None
Inherited: | Yes
Runtime Settable: | Yes
Property Sheet Visibility: | Visible
Property Sheet Group: | Top

### Description

Many report items can be the target of hyperlinks. The bookmark is a string that uniquely identifies the item instance within the report. This property is an expression that evaluates to a string. If the string is blank or null, then the item has no bookmark. Bookmarks should be unique. If there are duplicates, the behavior of the hyperlink is undefined: it may jump to the first item with that name.

### See Also

Action property on labels, data items, images and other items.

## boundDataColumns Property

Bindings the data set column and expressions with the property values..

### Details

Type: | List of ComputedColumn Structures
Since: | 2.1
Required: | No
Display Name: | Bound data columns
JavaScript Type: |
Default Value: | None
Inherited: | Yes
Runtime Settable: | Yes
Property Sheet Visibility: | Hidden
Property Sheet Group: | Top

### Description

Property values of a report item can bind to a data set column or other expressions through bound data columns' names. If a data set column or expression are not bound in the data columns, the exeuction of the expression fails.

### See Also

## cube Property

### Details

Type: | Cube Reference
Since: | 2.2
Required: | No
Display Name: | Cube
JavaScript Type: |
Default Value: | None
Inherited: | Yes
Runtime Settable: | No
Property Sheet Visibility: | Visible
Property Sheet Group: | Top

## dataBindingRef Property

### Details

Type: | ReportItem Reference
Since: | 2.2
Required: | No
Display Name: | Data binding reference
JavaScript Type: |
Default Value: | None
Inherited: | Yes
Runtime Settable: | Yes
Property Sheet Visibility: | Visible
Property Sheet Group: | Top

## dataSet Property

The name of the data set that provides data for this item.

### Details

Type: | DataSet Reference
Since: | 1.0
Required: | No
Display Name: | Data set
JavaScript Type: |
Default Value: | None
Inherited: | Yes
Runtime Settable: | No
Property Sheet Visibility: | Visible
Property Sheet Group: | Top

### Description

Reference to the data set to use for this component. If blank, the data set is that defined for the enclosing list, table or other element. See derived elements for the use of the data set for that element.

The data set name is optional. If none is provided, then the report item "inherits" a data set. A report item used as a section automatically uses the first data set defined in the report design. This convenience exists to simplify the tasks for customers to create simple reports using the XML design format. A report item nested inside a container uses the data set for the container.

### See Also

Report Item `bindings` property

## height Property

Height of the item.

### Details

Type: | dimension
Since: | 1.0
Required: | No
Display Name: | Height
JavaScript Type: |
Default Value: | None
Inherited: | Yes
Runtime Settable: | Yes
Property Sheet Visibility: | Visible
Property Sheet Group: | Report Item

### Description

Height of the item. Some items have a dynamic size. In this case, this is the minimum height, or may be ignored altogether. The actual size in the printed report usually depends on the content, and may be larger than the height set here. For example, a data, label or text item will grow as tall as required to display its content.

### See Also

Report Item `width` property

## paramBindings Property

Bindings between input parameters in the included design and values in the main design.

### Details

Type: | List of ParamBinding Structures
Since: | 1.0
Required: | No
Display Name: | Parameter bindings
JavaScript Type: |
Default Value: | None
Inherited: | Yes
Runtime Settable: | Yes
Property Sheet Visibility: | Hidden
Property Sheet Group: | Top

### Description

A report item can bind to a data set as described in the data set property. A report item can pass information to the data set by providing bindings to input parameters of the data set. Each binding identifies an input parameter by name, and provides an expression that gives the value of the parameter.

### See Also

Report Item `dataSet` property

Data Set element, especially the Parameters property

## refTemplateParameter Property

Name of the template parameter definition.

### Details

Type: | TemplateParameterDefinition Reference
Since: | 2.0
Required: | No
Display Name: | Referred template parameter definition
JavaScript Type: |
Default Value: | None
Inherited: | No
Runtime Settable: | No
Property Sheet Visibility: | Hidden
Property Sheet Group: | Top

### Description

when a report item is created from an template element, this property will reference to the base template element definition.

## style Property

Name of the style applied to this item.

### Details

Type: | Style Reference
Since: | 1.0
Required: | No
Display Name: | Style
JavaScript Type: |
Default Value: | None
Inherited: | Yes
Runtime Settable: | No
Property Sheet Visibility: | Visible
Property Sheet Group: | Top

### Description

Report items provide many style properties. The style properties are defined in the ROM Styles Specification. An element can inherit its style properties from a parent element, from a named style, or from a style that identifies the context in which the item appears. This property provides the name of the shared style to use.

This item can also set the value of style properties. Properties set on this element "override" those inherited from a parent element or a shared style.

### See Also

Style element in the ROM Styles Specification.

## toc Property

A table of contents entry for this item.

### Details

Type: | TOCStructure Structure
Since: | 2.2
Required: | No
Display Name: | TOC
JavaScript Type: |
Default Value: | None
Inherited: | Yes
Runtime Settable: | Yes
Property Sheet Visibility: | Hidden
Property Sheet Group: | Top

### Description

A table of contents entry for this item. The TOC property defines an expression that returns a string that is to appear in the Table of Contents for this item or its container.

## visibility Property

A list of visibility rules that determines when the item appears.

### Details

Type: | List of HideRule Structures
Since: | reserved
Required: | No
Display Name: | Visibility
JavaScript Type: |
Default Value: | None
Inherited: | Yes
Runtime Settable: | No
Property Sheet Visibility: | Hidden
Property Sheet Group: | Top

### Description

The visibility rules control when the item appears in the report. An item can be completely hidden, in which case it won�t even be created in the Factory. For example, perhaps the Country item should appear for international customers, but not domestic customers. An item can also be hidden conditionally depending on the output format. For example, perhaps a hyperlink should appear when the report is viewed on the web, but not when it is printed.

### See Also

Visibility Rule structure for the details of the rules.

## width Property

Width of the item.

### Details

Type: | dimension
Since: | 1.0
Required: | No
Display Name: | Width
JavaScript Type: |
Default Value: | None
Inherited: | Yes
Runtime Settable: | Yes
Property Sheet Visibility: | Visible
Property Sheet Group: | Report Item

### Description

Width of the item. When an item appears as a section (a top-level bit of content within the report), the width property is often ignored, and is taken to be the width of the page. See the derived elements for details.

### See Also

Report Item `height` property

## x Property

The x (horizontal) position of the item.

### Details

Type: | dimension
Since: | reserved
Required: | No
Display Name: | X
JavaScript Type: |
Default Value: | None
Inherited: | Yes
Runtime Settable: | Yes
Property Sheet Visibility: | Hidden
Property Sheet Group: | Report Item

### Description

The x position of the item. This is an absolute dimension relative to from the left of the container. Dimensions include both a measure and units: "10in" or "5cm". The position can also be relative: "10%".

The position is used only for containers that provide absolute positioning. Such containers include the free-form container and the graphic master page. Otherwise, the position is computed automatically by the container, and this property is ignored.

### See Also

Dimension property type

Report Item `y` property

## y Property

The y (vertical) position of the item.

### Details

Type: | dimension
Since: | reserved
Required: | No
Display Name: | Y
JavaScript Type: |
Default Value: | None
Inherited: | Yes
Runtime Settable: | Yes
Property Sheet Visibility: | Hidden
Property Sheet Group: | Report Item

### Description

The x position of the item. This is an absolute dimension relative to from the top of the container. Dimensions include both a measure and units: "10in" or "5cm". The position can also be relative: "10%".

The position is used only for containers that provide absolute positioning. Such containers include the free-form container and the graphic master page. Otherwise, the position is computed automatically by the container, and this property is ignored.

### See Also

Dimension property type

Report Item `x` property

## zIndex Property

### Details

Type: | integer
Since: | 2.2
Required: | No
Display Name: | Z index
JavaScript Type: |
Default Value: | 0
Inherited: | Yes
Runtime Settable: | Yes
Property Sheet Visibility: | Visible
Property Sheet Group: | Top