Eclipse BIRT Report Object Model (ROM)

Grid Element

Element Overview

Represents a Grid item, it's divided into a series of rows and columns.

Details

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

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.

Slot Summary

columns
Describes the columns that make up the grid.
rows
Any number of row entries.

Inherited Properties

bookmark, boundDataColumns, comments, cube, customXml, dataBindingRef, dataSet, displayName, displayNameID, eventHandlerClass, extends, height, name, paramBindings, propertyMasks, refTemplateParameter, style, toc, userProperties, viewAction, visibility, width, x, y, zIndex

Style Properties

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

Description

A grid item contains a set of report items, and the items are arranged into a grid. Each cell in the grid can contain a single item. However, the user can easily add multiple items by placing a container into a cell, and placing other items into the container.

Grid layout is familiar to anyone who has used HTML tables, Word tables or Excel: data is divided into a series of rows and columns. Items can span both rows and columns. The grid layout is ideal for many simple reports and dashboards. Grids help align report items for a clean layout. The "Grids" section below explains how this feature works in BIRT.

The grid section is divided into rows and columns. Rows grow or shrink depending on content. Columns ensure that items line up vertically. Columns can also grow or shrink depending on their contents.

The following terminology applies to grids:

The grid layout is ideal for reports that will be exported to Excel or shown on the web.

The grid layout can be applied to a list to align column headings with detail rows. It can be applied to a dashboard to create a clean, organized layout. It can also be applied to the entire report to align data in a group of dashboards and lists.

Benefits

Grid layout is a well-understood, powerful way to simplify the layout of some or all of the report.

To understand why, simply consider a tool that provides only free-form layout. The simplest report layout is to place text onto lines, and fields into columns. A layout that supports just (x, y) positioning forces the user to manually align controls vertically and horizontally. Typical tools provide an align option to help with this ? the user can select a set of elements and cause them to be aligned with the same left or right side, or the same top or bottom position. However, manual alignment is not "sticky." If the user decides to move the line or column position, he must manually move all the affected elements to the new location. The user must determine the affected controls manually.

Baseline alignment is very difficult with free-form layout. The developer must create the alignment manually though visual inspection and trial-and-error.

Another key limitation of free-form layout is the difficulty of aligning text along a baseline. Typical reporting elements are sized to a box that encloses the entire text, hence the baseline is somewhere in the middle of the element. The actual position depends on the specific font, font size, and the output device. Therefore, baseline alignment is virtually impossible using free-form layout. The best the developer can do is to eyeball the alignment to get close to the desired result.

Grid layout avoids the problems of free-form layout:

Grids also make it very easy for the developer to create a simple report by dragging elements into the report design. The grid ensures that report items are aligned, and automatically sizes the columns to fit the contents.

Visual Appearance

The developer can set a number of properties for the grid as a whole.

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.

Slot Detail

columns Slot

Describes the columns that make up the grid.

Details

Display Name: Columns
Since: 1.0
XML Element: None. (The contents appear directly within the container element.)
Contents: List of Column
Default Style: None

Description

This property describes the columns within the table. This property is optional. If omitted, BIRT infers the columns from the table structure itself, and BIRT will size the columns based on their contents. If provided, then the table must contain no more than the number of columns described. Use this property when you want to control the size, color, border, or other properties of each column.

See Also

The Column Definition structure in the ROM List & Table Specification.


rows Slot

Any number of row entries.

Details

Display Name: Rows
Since: 1.0
XML Element: None. (The contents appear directly within the container element.)
Contents: List of Row
Default Style: None

Description

Contains a list of the rows that make up the grid. Grids are defined in "row-major" format: as a list of rows that contain cells.