Eclipse BIRT Report Object Model (ROM)

Data Element

# Element Overview

Displays a data set or computed value with optional formatting.

### Details

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

### Property Summary

action
  Optional hyperlink defined for the data item.
helpText
  Optional tool-tip text that appears when the user hovers the cursor over the item.
helpTextID
resultSetColumn
  The bound column name refers to the value to display in the item.

### Method Summary

onCreate
  Script executed when the element is created in the Factory.
onPageBreak
onPrepare
  It is for a script startup phase. No data binding yet. The design of an element can be changed here.
onRender
  Script executed when the element is prepared for rendering in the Presentation engine.

### Inherited Properties

ACLExpression, allowExport, bookmark, bookmarkDisplayName, boundDataColumns, cascadeACL, comments, cube, customXml, dataBindingRef, dataSet, displayName, displayNameID, eventHandlerClass, extends, height, multiViews, name, newHandlerOnEachEvent, paramBindings, propertyMasks, pushDown, refTemplateParameter, style, theme, toc, userProperties, viewAction, visibility, width, x, y, zIndex

### Style Properties

backgroundAttachment, backgroundColor, backgroundImage, backgroundPositionX, backgroundPositionY, backgroundRepeat, bidiTextDirection, borderBottomColor, borderBottomStyle, borderBottomWidth, borderLeftColor, borderLeftStyle, borderLeftWidth, borderRightColor, borderRightStyle, borderRightWidth, borderTopColor, borderTopStyle, borderTopWidth, canShrink, color, dateTimeFormat, display, fontFamily, fontSize, fontStyle, fontVariant, fontWeight, highlightRules, letterSpacing, lineHeight, mapRules, marginBottom, marginLeft, marginRight, marginTop, masterPage, numberAlign, numberFormat, orphans, overflow, paddingBottom, paddingLeft, paddingRight, paddingTop, pageBreakAfter, pageBreakBefore, pageBreakInside, showIfBlank, stringFormat, textAlign, textLineThrough, textOverline, textTransform, textUnderline, verticalAlign, whiteSpace, widows, wordSpacing

### Description

A data element displays data from a data set, an expression, a parameter, etc. Data items display the value of a column, parameter or expression. Data items are for use with grids, containers, matrices, tables and other items that need a short, discrete data value.

Data items allow Java-like multi-part formats: One of the common formats used by some people is: #,##0_);(#,##0);"---". See the Style element for a description of the available styles.

BIRT applies one of the predefined styles depending on the data value of the item. If the expression returns a number, then BIRT applies the `number` style. If the expression returns a string, then BIRT applies the `string` style. And, if the expression returns a date, then BIRT applies the `date` style.

### See Also

Label element

Multi-line Data element

Style element

# Property Detail

## action Property

Optional hyperlink defined for the data item.

### Details

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

### Description

Optional hyperlink defined for the data item. Like the value expression, the hyperlink is computed, and can link to a different resource for each data item instance.

### See Also

Action structure

## helpText Property

Optional tool-tip text that appears when the user hovers the cursor over the item.

### Details

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

### Description

Reports often display large amounts of data on a single page. Data items are often short. While this works well once the user is familiar with the meaning of each data string/value, it can make the report confusing to the first-time user. Help-text helps bridge the gap. It allows the user to display a number, such as the Return on Investment (ROI) for an asset in the report. If the user needs more information, he can hover the cursor over the label and help text will appear that says something like, "Return on Investment: defined as the ratio of profit to funds invested."

The help text is optional. If no text is present, then no tool-tip text will appear. The help text can be externalized. The help text is static, it cannot vary for each data item.

## helpTextID Property

### Details

Type: | resourceKey
Since: | 1.0
Required: | No
Display Name: | Help text key
JavaScript Type: |
Default Value: | None
Inherited: | Yes
Runtime Settable: | Yes
Property Sheet Visibility: | Visible
Property Sheet Group: | Top

## resultSetColumn Property

The bound column name refers to the value to display in the item.

### Details

Type: | string
Since: | 2.1
Required: | No
Display Name: | Result set column
JavaScript Type: |
Default Value: | None
Inherited: | Yes
Runtime Settable: | Yes
Property Sheet Visibility: | Visible
Property Sheet Group: | Top

### Description

The bound column name refers to the value to display in the item. Through the boudn column, it can also reference a report parameter, a formula, a special value or other data item.

The expression is usually evaluated when the report is rendered, not in the Factory, though it may be evaluated in the Factory also. Expressions should depend only on variables and objects available both in the Factory and Presentation Engine. See the ROM Scripting Specification for details.

BIRT automatically determines the type of formatting to apply based on the actual return value of each expression. If the return value is a Number, BIRT applies numeric formatting. If the return value is a Date, BIRT applies date/time formatting. If the return value is a String, BIRT applies string formatting. The data item itself does not have a type; the type is computed independently for each and every data item based on the return value of this expression.

# Method Detail

## onCreate Method

Script executed when the element is created in the Factory.

### Synopsis

`None obj.onCreate( )`

### Details

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

### Description

Executed when the element is created in the Factory. Called after the item is created, but before the item is saved to the report document file. See the scripting spec for additional information about this script. Applications should perform visual customization in the on-render script instead.

## onPageBreak Method

### Synopsis

`None obj.onPageBreak( )`

### Details

Since: | 2.1
Context: | presentation
Arguments: | None
Return Type: | None

## onPrepare Method

It is for a script startup phase. No data binding yet. The design of an element can be changed here.

### Synopsis

`None obj.onPrepare( )`

### Details

Since: | 2.0
Context: | startup
Arguments: | None
Return Type: | None

### Description

It is for a script startup phase. No data binding yet. The design of an element can be changed here.

## onRender Method

Script executed when the element is prepared for rendering in the Presentation engine.

### Synopsis

`None obj.onRender( )`

### Details

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

### Description

Executed when the element is prepared for rendering in the Presentation engine. Changes made to the element are written to the target output format, but not saved to the report document file. This is the preferred place for visual customizations.