Eclipse BIRT Report Object Model (ROM)

List Element

# Element Overview

This section describes the list itself.

### Details

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

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

header
  Sections that appears before the first row of the list.
groups
  Groups for the report.
detail
  Sections to print for every row in the query.
footer
  A section that appears after the last row of the report.

### Inherited Properties

bookmark, boundDataColumns, comments, customXml, dataSet, displayName, displayNameID, eventHandlerClass, extends, filter, height, name, paramBindings, propertyMasks, refTemplateParameter, repeatHeader, sort, style, toc, userProperties, viewAction, visibility, width, x, y

### Style Properties

backgroundAttachment, backgroundColor, backgroundImage, backgroundPositionX, backgroundPositionY, backgroundRepeat, 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, paddingBottom, paddingLeft, paddingRight, paddingTop, pageBreakAfter, pageBreakBefore, pageBreakInside, showIfBlank, stringFormat, textAlign, textIndent, textLineThrough, textOverline, textTransform, textUnderline, verticalAlign, whiteSpace, widows, wordSpacing

### Description

The list item creates a banded presentation of a set of data rows. The data in each band can be in any of the supported section types: grid, free-form, text, chart and so on. A list is composed of a series of bands. Each band can contain any number of sections. The sections print sequentially. Or, the user can attach conditions so that only one of the sections prints for any given list or row.

A list can appear as a top-level section (or as a subsection within another top-level list). If so, then the bands fill the entire width of the page. A list can also appear within a container (grid, table cell, free-form, etc.). In this case, the list width is fixed. The list height will grow as large as needed to display the list contents.

### See Also

Table element

# 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

## header Slot

Sections that appears before the first row of the list.

### Details

Display Name: | Header
Since: | 1.0
XML Element: | `header`
Contents: | List of Data, ExtendedItem, FreeForm, Grid, Image, Label, List, Table, TemplateReportItem, Text, TextData
Default Style: | list-header

### Description

The header band appears before the first detail row of a list. This band contains any number of sections. Sections appear sequentially one after another, or can be selected conditionally.

The header normally appears whether the report contains any data rows or not, but the user can change this behavior using expressions.

Report items within the header slot have visibility to the entire result set. If the header contains a simple element such as a data item, then it will display values from the first row. If the header contains a chart, then the chart displays rows from the entire data set. If the header displays an aggregate, then the aggregate is computed over the entire data set.

## groups Slot

Groups for the report.

### Details

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

### Description

Groups for the report. The outermost group appears first in the list, the innermost group appears last. Each group has a group key, a header, a footer and more.

### See Also

List Group element

## detail Slot

Sections to print for every row in the query.

### Details

Display Name: | Detail
Since: | 1.0
XML Element: | `detail`
Contents: | List of Data, ExtendedItem, FreeForm, Grid, Image, Label, List, Table, TemplateReportItem, Text, TextData
Default Style: | list-detail

### Description

The detail band contains the sections to print for each row within the list. The list creates a separate instance of the detail band for each row. The detail band normally contains simple elements such as a data item.

The detail band can also contain a nested list or table. In this case, the nested list or table is repeated for each row in the outer list. This is hand to create subreports. For example, outer report displays a list of customers, the inner prints a form letter that contains a list of the customer’s sales this month.

## footer Slot

A section that appears after the last row of the report.

### Details

Display Name: | Footer
Since: | 1.0
XML Element: | `footer`
Contents: | List of Data, ExtendedItem, FreeForm, Grid, Image, Label, List, Table, TemplateReportItem, Text, TextData
Default Style: | list-footer

### Description

The header band appears after the first detail row of a list. This band contains any number of sections. Sections appear sequentially one after another, or can be selected conditionally.

The footer normally appears whether the report contains any data rows or not, but the user can change this behavior using expressions.

Report items within the footer slot have visibility to the entire result set. If the footer contains a simple element such as a data item, then it will display values from the last row. If the footer contains a chart, then the chart displays rows from the entire data set. If the footer displays an aggregate, then the aggregate is computed over the entire data set.