Eclipse BIRT Report Object Model (ROM)
Grid Element
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 |
ACLExpression, allowExport, bookmark, bookmarkDisplayName, boundDataColumns, cascadeACL, comments, cube, customXml, dataBindingRef, dataSet, displayName, displayNameID, eventHandlerClass, extends, height, multiViews, name, newHandlerOnEachEvent, paramBindings, propertyMasks, pushDown, refTemplateParameter, style, toc, userProperties, viewAction, visibility, width, x, y, zIndex
backgroundAttachment, backgroundColor, backgroundImage, 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, paddingBottom, paddingLeft, paddingRight, paddingTop, pageBreakAfter, pageBreakBefore, pageBreakInside, showIfBlank, stringFormat, textAlign, textIndent, textLineThrough, textOverline, textTransform, textUnderline, timeFormat, verticalAlign, whiteSpace, widows, wordSpacing
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.
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.
The developer can set a number of properties for the grid as a whole.
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 |
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 |
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 |
Script executed when the element is created in the Factory.
None obj.onCreate( )
Since: | 1.0 |
Context: | factory |
Arguments: | None |
Return Type: | None |
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.
None obj.onPageBreak( )
Since: | 2.1 |
Context: | presentation |
Arguments: | None |
Return Type: | None |
It is for a script startup phase. No data binding yet. The design of an element can be changed here.
None obj.onPrepare( )
Since: | 2.0 |
Context: | startup |
Arguments: | None |
Return Type: | None |
It is for a script startup phase. No data binding yet. The design of an element can be changed here.
Script executed when the element is prepared for rendering in the Presentation engine.
None obj.onRender( )
Since: | 1.0 |
Context: | presentation |
Arguments: | None |
Return Type: | None |
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.
Describes the columns that make up the grid.
Display Name: | Columns |
Since: | 1.0 |
XML Element: | None. (The contents appear directly within the container element.) |
Contents: | List of Column |
Default Style: | None |
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.
The Column Definition structure in the ROM List & Table Specification.
Any number of row entries.
Display Name: | Rows |
Since: | 1.0 |
XML Element: | None. (The contents appear directly within the container element.) |
Contents: | List of Row |
Default Style: | None |
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.