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

### Property Summary

caption
captionID
summary

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

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, backgroundImageType, backgroundPositionX, backgroundPositionY, backgroundRepeat, backgroundSizeHeight, backgroundSizeWidth, bidiTextDirection, 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, overflow, 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:

- Grid: a tabular layout with a fixed set of columns and variable number of rows. (Contrast this with a matrix that can have a variable set of columns.)
- Column: a vertical slice though the grid. Columns help organize the layout, but do not represent a specific bit of data as they do in matrices.
- Row: a horizontal slice through the grid.
- Cell: a point at which a row and column intersect. A cell can span rows and columns.

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:

- Automates the task of aligning report elements onto lines.
- Automates the task of aligning elements vertically into columns.

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.

- Style. The style defines the font to use within grid cells, the border style for the grid, fill color, and so on.
- Fixed or variable size. A grid will normally adjust based on the available space on the page. When viewed on the web, the grid columns will expand to make use of the full width of the browser window in the expected way.
- Row alignment: how to align items within a row. Options are top, middle, bottom or baseline (described below).

# Property Detail

## caption Property

### Details

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

## captionID Property

### Details

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

## summary Property

### Details

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

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