Eclipse BIRT Report Object Model (ROM)
Text Element
| 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 |
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, 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
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
Label Item element
Multi-line Data element
Style element, especially the Font and Text properties.
HTML Support section below.
Embedded Expressions section.
The text for the item.
| 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 |
The text for the item. See the contentType property for how to identify the text
formatting. The text can be externalized.
Resource key for the content.
| 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 |
The formatting within the text: HTML or plain text.
| 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 |
| 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. |
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.
| 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 |
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.