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

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

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

### Style Properties

backgroundAttachment, backgroundColor, backgroundImage, backgroundPositionX, backgroundPositionY, backgroundRepeat, bidiTextDirection, 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:

- Ability to enter formatted text that contains markers for data fields, expressions, and so on. When run, the value of each field is concatenated with any static text to produce the final output.
- Control text formatting on a character-by-character basis within a single text control. For example, displaying one word in a paragraph in a different font and color from the rest.
- Automatically adjust element size based on content.
- A single text element can span multiple pages to accommodate large amounts of text.
- Specify formatting using embedded HTML.

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

Name | Display Name | Value | Description
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.

## hasExpression Property

### Details

Type: | boolean
Since: | 2.5
Required: | No
Display Name: | Has expression
JavaScript Type: |
Default Value: | true
Inherited: | Yes
Runtime Settable: | Yes
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.