# Text

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

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

## content

The text for the item.

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

Resource key for the content.

## contentType

The formatting within the text: HTML or plain text.

### Choices

- auto: BIRT will infer the format as explained below.
- plain: Plain text with no formatting.
- 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.

### See Also

## onCreate

Script executed when the element is created in the Factory.

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

## onPrepare

It is for a script startup phase. No data binding yet. The design of an element can be changed here.

### Description

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.

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