Eclipse BIRT Report Object Model (ROM)

Text Element

Element Overview

Displays a multi-line block of text defined within the report. Can contain embedded formatting and value expressions.

Details

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

Property Summary

content
The text for the item.
contentID
Resource key for the content.
contentType
The formatting within the text: HTML or plain text.

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

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, display, fontFamily, fontSize, fontStyle, fontVariant, fontWeight, highlightRules, letterSpacing, lineHeight, marginBottom, marginLeft, marginRight, marginTop, masterPage, orphans, paddingBottom, paddingLeft, paddingRight, paddingTop, pageBreakAfter, pageBreakBefore, pageBreakInside, showIfBlank, textAlign, textIndent, textLineThrough, textOverline, textTransform, textUnderline, verticalAlign, whiteSpace, widows, wordSpacing

Description

The text item allows the developer to provide the text as part of the report design. The text can be localized. Text can be in HTML or plain text format. HTML text can contain placeholders for data and expressions: something line the mail merge feature of a word processing program. "Mail merge" is feature in which a standard block of text contains "place holders" for data retrieved from a database. It is often used to create form letters, or to format specific blocks of text within a report. For example, a report can use the text item to display a single line with the US-style city/state/zip address line:

<value-of>row.city</value-of>,
<value-of>row.state</value-of>
<value-of>row.zipcode</value-of>

Which might appear as:

South San Francisco, CA 94080

Another example is "mail-merge", i.e., to incorporate personalized data into a block of text. Mail-merge is especially powerful when combined with sections to create conditional paragraphs that further customize each letter.

The Text item provides many powerful features:

The text object is designed to allow continuous flow of text. Creating the same effect with a set of report items (such as labels and data items) has the well-known problems that the appearance varies depending on characteristics of the printer or display format. (Font widths & heights vary across presentation formats, making it difficult to align free-form labels and data items.) The user can combine a series of text elements, each in a separate section, to create conditional blocks of text.

BIRT leverages HTML and other open standards for rendering. For the most part, formatting within a block of text is simply passed to the browser or other formatting engine for processing.

A text item can be used to create report headings and other textual content. Using a text item is often easier than using a grid, free-form or other container. With text, the item contains text instead of rectangular report items. Text is placed onto lines. Lines grow and shrink depending on the size of their contents just as in Word or HTML. Text can be centered, or can be left or right justified. ROM provides control over line spacing, paragraph spacing and similar properties.

For example:

<center><b><span style=�font-size: larger�>
Monthly Sales Summary</span><br>
For the month of:
<value-of>Date.monthName( params.MonthParam )</value-of>,
<value-of>Date.year( params.MonthParam )</value-of>
<\b></center>

Displays a report title that looks like this:

Monthly Sales Summary

For the month of: November, 2004

See Also

Label Item element

Multi-line Data element

Style element, especially the Font and Text properties.

HTML Support section below.

Embedded Expressions section.

Property Detail

content Property

The text for the item.

Details

Type: literalString
Since: 1.0
Required: No
Display Name: Content
JavaScript Type:
Default Value: None
Inherited: Yes
Runtime Settable: No
Property Sheet Visibility: Visible
Property Sheet Group: Top

Description

The text for the item. See the contentType property for how to identify the text formatting. The text can be externalized.

See Also

 


contentID Property

Resource key for the content.

Details

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

contentType Property

The formatting within the text: HTML or plain text.

Details

Type: choice (textContentType)
Since: 1.0
Required: No
Display Name: Content type
JavaScript Type:
Default Value: auto
Inherited: Yes
Runtime Settable: No
Property Sheet Visibility: Visible
Property Sheet Group: Top

Choices

NameDisplay Name ValueDescription
auto Auto auto BIRT will infer the format as explained below.
plain Plain plain Plain text with no formatting.
html HTML html Formatting using a subset of HTML tags.

Description

The user can explicitly identify the format of the text using the Content Type property. Or, the user can set the property to "auto", (or omit the property) and BIRT will infer the format from the text itself.

BIRT determines the text format by examining the first few characters of the string. If the first characters are "<HTML>" (in either upper case or lower case), then the string is assumed to be HTML. Otherwise, the text is plain text. Any white space before these characters is ignored. That is, "<html>" and "   <html>" are both taken to indicate that the text is formatted in HTML.

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.